Prebid Modules: How they work, use cases, and examples

With inputs from Richard Lam, Senior Product Manager at Blockthrough.

Prebid.js is the most widely adopted header bidding wrapper among web publishers for many reasons. It’s open-source, easy to configure, and supports more than 200 bidding adapters.

But perhaps more even more important than those things, Prebid allows publishers to customize their header bidding stack and extend its functionality in ways that many other proprietary header bidding wrappers cannot, using something called “modules”.

In this guide, we’ll explain what Prebid Modules are, along with a rundown of the most commonly used Prebid Modules, their use cases, things to note, and sample configurations.

What are Prebid Modules?

Prebid.js features a modular framework. This means that the base functionality of the wrapper can be extended by installing one or more optional add-ons or “modules”—in the same way that browsers offer extensions and content management systems (like WordPress) offer plugins.

There are several advantages to this approach, the chief among them being that publishers don’t need to compile and execute any additional code beyond the functionality that they require. A modular code framework also means faster auctions on the page and better revenue performance, which leads to better outcomes for both users and publishers.

The most common Prebid modules

Currency Module

The currency module handles conversion in cases where the demand partners participating in the auction are bidding in a currency different from the default used by the publisher’s ad server. For instance, let’s say you have demand partner A and B returning bids in USD ($) and Euro (€) respectively, but your ad server’s base currency is the British pound sterling.

Before Prebid released the currency module, publishers relied on a manual CPM adjustment to reconcile currency conversions. However, since currencies fluctuate in real-time, operations teams had to frequently update the adjustments. The currency module eliminates that problem by conducting conversions automatically at real-time market rates.

Here’s an example of currency conversion code in Prebid:

pbjs.setConfig({
"currency": {
      // enables currency feature
      "adServerCurrency": "GBP",
      "granularityMultiplier": 1, // 0.50 increment up to 5 is fine for GBP
      // optionally override the default rate file
      "conversionRateFile": "URL_TO_RATE_FILE",
      // optionally provide a default rate in case the file can't be read
      "defaultRates": { "USD": { "GPB": 0.75 }}
   }
});

Prebid.org hosts a conversion file at https://cdn.jsdelivr.net/gh/prebid/currency-file@1/latest.json with support for 33 currencies. Publishers can also declare their own JSON currency file.

Consent Management Modules

Privacy regulations such as GDPR and CCPA have given users certain rights over how their personal data is stored, used, and processed, and the cost of non-compliance can be substantial. So, Prebid created the consent modules to pass the consent strings collected by the publishers’ consent management platform and make them available to their bidding partners.

There are three different modules currently offered under the category:

• GDPR Consent Management Module: This module is designed to support the EU GDPR regulation. It fetches the user’s GDPR and Google additional consent data from supported CMPs and then incorporates this data into auction objects for adapters to collect. Support for reading and parsing TCF 2.0 consent strings is currently under development.
• GDPR Enforcement Module: This module is an add-on to the base EU GDPR module and allows the page to define which activities should be enforced at the Prebid.js level. This means the ability to set timeouts and prevent the activation of cookie syncs, bid adapters, analytics adapters, and access to cookies or localstorage in the user’s browser.
• US Privacy Consent Management Module: This module supports the California Consumer Privacy Act (CCPA). The IAB has generalized the requirements to cover future regulations, dubbing the feature “US Privacy”. The module works by working with IAB-compatible US Privacy API to fetch an encoded string representing the user’s notice and opt-out choices and then making that information available for adapters to consume and process.

Here is a sample configuration that supports both GDPR and US Privacy:

var pbjs = pbjs || {};
     pbjs.que = pbjs.que || [];
     pbjs.que.push(function() {
       pbjs.setConfig({
         consentManagement: {
           gdpr: {
            cmpApi: 'iab',
            allowAuctionWithoutConsent: false, // suppress auctions if there's no GDPR consent string
            timeout: 3000  // GDPR timeout 3000ms
           },
           usp: {
            timeout: 100 // US Privacy timeout 100ms
           }
         }
       });
     });

User ID Module

Part of what makes header bidding valuable is the ability to pass user identity to bidders participating in the auction. To enable this, users are tagged with a User ID—a unique identifier that can be used to track them without compromising their personally identifiable information. Right now, exchanges sync User IDs with dozens of demand sources in a process called cookie syncing, which will no longer be possible after the deprecation of third-party cookies.

In the wake of these developments, a lot of ad tech vendors have presented their own unified ID solutions (80 at last count by AdExchanger) that rely on first-party mechanisms to identify users, create encrypted IDs, and then sync them between publishers and their demand partners.

The Prebid User ID module allows publishers to activate these ID solutions from multiple vendors on their header bidding stack. Here’s a simplified flow of what that process looks like:

• You decide which User ID sub-modules to add to Prebid. Prebid supports many different ID solutions, including Google’s FLoC, Unified ID, ID5, IndentityLink and more.
• Build the User ID module and specify the ID sub-modules that you would like to include
• The page defines User ID configuration in pbjs.setConfig()
• When pbjs.setConfig() is called, the User ID module is activated and the data is stored locally. Finally, an object containing one or more IDs is made available to adapters.
• When paired with the Consent Management Module, privacy rules are enforced, and the User ID module activates or deactivates based on those criteria being met.

Price Floors Module

