Prebid Server Adapter

• Overview
• Configuration
• Bid Params
• Examples
  • Defining endpoints
  • Server-Side Aliases
  • Video via s2sConfig
  • Stored impressions
  • Stored responses
• Related Reading

Overview

The Prebid Server Adapter is a meta-adapter. It’s not an actual bidder, but rather a way to get a batch of bids from other bidders with one request. A request for the set of auctions is sent to Prebid Server, which performs all the auctions server-to-server (S2S), responding in time for Prebid.js to send the results to the ad server. This lightens the performance load on the user’s device.

Configuration

Here’s an example config enabling the AppNexus Prebid Server:

pbjs.setConfig({
    s2sConfig: {
        accountId : '12345',
        bidders : ['appnexus','pubmatic', 'rubicon'],
        defaultVendor: 'appnexus',
        timeout: 300
    }
});

To use multiple prebid servers, just define s2sConfig as an array. The same bidder cannot be set in both configs. For example:

pbjs.setConfig({
    s2sConfig: [
    {
        name: "pbs-appnexus",
        accountId: '12345',
        bidders: ['appnexus','pubmatic'],
        defaultVendor: 'appnexus',
        timeout: 300,
    },
    {
        name: "pbs-rubicon",
        accountId: '678910',
        bidders: ['rubicon'],
        defaultVendor: 'rubicon',
        timeout: 300,
    },
    ],
});

There are many configuration options for s2sConfig:

If endpoint and syncEndpoint are objects, these are the supported properties:

Notes on s2sConfig properties

• Currently supported vendors are: appnexus, openx, and rubicon
• When using defaultVendor option, accountId still needs to be defined.
• If bidders is omitted, only adUnits that also omit bidders will be sent to Prebid Server. See the stored impressions example below.
• If the s2sConfig timeout is greater than the Prebid.js timeout, the s2sConfig timeout will be automatically adjusted to 75% of the Prebid.js timeout in order to fit within the auction process.
• When using the endpoint or syncEndpoint object configs, you should define both properties. If either property is not defined, Prebid Server requests for that type of user will not be made. If you do not need to distinguish endpoints for consent reasons, you can simply define the same URL value in both fields or use the String version of the field (which is configured to use defined URL for all users).
• When allowUnknownBidderCodes is true, bidders that have not been explicitly requested in adUnit.bids may take part in the auction. This can break custom logic that relies on the availability of a bid request object for any given bid. Known scenarios where custom code won’t get the request when there’s an “unknown bidder”:
  • There will not be a bidRequested event.
  • In the MASS custom renderers module, payload.bidRequest will be undefined.
  • In the Price Floors module, custom schema functions will see the bidRequest object as undefined.

Additional options for s2sConfig may be enabled by including the Server-to-Server testing module.

Passing the Referrer to Server Side Adapters

• Setting extPrebid.origreferrer will be recognized by some server-side adapters as the referring URL for the current page.

Emitting SeatNonBid Data

• Prebid Server can be instructed to return additional SeatNonBid information about why bidders might not have bid on certain adunits. You can get this extra information by setting extPrebid.returnallbidstatus equal to true. Note that client-side analytics adapters can receive this data by listening to the seatNonBid event.

Bid Params

Bid params are sourced from the adapter configurations set for client side. These do not need to change for Prebid Server.

Errors in bidder parameters will cause Prebid Server to reject the entire request. The Prebid Server philosophy is to avoid silent failures – we assume you will test changes, and that it will be easier to notice a 4xx error coming from the server than a silent failure where it skips just the bad parameter.

Examples

Defining endpoints

s2sConfig example with the endpoint attributes defined instead of using the ‘defaultVendor’ approach:

pbjs.setConfig({
    s2sConfig: [{
        accountId: '1001',
        bidders: ['bidderA', 'bidderB'],
        endpoint: 'https://mypbs.example.com/path',
        syncEndpoint: 'https://mypbs.example.com/path',
        timeout: 300
    }]
})

A similar example with the endpoint attributes defined as objects:

pbjs.setConfig({
    s2sConfig: [{
        accountId: '1001',
        bidders: ['bidderA', 'bidderB'],
        endpoint: {
            p1Consent: 'https://mypbs.example.com/path',
            noP1Consent: 'https://mypbs2.example.com/path'
        },
        syncEndpoint: {
            p1Consent: 'https://mypbs.example.com/path',
            noP1Consent: 'https://mypbs2.example.com/path'
        },
        timeout: 300
    }]
})

Server-Side Aliases

You may want to run a particular bidder on the client for banner, but that same bidder on the server for video. You would do this by setting a server-side alias. For example:

pbjs.setConfig({
  s2sConfig: [{
    accountId: '1',
    bidders: ['tripleliftVideo'],
    defaultVendor: 'appnexus',
    timeout: 500,
    extPrebid: {
      aliases: {
        tripleliftVideo: tripleLift
      }
    }
  }]
})

Here’s how it works:

1. Video ad units are coded with the dynamic alias. e.g. tripleliftVideo
2. The s2sConfig.bidders array contains ‘tripleliftVideo’ telling Prebid.js to direct bids for that code to the server
3. Finally, the extPrebid.aliases line tells Prebid Server to route the ‘tripleliftVideo’ biddercode to the ‘triplelift’ server-side adapter.

Video via s2sConfig

Supporting video through the Server-to-Server route can be done by providing a couple of extra arguments on the extPrebid object. e.g.

pbjs.setConfig({
    s2sConfig: [{
        accountId: '1001',
        bidders: ['rubicon', 'pubmatic'],
        defaultVendor: 'rubicon',
        timeout: 250,
        extPrebid: {
            cache: {
                vastxml: {returnCreative: false}
            },
            targeting: {
                pricegranularity: {"ranges": [{"max": 40.00, "increment": 1.00}]}
            }
        }
    }]
})

Stored impressions

Prebid Server stored requests can be requested through the adUnit ortb2Imp property. This is useful to move the list of bidders and parameters from the page to blocks of JSON stored on the server. For these cases, it’s not necessary to specify bids:

pbjs.addAdUnits([{
  code: 'example-stored-request',
  mediaTypes: {
    banner: {
      sizes: [[300, 250]]
    }
  },
  ortb2Imp: {
    ext: {
      prebid: {
        storedrequest: {
          id: 'your-stored-request-id'
        }
      }
    }
  }
}])

Stored responses

For debugging purposes, it can be useful to have a page that retrieves a static value rather than running an actual auction. For this you can use PBS stored responses. Here’s an example:

pbjs.addAdUnits([{
  code: 'example-stored-response',
  mediaTypes: {
    banner: {
      sizes: [[300, 250]]
    }
  },
  ortb2Imp: {
    ext: {
      prebid: {
        storedauctionresponse: {
          id: 'your-stored-response-id'
        }
      }
    }
  }
}])

Related Reading

• Prebid Server Overview