Prebid.js Setup Guide: From Zero to Your First Live Auction

Set up Prebid.js by launching one custom client-side build, one known-good display ad unit, a short bidder list, one defensible auction timeout, and GAM line items that match the hb_pb and hb_bidder values Prebid sends through GPT. Prove that path live first. Then expand bidders, formats, refresh logic, or Prebid Server only after the handoff is clean.

Key takeaways

• Use a custom Prebid.js build and keep only the adapters and modules you need for launch.
• Pick bidders based on measurable lift, not how many names you can add to the wrapper.
• Match Prebid price buckets, GPT sequencing, and GAM line items before you go live.
• Test for targeting, timing, and silent failures, not just whether bids appear in the browser.
• The first-week revenue risk usually comes from setup drift, not the auction itself.

Where Prebid.js sits in the header bidding stack

Prebid.js runs the browser-side auction before the ad server request. Google Ad Manager still decides what serves. Treat Prebid.js as the demand coordinator: it calls adapters, receives bids, and writes targeting. It does not traffic line items, host creatives, forecast delivery, or override GAM priority rules.

The first live auction has a fixed handoff. Load your custom Prebid.js build, define ad units, request bids from selected adapters, wait for the auction to close, call setTargetingForGPTAsync, and only then let GPT request the ad from GAM. Prebid.org’s developer documentation covers this basic impression flow and the related components in its getting-started materials Prebid.org documentation.

That boundary explains many first-launch failures. If bids appear in the browser but GAM serves a house line item, do not rebuild the wrapper first. Check whether hb_pb and hb_bidder reached the GPT slot, whether the matching GAM line item is eligible, whether the creative is attached, and whether a higher-priority campaign, protection, or size mismatch blocked it.

The practical division of labor

Prebid.js controls the auction request. It decides which bidder adapters get called for each ad unit, which media types are allowed, how long bidders have to respond, how bid prices are bucketed, and which key-values get written back for GPT to pass into GAM.

GPT controls the ad request into GAM. It owns slot definition, page-level ad request behavior, and the moment GAM receives the targeting. From there, GAM evaluates eligible line items, priorities, key-values, creative compatibility, roadblocks, frequency settings, competitive exclusions, protections, and direct-sold demand.

Use the clean operating model: Prebid collects bids and writes signals; GAM monetizes those signals under your trafficking rules. Keep that line sharp. Do not rebuild Prebid because a GAM line item targets the wrong ad unit, and do not change GAM priorities because an adapter is not firing in the browser.

When client-side Prebid.js is no longer enough

A pure client-side build works best when bidder count is controlled, page weight is reasonable, consent handling is already understood, and debugging can stay close to the browser. It starts to strain when every placement calls a long adapter list, mobile templates show visible latency, or a demand partner performs better through a server-side path.

That is where Prebid Server or a hybrid setup deserves a separate test. Playwire’s guide separates the Prebid ecosystem into Prebid.js for client-side, Prebid Server for server-side, plus Prebid Mobile and Prebid Video for other implementation needs Playwire. More server-side execution can reduce browser work, but it changes identity, reporting, troubleshooting, and partner configuration.

For a first launch on a mid-to-large U.S. publisher site, client-side Prebid.js is usually the safest way to get one controlled live auction running. The tradeoff is discipline. Every extra adapter, module, ad unit exception, and GAM mapping creates another place for latency, consent, targeting, or reporting to drift.

Build the wrapper the right way: install, customize, and keep it lean

Use a custom Prebid.js build with only the bidder adapters and modules needed for the first launch. MonetizationGuy’s implementation guide gives the same practical instruction: download a customized Prebid.js file that includes only the adapters you plan to use so the production file stays smaller MonetizationGuy. The open-source project and developer materials live under the Prebid.js GitHub and documentation ecosystem GitHub.

