Before You Start

Here are a few things to understand and to decide before implementing Prebid.js. Make sure you understand how Prebid.js works before moving on.

1: Decide on price bucket granularity

With pre-bid, you’ll need to setup line items to tell your ad server how much money the “bidder” demand is worth to you. This process is done via key-values.

Example:

  • Prebid.js is going to call your bidders for their price, then pass it into your ad server on the query-string. You want to target this bid price with a line item that earns you the same amount if it serves.

  • If you had 1-line item for every bid at a penny granularity of $0.01, $0.02, $0.03, …, 1.23, …, $4.56 you’d need 1,000 line items just to represent bids from $0-$10. We call this the “Exact” granularity option.

  • Creating 1,000 line items can be a hassle, so publishers typically use price buckets to represent price ranges that matter. For example, you could group bids into 10 cent increments, so bids of $1.06 or $1.02 would be rounded down into a single price bucket of $1.00.

Our recommendation is to start with $1 or 10 cent granularity until you’re more comfortable with Prebid.js. At $1, you only need to setup 10-20 line items – easy. When you’re ready, get more granular with the price buckets to improve yield.

Note that DFP has an order object limits of containing up to 450 line items (including archived line items). If you are designing your own granularity setup, make sure you do not exceed that amount. Or, you can find the recommended pre-configured granularities here.

Action Item: Once you have decided the price granularity, review this example page with your dev team to learn how to set price granularity on the page.


2: One set of line items for all bidders vs. for each bidder

A. One set of line items for ALL bidders

One set of line items for all bidders is the recommended way of setting up your line items. Choose this option if you prefer an easier, low-maintenance setup:

  • It’s quicker and easier to setup, because you only have to create one set of line items.

  • It’s easier to maintain because adding more bidders requires no change to your line item setup.

  • It’s less error-prone because you only need to maintain 3 keywords:

Default Key Scope Description Example
hb_pb Required The price bucket. Used by the line item to target. 2.10
hb_adid Required The ad Id. Used by the ad server creative to render ad. 234234
hb_bidder Required The bidder code. Used for logging and reporting to learn which bidder has higher fill rate/CPM. rubicon

Action Item: For instructions on setting up pre-bid with one set of line items for all bidders, see Send Top Bid to Ad Server - Step by Step guide to DFP setup.


B. One set of line items for EACH bidder

Choose one set of line items for each bidder if you:

  • Have to rely on line item reporting (not query string reporting) to get winning bid by bidder analytics
    • With one set of line items for all bidders, Prebid.js only sends the highest bid to the ad server (the decision logic of choosing the highest bid can be customized by you). This is sufficient if the winning bids matter the most to you. For example, a bidder bidding 100% of time but losing in every auction still has a fill rate of 0%. However, if having access to all bid information is important to you, use one set of line items for each bidder.
  • Require bid landscape data for header bidding partners
    • With one set of line items for all bidders, Prebid.js sends the bidder information (Which bidder has the highest price) via a keyword bidder=bidder_name. To run a report to attribute winning bids to bidders, you will need to rely on your ad server’s keyword reports. DFP supports this, but some ad servers do not. DFP does not support running reports for more than 2 keywords. Therefore, if you have existing reports that already rely on keywords, and you want to add a winning bid by bidder dimension, use one set of line items for each bidder.
  • Requires setting more keyword targeting within your ad server. The below keys are targeting are required for each of your header bidding partner.

Important: DFP has a key-value key character limit of up to 20 characters. Some of the keys without truncation will exceed 20 chars (To date only Index Exchange’s keys need attention). Prebid.js automatically truncates the key length to 20 characters. For example, hb_adid_indexExchange is truncated to hb_adid_indexExchang (the 21st character e is truncated). Note that the key is case-sensitive. To get the exact key-value keys for each bidder, find them at Bidder Params.

Default Key Scope Description Example
hb_pb_BIDDERCODE Required The price bucket. Used by the line item to target. Case sensitive and truncated to 20 chars. The BIDDERCODE is documented at Bidder Params. hb_pb_rubicon = 2.10
hb_adid_BIDDERCODE Required The ad Id. Used by the ad server creative to render ad. Case sensitive and truncated to 20 chars. The BIDDERCODE is documented at Bidder Params. hb_adid_indexExchang = 234234
hb_size_BIDDERCODE Optional This is not required for adops. Case sensitive and truncated to 20 chars. hb_size_appnexus = 300x250

Action Item: For instructions on setting up pre-bid with one set of line items for each bidder, see Send All Bids to Ad Server - Step by Step guide to DFP setup.


3: Work together with your dev team

Implementing header bidding requires much more collaboration with your dev team than normal Ad Ops setup. For example:

  • Setting up price granularity requires you and the dev team working together to ensure the price buckets match. We have seen cases when the code on page sends $0.10 increments, while the line item setup expects $0.50 increments. This results in the ad server not catching 80% of the bids.