PAAPI module

This module allows Prebid.js to support PAAPI, formerly known as FLEDGE.

This document covers the steps necessary for publishers to enable PAAPI on their inventory. It also describes the changes Bid Adapters need to implement in order to support PAAPI.

A related module, paapiForGpt, adds support specifically for GPT’s component auctions.

Publisher Integration

To use PAAPI, publishers must:

• include this module in their Prebid.js bundle

   gulp build --modules=paapi,...
  

• enable PAAPI, globally or by ad unit, through configuration
• manage the PAAPI auctions. This can be delegated to GPT with the paapiForGpt module; homegrown solutions are possible with topLevelPaapi.

Module Configuration

This module exposes the following settings:

As noted above, PAAPI support is disabled by default. To enable it, set the enabled value to true for this module and configure defaultForSlots to be 1 (meaning Client-side auction). using the setConfig method of Prebid.js:

pbjs.que.push(function() {
  pbjs.setConfig({
    paapi: {
      enabled: true,
      defaultForSlots: 1
    }
  });
});

Optionally, PAAPI support can be limited to specific bidders:

pbjs.que.push(function() {
  pbjs.setConfig({
    paapi: {
      enabled: true,
      defaultForSlots: 1,
      bidders: ['bidderA', 'bidderB']
    }
  });
});

AdUnit Configuration

All adunits can be opted-in to PAAPI in the global config via the defaultForSlots parameter. If needed, adunits can be configured individually by setting an attribute of the ortb2Imp object for that adunit. This attribute will take precedence over defaultForSlots setting.

The ae field stands for Auction Environment and was chosen to be consistent with the field that GAM passes to bidders in their Open Bidding and Exchange Bidding APIs. More details on that can be found here In practice, this looks as follows:

pbjs.addAdUnits({
    code: "my-adunit-div",
    // other config here
    ortb2Imp: {
        ext: {
            ae: 1
        }
    }
});

Advanced usage: publisher-managed component auction

Bid adapters typically act as PAAPI sellers, each providing one or more component auctions in a multi-seller PAAPI auction. Some adapters may act as PAAPI buyers: instead of a full component auction, they can reply directly with buyer information. By configuring componentSeller, these buyers are collected into one or more publisher-managed component auctions.

Bid Adapter Integration

Chrome has enabled a two-tier auction in PAAPI. This allows multiple sellers (frequently SSPs) to act on behalf of the publisher with a single entity serving as the final decision maker. In their current approach, GPT has opted to run the final auction layer while allowing other SSPs/sellers to participate as Component Auctions which feed their bids to the final layer. To learn more about Component Auctions, go here.

The PAAPI auction, including Component Auctions, are configured via an AuctionConfig object that defines the parameters of the auction for a given seller. This module enables PAAPI support by allowing bid adaptors to return AuctionConfig objects in addition to bids. If a bid adaptor returns an AuctionConfig object, Prebid.js will make it available through getPAAPIConfig, as well as other PAAPI modules such as paapiForGpt.

If your adapter interfaces with an ORTB backend, you may take advantage of Prebid’s ORTB conversion library, which implements the following using protected audience community extensions

Modifying a bid adapter to support PAAPI is a straightforward process and consists of the following steps:

1. Detecting when a bid request is PAAPI eligible
2. Responding with AuctionConfig or InterestGroupBuyer in addition to (or instead of) bids

Input parameters

When PAAPI is configured, the following fields are made available to adapters’ buildRequests:

Output values

When a bid request is PAAPI enabled, a bid adapter can return a tuple consisting of bids and PAAPI objects rather than just a list of bids:

function interpretResponse(resp, req) {
    // Load the bids from the response - this is adapter specific
    const bids = parseBids(resp);

    // Load auction configs or igb from the response - also adapter specific
    const paapi = parsePaapi(resp);
    return {bids, paapi};
}

paapi must be an array of objects containing:

Each object must specify exactly one of igb or config.

An example of this can be seen in the OpenX bid adapter here or RTB House bid adapter here.

Related Reading

• paapiForGpt module
• Protected Audience API (PAAPI), formerly FLEDGE
• Component Auctions
• getPAAPIConfig