1. Start from the official project and documentation, not a copied wrapper from an old property. The GitHub prebid/Prebid.js repository describes Prebid.js as free, open source software and points developers to the documentation and working examples for implementation details GitHub prebid/Prebid.js.
2. Create a custom build instead of shipping unused bidder adapters. Monetization Guy’s implementation walkthrough makes this the first practical setup move: download a customized version that includes only the adapters you plan to work with so the file stays smaller and page load performance is easier to protect Monetization Guy.
3. Select only the launch-critical modules. For version one, that usually means bidder adapters, the media types you actually sell, consent support if your traffic requires it, currency handling if bids arrive in multiple currencies, and analytics only if someone will use the data during launch week.
4. Define ad units in a way that mirrors your GAM inventory. Use stable ad unit codes, real sizes, and bidder params that match signed partner agreements. Do not let development names like div-gpt-ad-test-1 leak into a production mapping that your ad ops team cannot recognize later.
5. Set price granularity before trafficking line items. GAM cannot match prices you never created line items for, and Prebid should not send buckets your ad server setup cannot monetize. If you use custom buckets, write down the top price, increment, currency assumption, and which line item range owns each bucket.
6. Decide whether currency conversion belongs in the first build. If all launch bidders transact in USD and your GAM network is priced in USD, keep currency handling simple. If you have cross-currency demand, configure it deliberately instead of letting reporting teams reconcile inconsistent bid values after launch.
7. Add consent management only as tightly as your legal and product requirements demand. If your site relies on a Consent Management Platform and IAB TCF signals, make the CMP path part of launch QA, not a later privacy task. Consent logic can change which bidders are called, which user IDs are available, and whether demand partners return bids.
8. Keep video out of the first web display launch unless the inventory is part of the actual release. Prebid Video is its own implementation lane in the broader Prebid ecosystem, and mixing it into a display-only go-live creates extra creative, renderer, player, and reporting checks that do not help the first auction.
9. Version the build and keep a changelog that ad ops can read. Record the Prebid.js version, adapters, modules, timeout, price granularity, and GAM mapping date. When revenue changes after a release, you need to know whether the wrapper changed, demand changed, or GAM changed.
10. Load the wrapper in the page sequence you plan to use in production. A build that works in a local example can still fail when your real site has lazy loading, infinite scroll, consent gating, single-page app routing, ad refresh rules, or competing scripts that touch GPT.

Keep the first build lean for operational reasons, not aesthetics. Fewer adapters mean fewer network calls to inspect, fewer bidder parameters to validate, fewer consent edge cases, and a smaller surface area for adapter-specific bugs. Add complexity after one placement proves that Prebid, GPT, and GAM agree on the same auction.

Choose bidders, set timeouts, and avoid the usual revenue mistakes

Minimal live auction skeleton: select a custom Prebid.js build that contains only the bidders you will call on launch, then include that file before the auction code. Define one display ad unit first, such as code: 'top_leaderboard', mediaTypes: { banner: { sizes: [[728,90],[970,250]] } }, bids: [{ bidder: 'yourBidder', params: { placementId: 'provided_by_partner' } }]. Use real bidder params from the partner, not placeholders in production.

Queue the auction logic through pbjs.que so it waits for Prebid to load: var pbjs = pbjs || {}; pbjs.que = pbjs.que || []; pbjs.que.push(function(){ pbjs.addAdUnits(adUnits); pbjs.requestBids({ timeout: 1000, bidsBackHandler: function(){ pbjs.setTargetingForGPTAsync(['top_leaderboard']); googletag.cmd.push(function(){ googletag.pubads().refresh([topSlot]); }); } }); });. The timeout value here is only an example; use the value your page test can defend.

Match the GPT sequence to the auction sequence. Define the GPT slot before you refresh it: googletag.cmd.push(function(){ topSlot = googletag.defineSlot('/1234567/site/top_leaderboard', [[728,90],[970,250]], 'div-gpt-top').addService(googletag.pubads()); googletag.pubads().disableInitialLoad(); googletag.enableServices(); });. The important rule is simple: do not make the GAM ad request until after setTargetingForGPTAsync has written the Prebid keys for that slot.

The cut rule for launch bidders

GAM trafficking checklist for the skeleton: create key-values for hb_pb and hb_bidder using the values your Prebid setup sends; traffic line items that target those values and the same ad unit; attach a Prebid creative that can render the winning bid using the auction ad ID; include every served creative size you allowed in the Prebid ad unit; confirm the line item priority does not lose to house or direct demand when you are trying to test Prebid delivery.

Pick first-launch bidders by placement fit and supportability, not by partner count. Keep a bidder only if its adapter fires, required params are present, responses arrive inside your timeout often enough to matter, bids map to GAM line items, and the partner has a clear role on that inventory. Refresh traffic needs the same discipline: sticky units, infinite scroll, and rapid refresh placements should start with a tighter bidder list until you can inspect latency and bid density by placement.

A practical comparison of setup choices before launch

