Mastering Prebid.js Ad Server Key Values: A Practical Guide for Publishers
Header bidding success hinges on more than just integrating Prebid.js; knowing how auction results are handed off to your ad server is crucial. At the heart of this process are key value pairs (KVPs), which determine which bids surface, how creatives get rendered, and how much insight you get for reporting.
Publishers who overlook key value management often face operational slowdowns, data overload, or missed revenue. This guide demystifies how Prebid.js ad server key values really work, and how you can configure them to align with your revenue, reporting, and scale needs.
Understanding Ad Server Key Values in Prebid.js
Ad server key values—commonly known as KVPs—are vital for connecting Prebid.js auctions to your ad server (such as Google Ad Manager, or GAM). After the auction, Prebid supplies a set of KVPs to the ad server. These influence which line item wins, ensure creatives render correctly, and power detailed reporting.
Types and Purposes of Key Values
Core Prebid KVPs include targeting elements (e.g., ‘hb_pb’ for price buckets, ‘hb_bidder’ for bidder identity, ‘hb_deal’ for PMP deals), display data (like ‘hb_adid’, ‘hb_size’), and reporting fields. The exact set of keys can impact whether ad server line items match, how accurately deal or bidder performance is tracked, and whether the right creative gets delivered.
Header Bidding and Ad Server Interaction
During a typical header bidding flow, Prebid.js collects bids, determines auction results, and attaches the relevant KVPs to each ad slot. The ad server then selects the best line item match, using those KVPs—especially the price bucket—to compete Prebid demand against direct-sold or other line items.
Configuring Key Value Output: Modes and Controls
How Prebid.js supplies KVPs to your ad server is highly configurable. Choosing the right mode influences reporting, revenue, and ad server performance—especially if you have many bidders or lots of ad units on a page.
Send All Bids vs. Top Bid Only
• ‘Send All Bids’ mode (enableSendAllBids: true) sends KVPs for every bid, giving full visibility and granular reporting in the ad server, but can increase KVP traffic significantly.
• ‘Top Bid Only’ mode (enableSendAllBids: false) passes just the winning bid KVPs, reducing complexity but limiting bidder-level transparency.
Advanced Controls for KVP Management
Prebid.js provides granular controls to customize which keys get sent:
– ‘targetingControls.alwaysIncludeDeals’ ensures PMPs or deals are represented in KVPs.
– ‘sendBidsControl.bidLimit’ can limit the ad server to the top N bids.
– ‘targetingControls.allowTargetingKeys’ and ‘allowSendAllBidsTargetingKeys’ restrict or expand the list of KVPs sent.
– ‘bidderSettings’ allows publishers to define completely custom KVP outputs.
Example: To only send winning bids with minimal keys—price, ad ID, and size:
pbjs.setConfig({
enableSendAllBids: false,
targetingControls: { allowTargetingKeys: [‘PRICE_BUCKET’, ‘AD_ID’, ‘SIZE’] }
});
Key Value Strategies for Real-World Publisher Setups
Different organizational needs and ad server limits shape how you should configure KVP output. Publishers must balance operational effort, ad server constraints, and reporting depth.
Line Item Structure: Per-Bidder vs. Shared
– Creating line items for each bidder increases transparency, reporting, and troubleshooting but can overwhelm ad server limits or make setup labor-intensive. This aligns best with ‘Send All Bids’ and is favored by publishers wanting deep analytics.
– Using a shared line item structure (one set of line items for all bids) reduces operational load but cuts down on visibility. This setup often pairs well with ‘Top Bid Only’ and bare-minimum KVP output.
Special Cases: Video and Mobile App
Video header bidding requires unique handling, such as the buildVideoUrl helper for GAM or custom KVP mapping for other ad servers. In mobile app environments, key value generation is typically managed at the Prebid Server level using stored requests.
Troubleshooting, Scalability, and Common Pitfalls
KVP mismanagement is a common source of header bidding problems—ranging from missing revenue to reporting inconsistencies or even ad delivery failures. The more complex your setup (multiple bidders, large-scale sites, varied deal structures), the more important robust KVP control becomes.
Troubleshooting Logic and Best Practices
• Always monitor what KVPs are actually sent to the ad server with either Prebid debug tools or ad server key inspector functions.
• Periodically audit both ad server (e.g., GAM) line item matching and Prebid KVP outputs after changes.
• Watch for ad server KVP limits—sending too many can cause dropped targeting or slowdowns.
Optimizing for Scale and Reporting
As your Prebid implementation grows, trim unnecessary KVPs to avoid hitting ad server limits and streamline reporting. Use deal-specific or format-specific KVPs only when strictly needed.
What this means for publishers
Ad server key value management directly impacts your revenue, analytics accuracy, troubleshooting efficiency, and the overall health of your programmatic stack. Well-calibrated KVP configuration can help you avoid common pitfalls—such as line item over-proliferation or misattribution—while still giving you the levers to optimize for yield, scale, and reporting.
Practical takeaway
Start by identifying what your organization needs from reporting, analytics, and operational scale. If you require bidder-level insight and can handle the extra setup, opt for ‘Send All Bids’ with per-bidder line items but closely monitor the amount of KVP data.
If simplicity or ad server constraints are top priorities, tune Prebid.js to only supply the essential KVPs for your line item setup. Regularly audit your ad server to ensure line item matching and reporting are working as intended—and revisit your configuration any time you add new demand partners or formats.
Prebid.js provides robust controls to adapt to your evolving needs—leverage them intentionally, and document your choices so future teams understand why you made each KVP decision.
