How to Add a New Bidder Adapter
At a high level, a bidder adapter is responsible for:
- Sending out bid requests to the ad server
- 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
- 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
Create a JS file under
moduleswith the name of the bidder suffixed with ‘BidAdapter’, e.g.,
Create an adapter factory function with the signature shown below:
A good example of an adapter that uses this pattern for its implementation is Pubmatic.
Step 3: Design your bid params
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.
params object contains information about the bids configured in the request:
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.
If the bid is invalid (no fill or error), create the
bidObject as shown below.
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.
The required parameters to add into
||Required||The bidder code.||
||Required||The bid price. We recommend the most granular price a bidder can provide||3.5764|
||Required||The width of the returned creative.||300|
||Required||The height of the returned creative.||250|
||Required||The creative payload of the returned bid||
adloader.loadScript(scriptURL, callback, cacheRequest)
Note that loading external code into your adapter will be prohibited starting with Prebid 1.0.
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.