Understanding Prebid Size Mapping: Responsive Ads and Label-Based Configuration for Publishers

Responsive advertising isn’t just a design trend—it’s a revenue and user experience essential. As users shift across devices, publishers need their ad setup to adapt seamlessly while ensuring optimal demand and efficient ad operations.

Prebid.js offers a robust approach to responsive ads through its size mapping module, leveraging ‘sizeConfig’ and labels. This guide explains how these tools work, common implementation patterns, and where publishers often go wrong—arming your ad ops team with the clarity it needs to build a scalable, error-resistant header bidding setup.

What Is Prebid Size Mapping?

Prebid’s size mapping refers to the configuration mechanism that lets publishers control which ad sizes are active on different screen widths and devices. Instead of hardcoding ad sizes, Prebid evaluates size rules dynamically, allowing for more flexible, responsive ad displays.

Why Responsive Matters in Header Bidding

With users moving between desktops, tablets, and phones, a one-size-fits-all approach to ad sizing kills performance. Misaligned or blank ads reduce viewability, frustrate users, and leave money on the table. Size mapping empowers granular control, helping ad slots reflect actual device and viewport characteristics.

How SizeConfig Works in Prebid.js

Publishers declare a global ‘sizeConfig’ object using `pbjs.setConfig`. Each rule in this object uses a CSS media query (like ‘(min-width: 1200px)’) to define which screen sizes are in play. For each matched query, supported ad sizes are activated, and relevant labels are applied. At bid time, Prebid queries the user’s device and activates the appropriate ad unit sizes based on the active labels and matched media queries.

Implementing Responsive Ad Units with SizeConfig

Configuring responsive ads in Prebid.js centers around the ‘sizeConfig’ parameter. The challenge is to align media queries, ad sizes, and label logic so that every device is served optimal creatives.

Real-World Example: Setting Up Desktop, Tablet, and Mobile Sizes

Take a site with four breakpoints: desktop HD (min-width: 1600px), desktop (1200px+), tablet (768px–1199px), and phone (0px+). Each breakpoint supports specific ad sizes. By defining multiple ‘sizeConfig’ entries with proper media queries and supported sizes, Prebid automatically picks and activates the right sizes for each user. For instance, a 970×90 leaderboard may only show on wide screens, while a 300×250 appears across all device types.

Common Mistake: Overlapping Media Queries

Overlapping queries can create ambiguity. For example, if tablet and desktop definitions overlap, unexpected ad sizes might be active, leading to inconsistent creative rendering or even missed revenue. Always ensure media queries are mutually exclusive or handle overlapping logic carefully—Prebid will intersect matching ‘sizesSupported’ arrays, only serving ad sizes valid for all matched queries.

Using Labels for Conditional Ad Unit and Bid Targeting

Labels go beyond pure responsiveness: they’re a logic layer publishers can use to target ad units and even individual bids based on complex device, region, or user status rules.

How Labels Work in Prebid

Labels are set either in the ‘sizeConfig’ array or via the ‘pbjs.requestBids’ call. Each ad unit or bidder can include ‘labelAny’ (OR logic) or ‘labelAll’ (AND logic) conditions. This means, for example, a mobile-only bidder can be activated only when ‘phone’ is active, while another runs on both desktop and tablet. Conditional targeting prevents unnecessary bid requests, focuses demand where it matters, and keeps ad delivery aligned with user context.

Example: Multi-Bidder, Multi-Device Setup

Suppose you add one ad unit covering all devices, but use different bidders per device type. With labels, you can include an array such as ‘labelAny: [“desktop”, “tablet”]’ for a bidder that only runs on larger screens, and another with ‘labelAny: [“phone”]’ for mobile-specific demand. This keeps your auction clean and efficient.

Limitations, Pitfalls, and When to Use Advanced Size Mapping

The standard size mapping module focuses on banners where all responsive behavior changes in lockstep. But sites with more complex layouts or media types may need Prebid’s advanced size mapping module—or risk unpredictable auctions.

Limits of Standard SizeConfig

If you require different breakpoints for various ad units (e.g., left-nav and footer have different rules) or want to work with video/native ad slots, standard size mapping may fall short. In these cases, consider Prebid’s Advanced SizeMapping module, which offers much more granular control and avoids operational headaches.

Troubleshooting Label and SizeConfig Issues

A common issue is incorrect label or media query logic. For example, misaligned labels can inadvertently disqualify or activate ad units and bids, resulting in missing demand or excessive resourcing. Always verify label logic and thoroughly test viewport breakpoints to ensure ads appear as intended.

What this means for publishers

Mastering Prebid’s size mapping and labels lets publishers serve the right ads on every screen, boost fill rates, and avoid awkward ad misfires that erode user experience. Proper configuration minimizes wasted impressions, maximizes revenue from each device, and gives operational teams far greater control when troubleshooting or scaling responsive setups.

Practical takeaway

To get responsive ads right with Prebid, start with clear device breakpoints and ad size rules, setting up your ‘sizeConfig’ before launching any campaigns. Use labels strategically: reserve them for genuinely conditional logic, like activating certain bidders or ad units for specific audiences (devices, regions, or user segments).

Routinely test your ad unit and bidder activation logic on real devices to catch unintended overlaps or gaps. For more advanced scenarios—like dynamic layouts, multiple ad formats, or per-unit breakpoints—explore the advanced size mapping module and keep the logic as maintainable as possible. Proper use of size mapping and labels is foundational to robust, scalable header bidding setup that truly puts publishers in control.