Decision table for first-launch setup paths: Lean client-side launch: bundle-size impact is lowest because the custom build includes only required adapters and modules; latency risk is lowest among client-side options because fewer adapters run in the browser; debugging difficulty is lowest because adapter calls and targeting are visible in browser tools; GAM trafficking complexity is lowest because you start with one price-bucket pattern; launch safety is highest; best fit is a publisher that needs one clean live auction before expansion; source note: custom builds and working examples are covered in Prebid developer and GitHub materials Prebid.org documentation GitHub.

Broader client-side launch: bundle-size impact is higher because more adapters and modules ship to the browser; latency risk rises with more bidder calls; debugging gets harder because more no-bids, timeouts, and params overlap; GAM trafficking complexity rises if placements use different sizes or buckets; launch safety is medium; best fit is a team with proven bidder params and GAM templates already prepared; source note: Prebid’s component model and custom-build guidance support keeping only needed components Prebid.org documentation.

Hybrid Prebid.js plus Prebid Server: bundle-size impact can be lower in the browser for server-side demand, but setup complexity moves into server configuration; latency risk can improve on browser-heavy pages but depends on identity, partner setup, and routing; debugging difficulty is higher because part of the auction leaves the browser; GAM trafficking complexity is similar if the same targeting keys and buckets are used, but reporting reconciliation is harder; launch safety is medium to low for a first auction; best fit is a publisher that has already proven browser latency or page weight is the bottleneck; source note: Playwire separates Prebid.js and Prebid Server as different implementation paths Playwire.

Conservative staged launch: bundle-size impact starts low and grows only after QA; latency risk is controlled because each bidder or placement is added after the baseline; debugging difficulty stays manageable; GAM trafficking complexity grows in planned batches; launch safety is highest for multiple properties; best fit is a mid-to-large publisher with many templates, refresh rules, or business units that cannot absorb a noisy launch.

For most first launches, choose the lean client-side build or the conservative staged path. Both create a baseline you can trust. Once that first auction serves through GAM with the expected Prebid creative, adding a bidder or testing Prebid Server becomes a controlled experiment instead of a rescue job.

Broader paths earn their keep only after you identify the bottleneck. If browser timing is the problem, test hybrid demand on the slow template first. If price pressure is weak on a premium placement, expand bidder coverage there before touching lower-value inventory. If GAM rejects valid bids, fix trafficking before you change architecture.

Connect Prebid.js to Google Ad Manager without breaking the line item logic

Prebid.js monetizes only when its winning bid becomes GAM targeting that matches eligible line items and creatives. The browser can show a valid bid response, but GAM will ignore it if the hb_pb value has no matching line item, hb_bidder is not targeted correctly, slot mapping is wrong, or the ad request fires before targeting is set.

The core sequence is simple: define GPT slots, run the Prebid auction, set Prebid targeting for the relevant GPT slots, then make the GAM ad request. If GPT requests the ad before Prebid writes targeting, GAM evaluates the impression without the bid signals. Prebid’s developer materials and examples are the right anchor for this flow Prebid.org documentation.

Key-values and price buckets have to match exactly

Standard Prebid targeting keys are useful only if GAM is trafficked to receive them. For a basic display launch, hb_pb carries the price bucket, hb_bidder identifies the bidder, and the Prebid creative uses the auction ad ID to render the winning ad. Do not approve the code until ad ops can see those exact values in the browser and in GAM targeting.

The fragile piece is the price bucket. If Prebid rounds a bid into a bucket with no eligible GAM line item, the auction can look healthy in the browser and still fail commercially. The same failure happens when GAM uses a different key name, value format, ad unit, or match type than the values Prebid writes through GPT.

Do not leave price granularity as a developer-only setting. Ad ops needs the bucket structure before trafficking, and engineering needs the final key-value names before release. Prebid.org includes custom price granularity among its developer topics, which tells you bucket design belongs in implementation planning, not post-launch cleanup Prebid.org documentation.

GPT sequencing decides whether the auction counts

GPT is the pipe into GAM, so request timing determines whether Prebid targeting exists at decision time. Define the GPT slot, hold the initial request if needed, run requestBids, call setTargetingForGPTAsync for the slot, and then call display or refresh. If you refresh a slot later, run a fresh auction or deliberately choose a non-Prebid path for that refresh.

Single-page apps and infinite scroll templates make this easier to break. A newly injected slot needs its own GPT slot definition, Prebid ad unit mapping, auction, targeting write, and ad request. A refreshed slot needs fresh bid logic. Reusing stale hb_pb or hb_bidder values is dangerous because ads may still serve while auction integrity is wrong.

