How to Add a Prebid 1.0 Bidder Adapter
This document is a work in progress for Prebid 1.0
Feedback welcome - open an issue on Github.
At a high level, a bidder adapter is responsible for:
- Creating the bid requests for the bidder’s server.
- Parsing and registering the bid responses.
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.
As of October 1st, 2017, we will no longer be accepting pull requests for adapters that are not compliant with Prebid 1.0 conventions.
- Planning your adapter
- Create the Adapter
- Supporting Video
- Supporting Native
- Unit Tests
- Migrating from Prebid 0.x to 1.0
- Full Bid Adapter Example using the BaseAdapter
- Further Reading
Planning your adapter
With each adapter submission, there are two files required to be in the pull request:
modules/exampleBidAdapter.js: the file containing the code for the adapter
modules/exampleBidAdapter.md: a markdown file containing key information about the adapter:
- 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. Note that if your adapter supports video, outstream video, or native, you must also provide example parameters for each type.
Example markdown file:
Required adapter conventions
As of Prebid 1.0, adapters must follow the conventions listed below.
In order to provide a fast and safe header bidding environment for publishers, the Prebid.org team reviews all adapters for the following required conventions:
- Support multiple instances: All adapters must support the creation of multiple concurrent instances. This means, for example, that adapters cannot rely on mutable global variables.
- No loading of external libraries: All code must be present in the adapter, not loaded at runtime.
- Must support HTTPS: Within a secure page context, the request to the bidder’s server must also be secure.
- Compressed responses: All bid responses from the bidder’s server must be gzipped.
- Bid responses may not use JSONP: All requests must be AJAX with JSON responses.
- All user-sync activity must be registered via the provided functions: The platform will place all registered syncs in the page after the auction is complete, subject to publisher configuration.
Adapters may not use the
$$PREBID_GLOBAL$$variable: Instead, they must load any necessary functions and call them directly.
Failure to follow any of the above conventions could lead to delays in approving your adapter for inclusion in Prebid.js.
Design your bid params
bid.params object will define the parameters of your ad request. You can include tag ID, site ID, ad size, keywords, and other data, such as video parameters.
For more information about the kinds of information that can be passed using these parameters, see the existing bidder parameters.
A sample AdUnit with parameters for the ‘example’ bidder:
Create the Adapter
If you’re the type that likes to skip to the answer instead of going through a tutorial, see the Full Bid Adapter Example below.
The new code will reside under the modules directory with the name of the bidder suffixed by ‘BidAdapter’, e.g.,
Compared to previous versions of Prebid, the new BaseAdapter model saves the adapter from having to make the AJAX call and provides consistency in how adapters are structured. Instead of a single entry point, the BaseAdapter approach defines 4 entry points:
isBidRequestValid- Verify the the
AdUnits.bids, respond with
buildRequests- Takes an array of validBidRequests, all of which are guaranteed to have passed the isBidRequestValid() test.
interpretResponse- Parse the response and generate one or more bid objects
getUserSyncs- If the publisher allows user-sync activity, the platform will call this function and the adapter may register pixels and/or iframe user syncs.
A high level example of the structure:
Building the Request
When the page asks Prebid.js for bids, your module’s
buildRequests function will be executed. Building the request will use data from several places:
AdUnit params: The arguments provided by the page are in
validBidRequestsas illustrated below.
bidderRequest.bids.transactionIdshould be sent to your server and forwarded to any Demand Side Platforms your server communicates with.
Ad Server Currency: If your service supports bidding in more than one currency, your adapter should call
config.getConfig(currency)to see if the page has defined which currency it needs for the ad server.
Referrer: Referrer should be passed into your server and utilized there. This is important in contexts like AMP where the original page referrer isn’t available directly to the adapter. We suggest using the
utils.getTopWindowUrl()function to obtain the referrer.
Sample array entry for validBidRequests:
Prebid 1.0: Some of these bid request recommendations are new.
There are several IDs present in the bidRequest object:
- Bid ID is unique across AdUnits and Bidders.
- Auction ID is unique per call to requestBids(), but is the same across AdUnits. And finally,
- Transaction ID is unique for each AdUnit with a call to requestBids, but same across bidders. This is the ID that DSPs need to recognize the same impression coming in from different supply sources.
The ServerRequest objects returned from your adapter have this structure:
|type||string||Which HTTP method should be used||GET/POST|
|endpoint||string||The endpoint for the request.||“http://bids.example.com”|
|data||string or object||Data to be sent in the POST request. Objects will be sent as JSON.|
Here’s a sample block of code returning a ServerRequest object:
Interpreting the Response
interpretResponse function will be called when the browser has received the response from your server. The function will parse the response and create a bidResponse object containing one or more bids. The adapter should indicate no valid bids by returning an empty array. An example showing a single bid:
Prebid 1.0: There are several new parameters required on the bid response object. Note that that the bidResponse
creativeId field is different than in 0.x when it was
creative_id. It’s been changed to camel-case to be consistent with the other fields.
The parameters of the
||Required||The bid ID. Used to tie this bid back to the request.||12345|
||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. For video, this is the player width.||300|
||Required||The height of the returned creative. For video, this is the player height.||250|
||Required||The creative payload of the returned bid.||
||Required||Time-to-Live - how long (in seconds) Prebid can use this bid.||360|
||Required||A bidder-specific unique code that supports tracing the ad creative back to the source.||
||Required||Boolean defining whether the bid is Net or Gross. The value
||Required||3-letter ISO 4217 code defining the currency of the bid.||
||Either this or
||URL where the VAST document can be retrieved when ready for display.||
||Either this or
||XML for VAST document to be cached for later retrieval.||
Register User Syncs
All user ID sync activity must be done in one of two ways:
getUserSyncscallback of the BaseAdapter model
Prebid 1.0: There aren’t any differences in video except that there was formerly a separate document describing how to build a video adapter. That information has been moved here.
There are a few differences for adapters supporting video auctions. Here are the steps to ensure that an adapter properly supports video:
Step 1: Register the adapter as supporting video
supportedMediaTypes argument to the spec object, and make sure
video is in the list:
Step 2: Accept video parameters and pass them to your server
See the AppNexus AST adapter for an example of how video parameters may be passed in from the AdUnit.
Step 3: Respond with VAST or a VAST URL
When the bidder returns VAST or a VAST URL in its bid response, it needs to add the result into either
bid.vastUrl. For example, here is some code from the Tremor adapter showing how it’s done:
In order for your bidder to support the native media type, you need 2 things:
- Your (server-side) bidder needs to respond with a bid that has native information.
- Your (client-side) bidder adapter needs to unpack the server’s bid into a Prebid-compatible bid populated with the required native information.
For example, below is the code in the AppNexus AST adapter that achieves #2. As you can see, we:
- Check for native information on the bid response.
- Fill in the bid’s
nativeobject with information from the bid.
Every adapter submission must include unit tests. See existing test suites in test/spec/modules.
Migrating from Prebid 0.x to 1.0
During the transition period between Prebid 0.x and 1.0, all adapters should submit pull requests to the master branch. We will rebase to the prebid-1.0 branch regularly.
During the transition, please test your adapter with the prebid-1.0 branch.