What Is Prebid.js and How Do You Set It Up?

Prebid.js is an open-source JavaScript library maintained by Prebid.org that runs client-side header bidding auctions across multiple SSPs and DSPs before passing winning bids to Google Ad Manager. Over 300 bidder adapters are available. This article walks through the full setup: building your Prebid package, configuring ad units and bidder parameters, mapping key-value pairs in GAM, setting timeouts, and debugging live auctions.

If you need a refresher on the broader concepts, check out our comprehensive header bidding setup guide.

How Does the Prebid.js Auction Work?

Prebid.js executes a complete auction in the browser before your primary ad server makes its call. The auction runs in parallel with page rendering, and winning bids compete against AdX and direct-sold demand inside GAM.

The sequence in code: pbjs.requestBids() fires bid requests to every configured adapter. Each adapter sends a request to its SSP. Responses arrive within the bidderTimeout window. Prebid selects the highest bid per ad slot, sets targeting on the corresponding GPT slot via pbjs.setTargetingForGPTAsync(), and then googletag.pubads().refresh() fires the GAM request with Prebid's key-value targeting attached.

How Do You Build Your Prebid.js Package?

Go to prebid.org/download.html. Select your bidder adapters and modules. Download the compiled JavaScript file. Only include what you actually need.

• Bidder adapters: Add one adapter per SSP you work with. Common choices: appnexus (Xandr), rubicon (Magnite), pubmatic, indexExchange, openx, sovrn. Each adapter adds 5 to 15KB to the bundle. Six adapters typically produce a 60 to 100KB file.
• Modules: Prebid offers optional modules for consent management (GDPR TCF, US Privacy), price floors, user ID, and Prebid analytics. Include the consentManagement module if you serve EU traffic. Include the priceFloors module if you want Prebid to enforce floor CPMs. Skip modules you don't use.

The most common mistake: including 15+ bidder adapters and every available module. The resulting file exceeds 200KB and adds 300 to 500ms of script parse time. A bloated Prebid bundle defeats the purpose of header bidding by slowing the page enough to hurt Core Web Vitals. Start with 4 to 6 adapters. Add more only after confirming each one wins meaningful auction share.

How Do You Configure Ad Units, Bidders, and Timeouts?

Each ad unit in Prebid maps to a specific ad slot on your page. You define the slot's div ID, the allowed sizes, and the bidder configurations with SSP-specific parameters.

Here's the core configuration structure:

var adUnits = [{
  code: 'div-leaderboard',
  mediaTypes: {
    banner: { sizes: [[728, 90], [970, 250]] }
  },
  bids: [
    {
      bidder: 'appnexus',
      params: { placementId: 12345678 }
    },
    {
      bidder: 'rubicon',
      params: {
        accountId: 1234,
        siteId: 5678,
        zoneId: 91011
      }
    },
    {
      bidder: 'pubmatic',
      params: { publisherId: '987654', adSlot: 'leaderboard_top' }
    }
  ]
}];

Each bidder's params object uses SSP-specific fields. Magnite (rubicon) requires accountId, siteId, and zoneId. PubMatic requires publisherId and adSlot. AppNexus/Xandr requires placementId. Get these values from your SSP account manager or their self-serve dashboard.

Timeout Configuration

pbjs.setConfig({
  bidderTimeout: 1000,
  priceGranularity: 'dense'
});

Set bidderTimeout between 800ms and 1,200ms. Below 800ms, slower SSPs like Magnite and Index Exchange may not return bids in time, reducing auction competition. Above 1,200ms, the delay before GAM fires becomes noticeable to users and hurts LCP.

1,000ms is the standard starting point. Monitor bid response times per adapter using Prebid analytics. If a specific adapter times out on more than 20% of requests, either increase the timeout or remove that adapter.

Price granularity: Use dense ($0.01 increments up to $20) for maximum yield precision. The auto setting uses wider buckets that leave money on the table by rounding bid prices down.

How Do You Map Prebid Bids to Google Ad Manager?

Prebid passes three key-value pairs to GAM for each winning bid: hb_pb (the price bucket), hb_bidder (the winning SSP), and hb_adid (the creative ID). You need GAM line items that target these values.

1. Create key-values in GAM. Navigate to Inventory > Key-values. Create keys for hb_pb, hb_bidder, and hb_adid. Set hb_pb as a predefined value type with entries for each price bucket ($0.01 through $20.00 at $0.01 increments for dense granularity, or wider buckets if using auto).
2. Create Prebid line items. For each price bucket, create a line item with: type = Price Priority, rate = the bucket value (e.g., $5.00), key-value targeting = hb_pb = 5.00. The creative assigned to each line item uses Prebid's universal creative code, which renders the winning bidder's ad based on hb_adid.
3. Assign the Prebid universal creative. This is a single third-party creative script provided by Prebid.org that dynamically renders the correct ad for any winning bid. You create it once and assign it to all Prebid line items.

Creating line items manually for 2,000 price buckets is impractical. Use Prebid's Line Item Manager tool or third-party GAM automation tools (e.g., dfp-prebid-lineitems on GitHub) to generate them programmatically.

How Do You Debug Prebid Auctions on a Live Site?

Open Chrome DevTools (F12). In the Console tab, run pbjs.getBidResponses() to see all bids received for each ad unit. This shows you which SSPs responded, their bid prices, and response times.

Additional Debugging Commands:

• pbjs.getAllWinningBids() returns only the bids that won each auction slot.
• pbjs.getConfig() shows your current Prebid configuration including timeout and price granularity.
• pbjs.setConfig({ debug: true }) enables verbose console logging for every auction event: bid requests sent, responses received, timeouts, and GAM targeting applied.

Check for These Common Issues:

• No bids returned from a specific adapter. Verify the adapter's params values match what the SSP provisioned. A mistyped placementId or zoneId silently produces zero bids with no error message.
• All bids timing out. Your bidderTimeout is too low for your adapter set, or a slow adapter is blocking the auction. Enable debug logging and check response times. If one adapter consistently responds in 1,100ms and your timeout is 1,000ms, it never wins.
• GAM not serving Prebid creatives. Verify key-value targeting in GAM matches exactly. hb_pb=5.00 in Prebid must match hb_pb=5.00 in the line item targeting. A mismatch of 5.0 vs 5.00 causes silent failure.

Compare your winning bid eCPMs against CPM benchmarks by format and geo to assess whether your Prebid setup is competitive or leaving demand on the table. Publishers looking to offload latency-heavy adapters can move them to Prebid Server for server-side execution.