Keep slot naming consistent between Prebid ad units, GPT slots, and GAM ad units. If the Prebid ad unit code is top_leaderboard but the GPT request is tied to a different div or GAM path, the debug console may show both objects while GAM receives no usable Prebid targeting on the impression that matters.

The GAM mistakes that look like Prebid mistakes

The most expensive setup errors are usually plain trafficking mistakes. A line item targets the wrong GAM ad unit. The creative is missing. The creative size does not match the slot. A higher-priority campaign beats the Prebid line item during the test. hb_pb exists in Prebid but not in GAM. hb_bidder was created with a value format that does not match the bidder key sent from the page.

Another common failure is treating a bid response as proof the bid can serve. GAM still applies its own rules. Protections, labels, competitive exclusions, creative size mismatches, frequency settings, sponsorships, and higher-priority direct campaigns can all block a Prebid-backed line item even when the browser auction did its job.

Build one known-good test placement before you scale. Use one ad unit, one or two bidders, a narrow set of sizes, and a GAM setup you can inspect manually. For example, map top_leaderboard in Prebid to the GPT div for the same leaderboard slot, target hb_pb and hb_bidder in GAM, and confirm the Prebid creative renders through GAM before copying the pattern to other properties.

Testing before go-live: what to verify, what to ignore, and how to catch silent failures

Browser QA should prove the full chain, not just that an ad appeared. Check the Network panel for bidder requests, use pbjs.getBidResponses() to inspect returned bids, confirm pbjs.setTargetingForGPTAsync wrote hb_pb and hb_bidder, open Google Publisher Console to inspect the GAM slot, and use Professor Prebid as a fast visual check for auction calls and targeting. GeeksforGeeks identifies Professor Prebid as a Chrome extension for debugging and analyzing Prebid.js configurations GeeksforGeeks.

1. Open the real page template with browser dev tools and confirm that your Prebid.js file loads once, from the expected path, with the expected version. A duplicate wrapper can create conflicting auctions that look like random bidder behavior.
2. Use Professor Prebid to inspect ad units, bidder calls, bid responses, and targeting values. GeeksforGeeks describes Professor Prebid as a Chrome extension for debugging and analyzing Prebid.js configurations, which makes it useful for launch QA even if your deeper diagnosis still happens in dev tools Professor Prebid.
3. Check the network panel for bidder requests. Confirm that the intended adapters fire only on the intended placements, and that mobile, desktop, refresh, and lazy-loaded slots do not accidentally share the wrong bidder list.
4. Inspect the bid responses against your timeout. Separate true no-bids from late bids and blocked calls. A late response after the auction closes may appear in network logs, but it should not be counted as available demand for that impression.
5. Verify the targeting written by Prebid before GPT sends the ad request. Look for the price bucket, bidder, ad ID, and any placement-specific keys your GAM line items depend on. If targeting appears after the GAM request, your sequence is wrong.
6. Confirm the GAM request contains the expected key-values. Browser-side Prebid targeting is not enough; the values must travel in the ad request that GAM evaluates.
7. Test one line item at a known price bucket. Force a narrow condition where a bid should match, then verify that GAM serves the expected creative. This catches the difference between “auction works” and “ad server can deliver the auction winner.”
8. Run consent-state tests if your implementation depends on a Consent Management Platform. Test accepted, rejected, and no-choice states if those states exist on your site, and confirm that IAB TCF signals or CMP outputs change bidder behavior in the way your policy requires.
9. Watch the console, but do not chase every warning before you prove monetization. Launch blockers are missing wrapper load, missing bidder calls, empty targeting, GAM requests firing too early, creative render failure, and consent behavior that contradicts your requirements.
10. Run a limited live test on a small placement set before expanding across properties. Monitor latency, timeout misses, no-bid patterns, and GAM delivery for those placements rather than averaging the results into a sitewide number that hides the broken slot.

Silent failures cost more than hard failures because ads still render. A direct campaign, AdX line item, or house ad can fill the slot while Prebid demand never competes. Follow one impression from adapter request to bid response, from targeting write to GAM line item eligibility, and from creative selection to render. Revenue appearing somewhere is not proof the first live auction works.

The launch checklist that keeps first-week revenue stable

