Header Bidding with Prebid: How It Works and Why It Breaks

Header bidding lets a publisher offer the same impression to many demand sources at once, then choose the best result, instead of asking them one at a time in a fixed order. Prebid is the open-source standard for doing this. Its power is also the source of its difficulty: it runs in the visitor's browser, depends on several third parties, interacts with the ad server, and has to finish before the page feels slow. This guide explains the flow, a minimal setup and, most usefully, how to diagnose problems.

The auction flow

1. Prebid loadsThe Prebid library, with the bidder adapters you chose at build time, loads on the page, typically asynchronously.
2. Ad units are declaredEach slot is described by an ad unit: a code, the media types and sizes, and the list of bidders with their parameters.
3. Bid requests go out in parallelEach adapter sends a request to its demand partner, either directly from the browser or through a server-side Prebid Server.
4. Responses are collectedBids that arrive before the bidder timeout are accepted. Late or invalid bids are dropped.
5. A winner is chosen per slotPrebid compares the valid bids, after applying floors and any adjustments, and picks the highest.
6. Targeting is set on the ad server requestThe winning bid's price bucket and identifiers are passed as key-values.
7. The ad server decidesThe ad server (commonly Google Ad Manager) compares the header-bidding price with its own direct and programmatic demand.
8. RenderIf the header-bidding bid wins, a Prebid creative in the ad server calls back to Prebid to render the winning ad.

A minimal working setup

var pbjs = pbjs || {};
pbjs.que = pbjs.que || [];
var googletag = googletag || {};
googletag.cmd = googletag.cmd || [];

var PREBID_TIMEOUT = 1500;      // bidders must respond in this time
var FAILSAFE_TIMEOUT = 3000;    // ad server is called regardless after this

var adUnits = [{
  code: "div-gpt-ad-top",                       // must match the GPT slot div id
  mediaTypes: { banner: { sizes: [[300, 250], [300, 600]] } },
  bids: [
    { bidder: "appnexus", params: { placementId: 13144370 } },   // test placement from the docs
    { bidder: "exampleBidder", params: { siteId: "abc123" } }    // illustrative only
  ]
}];

pbjs.que.push(function () {
  pbjs.setConfig({
    bidderTimeout: PREBID_TIMEOUT,
    priceGranularity: "medium",                 // $0.10 buckets up to $20
    enableSendAllBids: false
  });
  pbjs.addAdUnits(adUnits);
  pbjs.requestBids({ bidsBackHandler: sendAdserverRequest });
});

var adserverRequestSent = false;
function sendAdserverRequest() {
  if (adserverRequestSent) return;              // guard against double calls
  adserverRequestSent = true;
  pbjs.que.push(function () {
    pbjs.setTargetingForGPTAsync();             // sets hb_pb, hb_bidder, hb_adid, ...
    googletag.cmd.push(function () { googletag.pubads().refresh(); });
  });
}

setTimeout(sendAdserverRequest, FAILSAFE_TIMEOUT);

Four ideas in this snippet deserve attention:

• The ad unit code links Prebid's slot to the page's ad slot. If it does not match the slot's element id, bids never reach the ad server for that slot.
• bidderTimeout is the maximum time bidders have. A longer timeout allows slower bidders to participate, which can raise revenue, but delays the ad call and can harm user experience and viewability.
• priceGranularity controls how a bid price is rounded into a bucket. The built-in "medium" setting uses ten-cent steps up to twenty dollars. The ad server needs matching line items for those buckets.
• The failsafe timeout guarantees that the ad server is called even if Prebid hangs, so a problem with a single bidder cannot blank the page's ads.

The ad-server hand-off

When the auction ends, Prebid sets key-values on the ad slot, the key ones being:

In the ad server, you create line items that target hb_pb values, each priced at that bucket. If a bid's bucket has no matching line item, the ad server cannot select it and the bid is effectively lost, with no error. This is why changing price granularity requires updating the ad-server setup in step.

Client-side versus server-side

In client-side bidding, the browser sends a request to each bidder. It is transparent and easy to debug, but each extra bidder adds network connections and page weight. In server-side bidding, using Prebid Server, the browser makes one request and the server fans out to many bidders. That reduces browser load and tends to scale better with many partners, at the cost of cookie-matching complexity and slightly less visibility. Many publishers run a hybrid: a handful of high-value bidders client-side, and the long tail server-side.

Consent and identity

Prebid has modules that read the user's consent signal and pass it to bidders, and that gate which bidders and identifiers may be used. If a consent module is configured but your consent management platform has not yet produced a string when the auction starts, bidders may be blocked or may withhold bids. Test the auction both with consent granted and denied, and in each region where you have traffic. Identity modules add user identifiers to requests where permitted, which can increase bid rates and prices; they also add dependencies that need monitoring.

The failures that cost the most

Debugging with the browser console

Prebid is generous with debugging tools. Append ?pbjs_debug=true to a page URL to enable verbose logging, then use the global API and events:

// Add ?pbjs_debug=true to the page URL, then in the browser console:
pbjs.getBidResponses();            // every bid received, per ad unit
pbjs.getAllWinningBids();          // bids that rendered
pbjs.getAdserverTargeting();       // the key-values sent to the ad server

// Listen to events to see timing and failures
pbjs.onEvent("bidRequested", e => console.log("requested", e.bidderCode));
pbjs.onEvent("bidResponse",  b => console.log("response", b.bidder, b.cpm, b.timeToRespond + "ms"));
pbjs.onEvent("noBid",        b => console.log("no bid", b.bidder));
pbjs.onEvent("bidTimeout",   t => console.log("timeout", t.map(x => x.bidder)));
pbjs.onEvent("auctionEnd",   a => console.log("auction end", a.auctionId));

A good first investigation compares three views of the same auction. What did each bidder return (getBidResponses)? What did Prebid send to the ad server (getAdserverTargeting)? And what did the ad server choose? The difference between any two adjacent views shows where the value was lost.

Monitoring in production

Because header bidding is distributed across browsers, you rarely notice problems by looking at a single page. Collect auction data with an analytics adapter, and track at least these metrics by bidder, device type and region: bid rate, timeout rate, average CPM, response latency, and win rate. Alert on sudden changes, since a bidder silently failing or a new release that increases timeouts is far more common than a catastrophic outage. Finally, keep your ads.txt up to date for every bidder, since an unauthorised seller will reduce bids regardless of how well the technical setup works. See our guide to ads.txt and sellers.json.

Related guides

Further reading

• Prebid.org documentation
• Prebid.js developer docs