How to Add a New Bidder Adaptor
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.
- 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.
Step 2: Add a new bidder JS file
Create a JS file under
src/adapterswith the name of the bidder, 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 OpenX.
Step 3: Design your bid params
bid.params object for defining the parameters of your ad request. At a minimum, you should include the tag ID and the site ID. You can also include ad sizes, 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 example, if your bidder supports serving video ads, you could add a
video object to your adapter’s bid parameters like the AppNexus AST adapter. To see how those video params are processed and added to the ad tag, see the AST adapter’s implementation of the
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, use
bidfactory.createBid(1)to create the
bidObject. A status of
1means the bid is valid. For details about the status codes, see constants.json.
- If the bid is invalid (no fill or error), use
bidfactory.createBid(2)to create the
bidObject. A status of
2means “no bid”.
If your bidder supports serving video ads, it needs to provide a VAST video URL in its response. On the adapter side, your implementation of
createBid needs to add the VAST URL to the bid. For an example implementation, see the implementation in the AST adapter.
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)
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.