Publishers have been setting price floors long before Prebid became popular to protect their inventory from being undersold. To recap, a “floor” is defined as the lowest CPM price a bid will need to meet for each Prebid auction. The Price Floor Module in Prebid allows publishers to declare their own price floors or use the price floors provided by a third-party vendor.

Here’s how it works:

• When building the Prebid.js package, the Price Floor Module is included with the command: ‘gulp build –modules=priceFloors,…'. Using the module, you can set floors at the ad unit or page level, and also integrate a third-party vendor to set dynamic floors.
• When the setConfig({floors}) function is initiated, the module will attempt to build a table based on the rules configured by the publisher during set up. If a dynamic floor is enabled, Prebid will attempt to call the floor provider’s endpoint and fetch the data.
• The bid adapters are responsible for fetching the price floor for each ad slot media type and size combination using the getFloors() function. If the bidder requests floors in a different currency, the module will handle the conversions.
• Finally, the bid adapters submit bids to Prebid. At this stage, the module will mark all bids that don’t meet the floor as “rejected”, and then only send the eligible bids to the publisher’s ad server. The module also emits floor event data to connected analytics adapters, so that floor providers have a feedback loop for model training.

Sidenote: Most Prebid floors are configured using five pre-configured dimensions, i.e., ad unit, GPT Slot Name, MediaType, ad size, and domain. However, publishers can also use a custom dimension function to set floors using other attributes, user device type for example.

Advanced Size Mapping Module

Responsive ad units and formats have been widely adopted by publishers as a way to simplify ad delivery across multiple device types and screen resolutions. The Advanced Size Mapping Module gives publishers flexibility in configuring responsive ad units beyond what’s possible with core Prebid. The module detects the users’ viewport dimensions and helps determine:

• Which banner sizes should be active
• What the playerSize is for video media type
• Whether or not the native media type should be active
• Whether or not a particular bidder should participate in the auction

The module works on the banner, video, and native formats, and can be used to control their on-page behavior. Publishers can also selectively activate/deactivate bidders based on checks.

Also, note that the Advanced Size Mapping Module adds about 12kb to the Prebid package. It is meant for publishers who have a complex site design and need a high level of customization for ad sizes, ad formats, and bidder participation based on device types and screen resolutions.

Bid Viewability Module

With ad viewability becoming an important metric for demand partners to make buying decisions, publishers need a way to measure and report the viewability performance of their inventory. The Bid Viewability Module triggers the BID_VIEWABLE event, which can be consumed by the winning bidder and analytics adapters.

Here are some additional things you should know about this module:

• Prebid provides two Bid Viewability modules, one intended for use when the publisher’s ad server is Google Ad Manager, and another that is ad server independent.
• IAB’s viewability guidelines are used for deciding whether or not the impression is viewable. This means that at least 50% of the ad’s pixels must be viewable on the screen for a continuous one second for it to be considered viewable. There are additional viewability criteria for larger ads and video ads.
• The GAM module works with banner, outstream, and native ads, while the ad server independent module only supports banner creatives, with more support in the works.
• Prebid also supports custom viewability tracking using vendor-specific modules

First Party Data Enrichment Module

Availability of reliable first-party data has become more valuable than ever and demand partners are willing to bid more where such data is available. Prebid allows publishers to supply attributes related to their users and content, and also apply permissions so only selected bidders are allowed access to those attributes.

The First Party Data Enrichment Module adds a number of First Party Data fields from the environment to the bidstream for consumption by bidding partners.

Making this data available translates to higher bids and improved yield. When the first auction on the page is run, this module merges a number of values to the ortb2 object. Some of the available data fields include page URL, referrer URL, host domain, viewport width/height, meta keywords, and currency. If the module is included in the build, it will automatically perform the enrichments unless restricted with setConfig, such as in the example below:

pbjs.setConfig({
    firstPartyData: {
        skipEnrichments: true   // defaults to false
    }
});

If the publisher needs to refresh the data fields after the first auction is performed, it can be executed using the function pbjs.refreshFpd();.

MultiBid Module

Multi-bidding is a process that allows bidders to send multiple bids for an impression to the ad server. Earlier, this feature was only supported on Prebid Server, the S2S edition of Prebid. The MultiBid Module now extends the same functionality to Prebid.js.

Here are the use cases supported by this module:

• Allows bidders to provide bids on both outstream and banner
• Allows bidders to provide multiple video bids for the fallback scenario
• Allows bids from a bidder to be selectively blocked based on ad server targeting logic
• Informs bidders about how many bids will be considered
• Expands the number of ad server targeting values that can be set

Allowing bidders to place multiple bids for the same impression translates to greater bid density and a lift in yield for publishers. Since this is a relatively new module, only a few SSPs support it (this includes Magnite and AppNexus), with support from other SSPs in development.

Here’s an example configuration for MultiBid:

pbjs.setConfig({
    multibid: [{
        bidder: "bidderA",
        // bidderA can supply up to two bids
        maxBids: 2,
	// the second bid will go to the ad server as hb_pb_bidA2
        targetBiddercodePrefix: "bidA"  
    },{
        bidder: "bidderB",
        // bidderB can supply up to three bids
        maxBids: 3,
	// additional bids will be passed as hb_pb_bidB2 and hb_pb_bidB3
        targetBiddercodePrefix: "bidB"
    },{
        bidders: ["bidderC","bidderD"]
        maxBids: 3
        // don't send extra bids to ad server, just cache good ones
    }]
});