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:
- 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
- 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
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||
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:
- Load the userSync module in the adapter file
- Register the sync
The general syntax for the userSync.registerSync() function:
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:
||string enum||The type of sync, either ‘image’ or ‘iframe’.|
||string||The name of the adapter. Used for logging.|
||string||The fully qualified URL.|
See the Publisher API Reference for more information about how this feature works.
Note that in Prebid 1.0, use of the registerSync() function will be required for all user ID activity.
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.