The first week after launch should measure stability before expansion. Review results by placement, device class, consent state, template, and GAM mapping. You are looking for repeatable auction behavior: adapters fire where expected, timeouts are explainable, hb_pb values match trafficked buckets, and the same slot does not alternate between clean Prebid delivery and missing targeting.

• Confirm the shipped bundle before traffic expansion: Prebid.js version, adapter list, modules, timeout, media types, currency handling, consent module behavior, and analytics configuration if used.
• Lock the first GAM mapping: ad unit names, key-values, price buckets, line item ranges, creatives, priorities, and any protections that can block header bidding demand.
• Track bid density by placement and device. A homepage top banner, a mobile mid-article unit, and an infinite scroll slot should not be judged from the same blended number.
• Watch timeout behavior separately from no-bid behavior. A bidder that never responds inside the auction window needs a different fix than a bidder that responds quickly but does not value the inventory.
• Review no-bid patterns by adapter. If one partner no-bids across every placement, check parameters and account setup before assuming weak demand.
• Check GAM delivery against Prebid targeting. If winning bids are present but the matching line items rarely serve, investigate ad server eligibility before changing the wrapper.
• Monitor refresh inventory with stricter scrutiny. Refresh can inflate request volume while adding latency and low-value auctions if every partner is called every time.
• Treat adapter updates as release events. After any Prebid.js build update, demand partner parameter change, or module addition, rerun the same known-good placement test from bidder call through GAM delivery.
• Set a cleanup review after real traffic accumulates. Remove bidders that add page cost without usable wins, narrow bidders to the placements where they compete, and document every cut so commercial teams do not re-add dead weight later.
• Decide whether the first build was too broad, too slow, or too fragile before adding features. Too broad means too many weak bidders; too slow means timeout and browser cost issues; too fragile means GAM or sequencing breaks under normal page behavior.

Ready to go live when these pass: one test placement serves a Prebid creative through GAM; hb_pb and hb_bidder values visible in the browser match eligible GAM line items; the creative renders in every allowed size; the ad request happens after setTargetingForGPTAsync; no higher-priority test conflict is masking the result; bidder params are real; timeout behavior is understood on desktop and mobile templates; rollback is simply disabling the wrapper or removing the test line items.

Frequently asked questions

Do you need Google Ad Manager to use Prebid.js?

No, but GAM is the most common pairing for publishers running Prebid.js at scale. The important part is that your targeting keys, line item priorities, creative setup, and price buckets line up with what Prebid sends back through GPT. If you use another ad server, the auction can still work, but the handoff logic and trafficking checklist change.

Should I start with client-side Prebid.js or Prebid Server?

Start with client-side if you want the fastest path to a controlled first launch, simpler browser debugging, and direct visibility into adapter calls. Move to Prebid Server or a hybrid setup only when browser latency, page weight, or mobile performance is the proven bottleneck. For a first build on a mid-to-large publisher site, client-side is usually the safer starting point.

How many bidders should be in the first build?

Use only the bidders you can justify on launch inventory. A practical first build is one or two proven partners on one test placement, then a controlled expansion by ad unit or property. Keep a bidder in production only if its params validate, it responds inside your timeout often enough to affect auctions, its bids map to GAM buckets, and your team can support its discrepancies.

What’s the first tool to use when bids don’t show up?

Professor Prebid is a useful first check because it shows the auction, adapter calls, and targeting in one place. After that, verify the GAM side: hb_pb, hb_bidder, line items, creative sizes, and price bucket alignment must match the values Prebid writes back through GPT. If bids appear in the browser but GAM serves something else, the failure is usually in the handoff.

What usually breaks a first live auction?

Troubleshoot a failed live auction in this order: confirm the custom Prebid build contains the adapter, confirm bidder params are present, confirm the request is not blocked by consent or page logic, confirm bids return before the timeout, confirm setTargetingForGPTAsync writes hb_pb and hb_bidder to the right GPT slot, confirm GAM has matching key-values and line items, then check creative compatibility and priority conflicts. Do not blame demand until the auction-to-GAM path is clean.

How we researched this

Sources consulted for this article:

• The Ultimate Guide to Prebid
• GitHub - prebid/Prebid.js: Setup and manage header bidding...
• Prebid.js Implementation: Step-by-Step Guide for Publishers
• Getting Started for Developers for Header Bidding
• Introduction to Prebid Tools | How to Launch and Manage Prebid?
• Prebid.js/README.md at master · prebid/Prebid.js · GitHub