The settings you apply when creating line items to capture bids coming in from the header bidding process are typically different from those you apply when creating line items for house ads. This document will walk you through some of the differences, and outline requirements and recommendations for creating line items to work with Prebid.
Manually configuring ad server elements for Prebid can be a fair amount of work. If you’re using Google Ad Manager (GAM), consider using our official command line tool, Prebid Line Item Manager, to create the setup. Using this tool may save you time and help you avoid mistakes.
Line items (and creatives) must, at some level, be associated with advertisers. When you create line items to capture Prebid bids, you won’t know who the actual advertisers are. Instead you need to create generic advertisers in your ad server that are used for Prebid. For example, you can create an advertiser named “Prebid Advertiser.” Or if you’re using Send All Bids, you can create one advertiser per bidder, such as “Prebid BidderA,” “Prebid BidderB,” etc. You then associate your line items and creatives with those advertisers.
Depending on your ad server, line items are typically grouped within orders under each advertiser.
You have many options for the way in which you set up your line items. The following are Prebid requirements, and also some recommendations, to ensure bids are captured correctly and to make keeping track of your header bidding line items easier.
These tables show the Prebid line item recommendations and requirements. The following sections provide more details on each.
Required
| Detail | Requirement |
|---|---|
| Line Item Type | Price Priority (depending on your ad server) |
| Key Value Pricing | Include the number of decimal places that are defined in the price granularity precision. Normally this is two decimal places, e.g. hb_pb=0.50 or hb_pb=1.00 |
Recommended
| Detail | Recommendation |
|---|---|
| Line Item Groups | Determine the number of containers you’ll need to store the line items based on price granularity, number of bidders, and ad server restrictions. Name your group in the format Prebid, format, bidder name (for Send All Bids), and unique number; for example, Prebid - banner - BidderA - 1. |
| Line Item Name | Name each line item for the header bidding price bucket. Use the naming pattern Prebid, mediatype, bidder (for Send All Bids), and price bucket; for example, Prebid - banner - BidderA - 1.50. |
| Creative Name | In the creative name, include Prebid, the media type and the size (if applicable), and a unique identifying number (if more than one creative of a given size is attached to the line item). If using Send All Bids, also include the bidder name; for example, Prebid - banner - BidderA - 1x1 - 1. |
| Start and End Dates | Start immediately, no end date |
| Priority | Above house ads but below directly sold ads |
| Impression Goal | None |
| Media Types | Group media types by price granularity. This typically means you can group banner, outstream video, and native together but video will be a separate set of line items. |
If your ad server supports it, you should set your line item type to Price Priority, which will let it compete with bids from other sources.
When you enter your key values for price, you must include the number of digits following the decimal point that are specified with your price granularity. This is known as the precision value. For example, if Prebid is configured with a precision of two decimal places, then when you enter a value for the key hb_pb you must include two decimal places in your value: 0.50 or 1.00 rather than 0.5 or 1. If you don’t include the correct number of decimal places, your line item will not match any header bidding values.
For predefined Prebid price granularities the precision is 2; for custom price granularities this value can be defined in your Prebid configuration.
Engineering instructions for setting the precision value can be found in setConfig Price Granularity.
See Key Values for general information about key value pairs.
If you are sending all bids to the ad server, you’ll most likely want to group your line items by bidder. (In Google Ad Manager this means creating at least one set of orders per bidder, with that bidder’s line items attached to the order.) This allows each group to have a set of line items that use the same targeting keywords, all of which include the bidder’s name. For example, if you are working with BidderA, all line items within a group would use the key hb_pb_BidderA in the line item’s key-value targeting, and hb_adid_BidderA in the attached creative.
Depending on your ad server and the number of line items you’re creating, you might need more than one group per bidder. For example, suppose you need to create 2000 line items for one bidder. If GAM is your ad server, you’re allowed only 450 line items per order, so you will need five orders per bidder to store the 2000 line items, for a total of 25 orders.
We recommend naming the group to include “Prebid”, media type, the bidder name, and also a number or other identifier if you need more than one group per bidder. For example, Prebid - banner - BidderA - 1. For Send Top Price Bid you can omit the bidder name: Prebid - banner - 1.
Because you’ll be creating one line item per price within each price bucket, it’s helpful to name your line items based on the price. It can also be helpful to include the mediatype, since different types of media could be priced the same. Some examples include Prebid - banner - 1.00, Prebid - video - 1.50, etc. If you’re sending all bids, include the bidder code: Prebid - banner - BidderA - 1.00, Prebid - banner - BidderA - 1.50.
We recommend naming creatives to include the media type, size (where applicable), and a number if there is more than one. For example, Prebid - banner - BidderA - 1x1 - 1; Prebid - video - BidderA - 1.
With header bidding, start and end dates of the actual ad campaigns are controlled by the header bidding demand partners. The demand partners check their inventory and bid for an ad slot based on campaigns running on their systems. The line items you’re creating are generic and immortal line items created to capture a bid from a campaign your demand partner will be running at some point in the future.
What this means is that you typically don’t want to include an end date in your line items. Your line item will always be active to read in bids coming from your demand partner.
Set your start date to begin immediately.
Unless you’re working with deals, bids received from header bidding will typically have a priority lower than directly sold ads but higher than any competing house ads.
We recommend you do not set an impression goal. Because these are general line items with (typically) no end date, there’s no need to set a goal.
Prebid supports many media types, and you can set up a single line item with multiple types. The media types you choose can impact the way in which you decide to organize your line items.
Grouping media types within line items is typically dictated by the pricing structure:
You must set a key value for each format used by an ad unit using the hb_format (or hb_format_BIDDER) key and setting its value to the appropriate format. For example, if the ad unit is set up as a banner ad, you would target hb_format=banner (along with the price, such as hb_pb=1.00). If your ad unit supports multiple types, set the key value to include all types: hb_format in banner,native.
Here’s an example that encapsulates a number of the key decisions outlined in this document. In this scenario, we’ve made the following decisions:
The granularity we’ve chosen means we’ll be creating 2000 line items for banner and 1000 line items for video. Those line items will be named as shown here:
… other banner orders up to 20.00 …
If we had chosen Send All Bids (the Prebid default), every element shown above would be recreated for each bidder, and each name would include the bidder name. For example: