At a high level, a bidder adapter is responsible for:
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.
In order to provide a fast and safe header bidding environment for publishers, the Prebid.org team reviews all adapters for the required bid adapter conventions laid out in the Module Rules. Here are additional details specific to Prebid.js:
buildRequests()
and getUserSyncs()
) or that are included in a winning and rendered creative.googletag.pubads().getSlots()
to modify or set targeting directly on slots is not permitted.The above list is not the full list of requirements. Failure to follow any of the required conventions defined in the Module Rules could lead to delays in approving your adapter for inclusion in Prebid.js. If you’d like to apply for an exception to one of the rules, make your request in a new Prebid.js issue.
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 adaptermodules/exampleBidAdapter.md
: a markdown file containing key information about the adapter:
Example markdown file:
The parameters of your ad request will be stored in the ad unit’s bid.params
object. You can include tag info, 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 example below, as well as the existing bidder parameters.
When defining the HTTP headers for your endpoint, it is important from a performance perspective to consider what forces the browser to initiate a CORS preflight request. We encourage learning more about Simple Requests & CORS as it relates to your specific development configuration.
A ‘Simple Request’ meets all of the following conditions:
Accept
Accept-Language
Content-Language
Content-Type
Range
Content-Type
header the only type/subtype combinations allowed are the following
If the request is made using XMLHttpRequest
object, no event listeners are registered on the object returned by the XMLHttpRequest.upload
property used in the request
ReadableStream
object is used in the requestPrebid recommends keeping module HTTP requests ‘simple’ if at all possible. The default content-type used by Prebid.js is text/plain.
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., exampleBidAdapter.js
.
Here are some guidelines for choosing a bidder code:
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 the following entry points:
isBidRequestValid
- Verify the the AdUnits.bids
, respond with true
(valid) or false
(invalid).buildRequests
- Takes an array of valid bid requests, 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. For more information, see Registering User Syncs below.onTimeout
- If the adapter timed out for an auction, the platform will call this function and the adapter may register timeout. For more information, see Registering User Syncs below.A high level example of the structure:
When the page asks Prebid.js for bids, your module’s buildRequests
function will be executed and passed two parameters:
validBidRequests[]
- An array of bidRequest objects, one for each AdUnit that your module is involved in. This array has been processed for special features like sizeConfig, so it’s the list that you should be looping through.bidderRequest
- The master bidRequest object. This object is useful because it carries a couple of bid parameters that are global to all the bids.Building the request will use data from several places:
validBidRequests[]
.bidderRequest
object.Here is a sample array entry for validBidRequests[]
:
Retrieve your bid parameters from the params
object.
Other notes:
requestBids()
, but same across bidders. This is the ID that enables DSPs to recognize the same impression coming in from different supply sources.requestBids()
has been called for this ad unit.requestBids()
has been called for this ad unit and bidder.userId
.bidderRequest.ortb2
(see below), provided here for convenience.Here is a sample bidderRequest object:
Notes on parameters in the bidderRequest object:
requestBids()
, but is the same across ad units.device.sua
) or information on the regulatory environment (regs.ext.gpc
).There are a number of important values that a publisher expects to be handled in a standard way across all Prebid.js adapters:
Parameter | Description | Example |
---|---|---|
Ad Server Currency | If your endpoint supports responding in different currencies, read this value. | config.getConfig(‘currency.adServerCurrency’) |
Bidder Timeout | Use if your endpoint needs to know how long the page is allowing the auction to run. | config.getConfig(‘bidderTimeout’); |
COPPA | If your endpoint supports the Child Online Privacy Protection Act, you should read this value. | config.getConfig(‘coppa’); |
First Party Data | The publisher, as well as a number of modules, may provide first party data (e.g. page type). | bidderRequest.ortb2; validBidRequests[].ortb2Imp |
Floors | Adapters that accept a floor parameter must also support the floors module | getFloor() |
Page URL and referrer | Instead of building your own function to find the page location, domain, or referrer, look in the standard bidRequest location. | bidderRequest.refererInfo.page |
Supply Chain | Adapters cannot accept an schain parameter. Rather, they must look for the schain parameter at bidRequest.schain. | bidRequest.schain |
Video Parameters | Video params must be read from AdUnit.mediaType.video when available; however bidder config can override the ad unit. | AdUnit.mediaType.video |
Referrer information should be passed to your endpoint in contexts where the original page referrer isn’t available directly to the adapter. Use the bidderRequest.refererInfo
property to pass in referrer information. This property contains the following parameters:
location
: a string containing the detected top-level URL, or null when the top window is inaccessible.topmostLocation
: a string containing the URL of the topmost accessible frame.canonicalUrl
: a string containing the canonical (search engine friendly) URL, as set by the publisher.
page : the best candidate for the top level URL - or null when the top window is inaccessible. Equivalent to canonicalUrl
|
location . |
domain
: the domain (hostname and port) portion of page
.ref
: referrer to the top window (window.top.document.referrer
), or null when the top window is inaccessible.reachedTop
: a boolean specifying whether Prebid was able to walk up to the top window.numIframes
: the number of iFrames.stack
: an array of URLs of all windows from the top window down to the current window.isAmp
: a boolean specifying whether the detected referer was determined based on AMP page information.The URLs returned by refererInfo
are in raw format. We recommend encoding the URL before adding it to the request payload to ensure it will be sent and interpreted correctly.
You shouldn’t call your bid endpoint directly. Rather, the end result of your buildRequests function is one or more ServerRequest objects. These objects have this structure:
Attribute | Type | Description | Example Value |
---|---|---|---|
method |
String | Which HTTP method should be used. | POST |
url |
String | The endpoint for the request. | "https://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:
The 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:
Please provide as much information as possible in the meta
object. Publishers use this
data for tracking down bad creatives and ad blocking. The advertiserDomains field and the Demand Chain Object are
particularly useful. Publishers may have analytics or security vendors with the capability to parse and validate complicated demand chain objects. The meta.advertiserDomains field is proposed as required in 5.0; other fields may become required in a future release.
The parameters of the bidResponse
object are:
Key | Scope | Description | Example |
---|---|---|---|
requestId |
Required | The bid ID that was sent to spec.buildRequests as bidRequests[].bidId . Used to tie this bid back to the request. |
12345 |
cpm |
Required | The bid price. We recommend the most granular price a bidder can provide | 3.5764 |
currency |
Required | 3-letter ISO 4217 code defining the currency of the bid. | "EUR" |
width |
Required | The width of the returned creative. For video, this is the player width. | 300 |
height |
Required | The height of the returned creative. For video, this is the player height. | 250 |
ad |
Required | The creative payload of the returned bid. | "<html><h3>I am an ad</h3></html>" |
ttl |
Required | Time-to-Live - how long (in seconds) Prebid can use this bid. See the FAQ entry for more info. | 360 |
creativeId |
Required | A bidder-specific unique code that supports tracing the ad creative back to the source. | "123abc" |
netRevenue |
Required | Boolean defining whether the bid is Net or Gross. The value true is Net. Bidders responding with Gross-price bids should set this to false. |
false |
vastUrl |
Either this or vastXml required for video |
URL where the VAST document can be retrieved when ready for display. | "https://vid.example.com/9876 |
vastImpUrl |
Optional; only usable with vastUrl and requires prebid cache to be enabled |
An impression tracking URL to serve with video Ad | "https://vid.exmpale.com/imp/134" |
vastXml |
Either this or vastUrl required for video |
XML for VAST document to be cached for later retrieval. | <VAST version="3.0">... |
bidderCode |
Optional | Bidder code to use for the response - for adapters that wish to reply on behalf of other bidders. Defaults to the code registered with registerBidder ; note that any other code will need to be explicitly allowed by the publisher. |
‘exampleBidder’ |
dealId |
Optional | Deal ID | "123abc" |
meta |
Optional | Object containing metadata about the bid | |
meta.networkId |
Optional | Bidder-specific Network/DSP Id | 1111 |
meta.networkName |
Optional | Network/DSP Name | "NetworkN" |
meta.agencyId |
Optional | Bidder-specific Agency ID | 2222 |
meta.agencyName |
Optional | Agency Name | "Agency, Inc." |
meta.advertiserId |
Optional | Bidder-specific Advertiser ID | 3333 |
meta.advertiserName |
Optional | Advertiser Name | "AdvertiserA" |
meta.advertiserDomains |
Required(*) | Array of Advertiser Domains for the landing page(s). This is an array that aligns with the OpenRTB ‘adomain’ field. See note below this table. | ["advertisera.com"] |
meta.brandId |
Optional | Bidder-specific Brand ID (some advertisers may have many brands) | 4444 |
meta.brandName |
Optional | Brand Name | "BrandB" |
meta.demandSource |
Optional | Demand Source (Some adapters may functionally serve multiple SSPs or exchanges, and this would specify which) | "SourceB" |
meta.dchain |
Optional | Demand Chain Object | { 'ver': '1.0', 'complete': 0, 'nodes': [ { 'asi': 'magnite.com', 'bsid': '123456789', } ] } |
meta.primaryCatId |
Optional | Primary IAB category ID | "IAB-111" |
meta.secondaryCatIds |
Optional | Array of secondary IAB category IDs | ["IAB-222","IAB-333"] |
meta.mediaType |
Optional | “banner”, “native”, or “video” - this should be set in scenarios where a bidder responds to a “banner” mediaType with a creative that’s actually a video (e.g. outstream) or native. | "native" |
Note: bid adapters must be coded to accept the ‘advertiserDomains’ parameter from their endpoint even if that endpoint doesn’t currently respond with that value. Prebid.org publishers have required that all bidders must eventually supply this value, so every bidder should be planning for it. There’s often a long lag time between making a PBJS adapter update and when most pubs upgrade to it, so we minimally require adapters to be ready for the day when the endpoint responds with adomain.
If your endpoint can return creatives with OpenRTB macros, your adapter should resolve them.
Prebid will resolve the AUCTION_PRICE macro, but it will be after currency conversion and any bid adjustments. This differs from how OpenRTB defines this value as being the clearing price in the bid currency. Header Bidding is a first-price auction, the best candidate for “clearing price” is the original bid itself.
Prebid won’t resolve any other macros in the creative (e.g. AUCTION_ID, AUCTION_CURRENCY).
All user ID sync activity should be done using the getUserSyncs
callback of the BaseAdapter
model.
Given an array of all the responses from the server, getUserSyncs
is used to determine which user syncs should occur. The order of syncs in the serverResponses
array matters. The most important ones should come first, since publishers may limit how many are dropped on their page.
See below for an example implementation. For more examples, search for getUserSyncs
in the modules directory in the repo.
The onTimeout
function will be called when an adapter has timed out for an auction. The adapter can fire an ajax or pixel call to register the timeout at their end.
Sample data passed to this function:
The onBidWon
function will be called when a bid from the adapter won the auction.
Sample data received by this function:
The onSetTargeting
function will be called when the adserver targeting has been set for a bid from the adapter.
Sample data received by this function:
The onBidderError
function will be called when the bidder responded with an error. Which means that the HTTP response status code is not between 200-299
and not equal to 304
.
Sample data received by this function:
Use aliases if you want to reuse your adapter using other name for your partner/client, or just a shortcut name.
spec.aliases can be an array of strings or objects.
If the alias entry is an object, the following attributes are supported:
Name | Scope | Description | Type |
---|---|---|---|
code |
required | shortcode/partner name | string |
gvlid |
optional | global vendor list id of company scoped to alias | integer |
skipPbsAliasing |
optional | ability to skip passing spec.code to prebid server in request extension. In case you have a prebid server adapter with the name same as the alias/shortcode. Default value: false
|
boolean |
If your bid adapter is going to be used in Europe, you should support GDPR:
If your bid adapter is going to be used in the United States, you should support COPPA and CCPA:
Follow the steps in this section to ensure that your adapter properly supports video.
Add the supportedMediaTypes
argument to the spec object, and make sure VIDEO is in the list:
If your adapter supports banner and video media types, make sure to include 'banner'
in the supportedMediaTypes
array as well
Video parameters are often passed in from the ad unit in a video
object. As of Prebid 4.0 the following paramters should be read from the ad unit when available; bidders can accept overrides of the ad unit on their bidder configuration parameters but should read from the ad unit configuration when their bidder parameters are not set. Parameters one should expect on the ad unit include:
The design of these parameters may vary depending on what your server-side bidder accepts. If possible, we recommend using the video parameters in the OpenRTB specification.
For examples of video parameters accepted by different adapters, see the list of bidders with video demand.
Video ad units have a publisher-defined video context, which can be either 'instream'
or 'outstream'
or 'adpod'
. Video demand partners can choose to ingest this signal for targeting purposes. For example, the ad unit shown below has the outstream video context:
...
mediaTypes: {
video: {
context: 'outstream',
playerSize: [640, 480],
mimes: ['video/mp4'],
protocols: [1, 2, 3, 4, 5, 6, 7, 8],
playbackmethod: [2],
skip: 1
// video params must be read from here in place of
// or instead of bidder-specific parameters
},
},
...
You can check for the video context in your adapter as shown below, and then modify your response as needed:
const videoMediaType = utils.deepAccess(bid, 'mediaTypes.video');
const context = utils.deepAccess(bid, 'mediaTypes.video.context');
if (bid.mediaType === 'video' || (videoMediaType && context !== 'outstream')) {
/* Do something here. */
}
The following is Prebid’s way to setup bid request for long-form, adapters are free to choose their own approach.
Prebid now accepts multiple bid responses for a single bidRequest.bids
object. For each Ad pod Prebid expects you to send back n bid responses. It is up to you how bid responses are returned. Prebid’s recommendation is that you expand an Ad pod placement into a set of request objects according to the total adpod duration and the range of duration seconds. It also depends on your endpoint as well how you may want to create your request for long-form. Appnexus adapter follows below algorithm to expand its placement.
AdUnit config
{
...
adPodDuration: 300,
durationRangeSec: [15, 30]
...
}
Algorithm
# of placements = adPodDuration / MIN_VALUE(durationRangeSec)
Each placement set max duration:
placement.video.maxduration = MAX_VALUE(durationRangeSec)
Example:
# of placements : 300 / 15 = 20.
placement.video.maxduration = 30 (all placements the same)
Your endpoint responds with:
10 bids with 30 seconds duration
10 bids with 15 seconds duration
In Use case 1, you are asking endpoint to respond with 20 bids between min duration 0 and max duration 30 seconds. If you get bids with duration which does not match duration in durationRangeSec
array, Prebid will evaluate the bid’s duration and will match into the appropriate duration bucket by using a rounding-type logic. This new duration will be used in sending bids to Ad server.
Prebid creates virtual duration buckets based on durationRangeSec
value. Prebid will
durationRangeSec
was [5, 15, 30] -> 2s is rounded to 5s; 17s is rounded back to 15s; 18s is rounded up to 30s)Prebid will set the rounded duration value in the bid.video.durationBucket
field for accepted bids
AdUnit config
{
...
adPodDuration: 300,
durationRangeSec: [15, 30],
requireExactDuration: true
...
}
Algorithm
# of placements = MAX_VALUE(adPodDuration/MIN_VALUE(allowedDurationsSec), durationRangeSec.length)
Each placement:
placement.video.minduration = durationRangeSec[i]
placement.video.maxduration = durationRangeSec[i]
Example:
# of placements : MAX_VALUE( (300 / 15 = 20), 2) == 20
20 / 2 = 10 placements:
placement.video.minduration = 15
placement.video.maxduration = 15
20 / 2 = 10 placements:
placement.video.minduration = 30
placement.video.maxduration = 30
Your endpoint responds with:
10 bids with 30 seconds duration
10 bids with 15 seconds duration
In Use case 2 requireExactDuration
is set to true and hence Prebid will only select bids that exactly match duration in durationRangeSec
(don’t round at all).
In both use cases, adapter is requesting bid responses for 20 placements in one single http request. You can split these into chunks depending on your endpoint’s capacity.
Adapter must add following new properties to bid response
Appnexus Adapter uses above explained approach. You can refer here
Adapter must return one IAB accepted subcategories (links to MS Excel file) if they want to support competitive separation. These IAB sub categories will be converted to Ad server industry/group. If adapter is returning their own proprietary categroy, it is the responsibility of the adapter to convert their categories into IAB accepted subcategories (links to MS Excel file).
If the demand partner is going to use Prebid API for this process, their adapter will need to include the getMappingFileInfo
function in their spec file. Prebid core will use the information returned from the function to preload the mapping file in local storage and update on the specified refresh cycle.
Params
Key | Scope | Description | Example |
---|---|---|---|
url |
Required | The URL to the mapping file. | "//example.com/mapping.json" |
refreshInDays |
Optional | A number representing the number of days before the mapping values are updated. Default value is 1 | 7 |
localStorageKey |
Optional | A unique key to store the mapping file in local storage. Default value is bidder code. | "uniqueKey" |
Example
getMappingFileInfo: function() {
return {
url: '<mappingFileURL>',
refreshInDays: 7
localStorageKey: '<uniqueCode>'
}
}
The mapping file is stored locally to expedite category conversion. Depending on the size of the adpod each adapter could have 20-30 bids. Storing the mapping file locally will prevent HTTP calls being made for each category conversion.
To get the subcategory to use, call this function, which needs to be imported from the bidderFactory
.
getIabSubCategory(bidderCode, pCategory)
Params
Key | Scope | Description | Example |
---|---|---|---|
bidderCode |
Required | BIDDER_CODE defined in spec. | "sample-biddercode" |
pCategory |
Required | Proprietary category returned in bid response | "sample-category" |
Example
As described in Show Outstream Video Ads, for an ad unit to play outstream ads, a “renderer” is required. A renderer is the client-side code (usually a combination of JavaScript, HTML, and CSS) responsible for displaying a creative on a page. A renderer must provide a player environment capable of playing a video creative (most commonly an XML document).
If possible, we recommend that publishers associate a renderer with their outstream video ad units. By doing so, all video-enabled demand partners will be able to participate in the auction, regardless of whether a given demand partner provides a renderer on its bid responses. Prebid.js will always invoke a publisher-defined renderer on a given ad unit.
However, if the publisher does not define a renderer, you will need to return a renderer with your bid response if you want to participate in the auction for outstream ad unit.
The returned VAST URL or raw VAST XML should be added into bid.vastUrl
or bid.vastXml
, respectively.
For example:
To do deals for long-form video (adpod
ad unit) just add the dielTier
integer value to bid.video.dealTier
. For more details on conducting deals in ad pods see our ad pod module documentation.
In order for your bidder to support the native media type:
adUnit.mediaTypes.native
object, as described in Show Native Ads.FEATURES.NATIVE
) before doing #2 or #3. This allows users not interested in native to build your adapter without any native-specific code.The adapter code samples below fulfills requirement #2, unpacking the server’s reponse and:
native
object with those assets.The full list of assets your bidder can set are defined in Table 3: Native Assets Recognized by Prebid.js. All assets can be returned as strings, or images can be returned as objects with attributes url
, height
, and width
.
Here’s an example of returning image sizes:
/* Does the bidder respond with native assets? */
else if (FEATURES.NATIVE && rtbBid.rtb.native) {
const nativeResponse = rtbBid.rtb.native;
/* */
bid.native = {
title: nativeResponse.title,
image: {
url: nativeResponse.img.url,
height: nativeResponse.img.height,
width: nativeResponse.img.width,
},
icon: nativeResponse.icon.url,
};
}
The targeting key hb_native_image
(about which more here (ad ops setup) and here (engineering setup)) will be set with the value of image.url
if image
is an object.
If image
is a string, hb_native_image
will be populated with that string (a URL).
Every adapter submission must include unit tests. For details about adapter testing requirements, see the Writing Tests section of CONTRIBUTING.md.
For example tests, see the existing adapter test suites.
pbjs: true
. If you also have a Prebid Server bid adapter, add pbs: true
. Default is false for both.gvl_id
.gdpr_supported: true
. Default is false.usp_supported: true
. Default is false.userId: (list of supported vendors)
. No default value.media_types: video, native
. Note that display is added by default. If you don’t support display, add “no-display” as the first entry, e.g. media_types: no-display, native
. No default value.coppa_supported: true
. Default is false.schain_supported: true
. Default is false.dchain_supported: true
. Default is false.safeframes_ok: false
. This will alert publishers to not use safeframed creatives when creating the ad server entries for your bidder. No default value.deals_supported: true
. No default value..floors_supported: true
. No default value..fpd_supported: true
. No default value.ortb_blocking_supported
to ‘true’,’partial’, or ‘false’. No default value. In order to set ‘true’, you must support: bcat, badv, battr, and bapp.prebid_member: true
. Default is false.For example:
---
layout: bidder
title: example
description: Prebid example Bidder Adapter
biddercode: example
aliasCode: fileContainingPBJSAdapterCodeIfDifferentThenBidderCode
gdpr_supported: true/false
gvl_id: none
usp_supported: true/false
coppa_supported: true/false
schain_supported: true/false
dchain_supported: true/false
userId: (list of supported vendors)
media_types: banner, video, native
safeframes_ok: true/false
deals_supported: true/false
floors_supported: true/false
fpd_supported: true/false
pbjs: true/false
pbs: true/false
prebid_member: true/false
multiformat_supported: will-bid-on-any, will-bid-on-one, will-not-bid
ortb_blocking_supported: true/partial/false
---
### Note:
The Example Bidding adapter requires setup before beginning. Please contact us at setup@example.com
### Bid Params
{: .table .table-bordered .table-striped }
| Name | Scope | Description | Example | Type |
|---------------|----------|-----------------------|-----------|-----------|
| `placement` | required | Placement id | `'11111'` | `string` |
Within a few days, the code pull request will be assigned to a developer for review. Once the inspection passes, the code will be merged and included with the next release. Once released, the documentation pull request will be merged.
The Prebid.org download page will automatically be updated with your adapter once everything’s been merged.