Understanding Prebid Key Values: A Practical Guide for Publishers

How Prebid Sends Bids to the Ad Server Using Key-Value Pairs

Prebid transmits bid information by appending a query string composed of key-value pairs (KVPs) to the ad server request URL. These KVPs carry crucial data such as bid prices, bidder identities, and ad identifiers. For example, a query string may look like this: `?hb_pb=1.50&hb_adid=234234&hb_bidder=bidderA` where `hb_pb` represents the bid price bucket, `hb_adid` marks the unique bid ID, and `hb_bidder` is the bidder’s code.

This mechanism allows header bidding bids to enter the ad server auction alongside traditional direct deals or other demand sources. To ensure a Prebid bid competes in the auction, line items must be configured in the ad server with key values matching those sent by Prebid. This is a fundamental integration point in header bidding implementations.

Example: Configuring Line Items in Google Ad Manager

Suppose you receive bids from BidderA with a price bucket of 1.50. Your GAM line item should contain targeting such as `hb_pb=1.50` and `hb_bidder=BidderA` to ensure this line item matches and competes during the auction. Without this matching, the header bidding bid would be ignored by GAM, leading to potential revenue loss.

Core Prebid Keys and Their Roles

Prebid uses a standard set of key-value pairs to convey bid details. Common keys include:

– `hb_pb`: The bid price bucket, adjusted for price granularity
– `hb_adid`: The unique ad ID used for rendering
– `hb_bidder`: The bidder’s identifier
– `hb_size`: The creative size for iframe resizing
– `hb_deal`: Deals or private marketplace IDs
– `hb_adomain`: Advertiser domains for reporting and verification

Depending on the media type (banner, video, native), some keys are essential for rendering creatives correctly, while others serve targeting or reporting purposes. Publishers should collaborate with their engineering teams to customize which keys are sent, based on their operational needs.

Sending Top Price vs. All Bids

Publishers can choose to send only the top price bid’s key values or all bids’ values to the ad server. Sending all bids leads to more key-value pairs like `hb_pb_BidderA`, `hb_pb_BidderB`, which can give granular insights but increase query string length. Sending the top price bid only simplifies the configuration but limits visibility into non-winning bids.

Using Key Values for Targeting, Reporting, and Rendering

Key values from Prebid serve multiple functions inside an ad server:

– Targeting: Matching line items to bids via key values ensures the correct demand competes in the auction.
– Reporting: Ad servers can use KVPs for performance reporting on bidders and deal activity.
– Rendering: Certain keys such as `hb_adid` and `hb_size` are required to display the winning creative properly.
– Special Usage: Keys like `hb_adomain` assist in troubleshooting by identifying advertiser domains.

Effective use of these keys requires careful setup. For example, failing to include `hb_adid` will prevent creatives from rendering correctly, while omitting `hb_bidder` can reduce reporting granularity.

Common Pitfall: Mismatched Targeting Keys

A frequent issue is line items with targeting keys not matching those sent by Prebid, causing no bids to win. For instance, if Prebid sends `hb_pb=1.20` but line items use price buckets like ‘1.15’ or ‘1.25’, the bid will not match. Consistent pricing buckets and key naming are essential.

Managing and Restricting Data Sent to Ad Servers

Prebid’s default configuration sends a fixed set of keys with every bid, but publishers might want to limit or customize these to reduce query string length or comply with ad server restrictions.

Large numbers of bidders and ad slots can produce very long query strings, risking truncation by the ad server and leading to missing or partial bid data. Prebid provides configuration options to:

– Specify which keys to include or exclude
– Limit the total length of the query string sent
– Prioritize key values from top bids and deals when truncation is necessary

Publishers should analyze typical query string lengths and adjust settings with engineering support to avoid data loss or auction errors.

Technical Controls and Best Practices

Use the `auctionKeyMaxChars` setting in Prebid’s targeting controls to cap query string length. Reduce the number of bidders or keys sent if the string is consistently too long. Collaborate with ad server and engineering teams to align on the keys needed for your operational and reporting requirements, ensuring consistent and reliable auction participation.

What this means for publishers

For publishers, mastering Prebid key values is crucial for operational control and maximizing auction competition. Proper configuration impacts ad revenue directly because improperly mapped key values lead to bids being ignored or creatives not rendering. It also streamlines reporting and troubleshooting efforts by providing clear, actionable data from header bidding partners. Finally, managing query string length helps maintain scalability and reliability in complex setups with many bidders or ad units.

Practical takeaway

Start by auditing your current Prebid key values and line item targeting to confirm they align perfectly. Work with your engineering team to customize which keys are sent to the ad server based on your reporting and rendering needs while keeping query string length manageable. Implement the `auctionKeyMaxChars` setting to avoid truncation issues and consider whether sending all bids or only the top price bid best fits your revenue and reporting goals. Regularly review performance and adjust configurations as your demand partners or ad server evolve to maintain optimal yield and operational efficiency.