How to Add a New Bidder Adapter

This page contains legacy instructions on how to build a Prebid adapter before Prebid 1.0. Adapter writers should use the Prebid 1.0 adapter guidelines.

As of October 1st, 2017, we will no longer be accepting pull requests for adapters that are not compliant with Prebid 1.0 conventions.

At a high level, a bidder adapter is responsible for:

1. Sending out bid requests to the ad server
2. Registering the bids that are returned with Prebid.js

This page has instructions for writing your own bidder adapter. The instructions here try to walk you through some of the code you’ll need to write for your adapter. When in doubt, use the working adapters in the Github repo for reference.

Adding a Video Bidder Adapter?
See How to Add a New Video Bidder Adapter.

• Step 1: Prepare prerequisites for a pull request
• Step 2: Add a new bidder JS file
• Step 3: Design your bid params
• Step 4: Send out bid requests
• Step 5: Register bid responses
• Step 6: Register User Sync Pixels
• Helper functions
• Further Reading

Step 1: Prepare prerequisites for a pull request

In your PR to add the new adapter, please provide the following information:

• The contact email of the adapter’s maintainer.
• A test ad unit that will consistently return test creatives. This helps us to ensure future Prebid.js updates do not break your adapter.
• Any other information listed as required in CONTRIBUTING.md.

Step 2: Add a new bidder JS file

1. Create a JS file under modules with the name of the bidder suffixed with ‘BidAdapter’, e.g., xyzBidAdapter.js

2. Create an adapter factory function with the signature shown below:

import bidfactory from 'src/bidfactory';
import bidmanager from 'src/bidmanager';
import * as utils from 'src/utils';       // useful functions
import { ajax } from 'src/ajax';          // recommended AJAX library
import { STATUS } from 'src/constants';
function xyzBidAdapter() {

    function _callBids(params) {... add code here ...}

    // Export the `callBids` function, so that Prebid.js can execute
    // this function when the page asks to send out bid requests.
    return {
        callBids: _callBids
    };
};

adaptermanager.registerBidAdapter(new XYZBidAdapter, 'xyz');
module.exports = xyzBidAdapter;

A good example of an adapter that uses this pattern for its implementation is Pubmatic.

Step 3: Design your bid params

Use the bid.params object for defining the parameters of your ad request. You can include tag ID, site ID, ad size, keywords, and other data, such as video bidding information.

For more information about the kinds of information that can be passed using these parameters, see the list of bidder parameters.

For more information about how the implementation of callBids should work generally, see the next section.

Step 4: Send out bid requests

When the page asks Prebid.js to send out bid requests, your bidder’s _callBids(params) function will be executed. This is a good place for you to send out bid requests to your bidder.

Example:

function _callBids(params) {
    bids = params.bids || [];
    for (var i = 0; i < bids.length; i++) {
        var bid = bids[i];
        // Send out bid request for each bid given its tag IDs and query strings
    }
    // Or, send out 1 bid request for all bids, depending on your bidder.
}

The params object contains information about the bids configured in the request:

{
    bidderCode: "openx",
    bids: [
        {
            bidder: "openx",
            adUnitCode: "id123/header-bid-tag-0",
            sizes: [ [300, 250], [300, 600] ]
            // params is custom to the bidder adapter and will be
            // passed through from the configuration as is.
            params: { 
            	unit: '3242432',
                pgid: '123124',
                jstag_url: 'http://...'
            },
        }, {
        	bidder: "openx",
        	// params, adUnit Code, and sizes
        	// Note that the same adUnitCode may appear again.
    	}
    ]
}

Note that you should keep track of the adUnitCode in bid requests. In the next section this will come in handy.

Step 5: Register bid responses

When the bid response(s) are available, notify Prebid.js immediately, so that your bid can get into the auction as soon as possible. A bidder’s API will usually have an event listener that notifies you when the bid responses are back.

To register the bid, call the bidmanager.addBidResponse(adUnitCode, bidObject) function. To register multiple bids, call the function multiple times.

If the bid is valid, create the bid response as shown below, matching the bid request/response pair. For details about the status codes, see constants.json.

var utils       = require('../utils.js');
var bidfactory  = require('../bidfactory.js');

var bidRequest  = utils.getBidRequest(id);
var bidResponse = bidfactory.createBid(STATUS.GOOD, bidRequest);

If the bid is invalid (no fill or error), create the bidObject as shown below.

var bidRequest  = utils.getBidRequest(id);
var bidResponse = bidfactory.createBid(STATUS.NO_BID, bidRequest);

Example:

// In the bidder's API callback...

// the bidder API's ad response unit that has info like CPM, creative content
var adUnit;

var bidRequest  = utils.getBidRequest(id);
var bidObject = bidfactory.createBid(STATUS.GOOD, bidRequest);
bidObject.bidderCode = 'openx';
bidObject.cpm = Number(adUnit.get('pub_rev')) / 1000;
bidObject.ad = adUnit.get('html');
bidObject.width = adUnit.get('width');
bidObject.height = adUnit.get('height');

// send the bidResponse object to bid manager with the adUnitCode.
bidmanager.addBidResponse(adUnitCode, bidObject);

// invalid bid response
bidObject = bidfactory.createBid(STATUS.NO_BID, bidRequest);
bidObject.bidderCode = 'openx';
bidmanager.addBidResponse(adUnitCode, bidObject);

adUnitCode in addBidResponse

In bidder API’s callback, there’ll be ID(s) that tie back to the request params in the bid object. Building a map from adUnitCode to the request param(s)/ID(s) will help you retrieve the adUnitCode based on the callback.

bidObject in addBidResponse

The required parameters to add into bidObject are:

Step 6: Register User Sync Pixels

In order to protect page performance, user ID sync logic within Prebid adapters should be queued using the userSync.registerSync() function. Both image pixels and iframe sync methods are supported, but publishers may control which method(s) are allowed.

At some point after the auctions are complete, Prebid will write out the registered userSyncs. See the userSync section of the Publisher API Reference for information about how Publishers can control which syncs are allowed.

Add a user sync in an adapter in two steps:

1. Load the userSync module in the adapter file
2. Register the sync

import { userSync } from 'src/userSync.js';

   // ... code ...
   if ($$PREBID_GLOBAL$$.userSync.iframeEnabled) {
     userSync.registerSync('iframe', 'exampleAdapter', 'http://example.com/iframe-url');
   } else {
     userSync.registerSync('image', 'exampleAdapter', 'http://example.com/pixel');
   }
   // ... code ...

The general syntax for the userSync.registerSync() function:

userSync.registerSync(type, adapterName, url);

Note that the userSync object contains the registerSync function. The example above shows a destructed import, which eliminates the need to refer the to function through its object.

Parameters for registerSync:

See the Publisher API Reference for more information about how this feature works.

Helper functions

adloader.loadScript(scriptURL, callback, cacheRequest)

Load a script asynchronously. The callback function will be executed when the script finishes loading.

Use this with the cacheRequest argument set to true if the script you’re loading is a library or something else that doesn’t change between requests. It will cache the script so you don’t have to wait for it to load before firing the supplied callback.

For usage examples, see the working adapters in the repo.

Further Reading

• How to Add a New Video Bidder Adapter

• The bidder adapter sources in the repo