The ad unit object is where you configure what kinds of ads you will show in a given ad slot on your page, including:
It’s also where you will configure bidders, e.g.:
This page describes the properties of the adUnit
object.
See the table below for the list of properties on the ad unit. For example ad units, see the Examples below.
Name | Scope | Type | Description |
---|---|---|---|
code |
Required | String | An identifier you create and assign to this ad unit. Generally this is set to the ad slot name or the div element ID. Used by setTargetingForGPTAsync() to match which auction is for which ad slot. |
bids |
Optional | Array[Object] | Array of bid objects representing demand partners and associated parameters for a given ad unit. See Bids below. |
mediaTypes |
Optional | Object | Defines one or more media types that can serve into the ad unit. For a list of properties, see adUnit.mediaTypes below. |
labelAny |
Optional | Array[String] | Used for conditional ads. Works with sizeConfig argument to pbjs.setConfig. |
labelAll |
Optional | Array[String] | Used for conditional ads. Works with sizeConfig argument to pbjs.setConfig. |
ortb2Imp |
Optional | Object | ortb2Imp is used to signal OpenRTB Imp objects at the adUnit grain. Similar to the global ortb2 field used for global first party data configuration, but specific to this adunit. |
ttlBuffer |
Optional | Number | TTL buffer override for this adUnit. See setConfig({ttlBuffer}) |
renderer |
Optional | Object | Custom renderer, typically used for outstream video |
video |
Optional | Object | Used to link an Ad Unit to the Video Module. For allowed params see the adUnit.video reference. |
See the table below for the list of properties in the bids
array of the ad unit. For example ad units, see the Examples below.
Note that bids
is optional only for Prebid Server stored impressions, and required in all other cases.
Name | Scope | Type | Description |
---|---|---|---|
bidder |
Optional | String | Unique code identifying the bidder. For bidder codes, see the bidder param reference. |
module |
Optional | String | Module code - for requesting bids from modules that are not bid adapters. See Prebid Server stored impressions. |
params |
Required | Object | Bid request parameters for a given bidder. For allowed params, see the bidder param reference. |
labelAny |
Optional | Array[String] | Used for conditional ads. Works with sizeConfig argument to pbjs.setConfig. |
labelAll |
Optional | Array[String] | Used for conditional ads. Works with sizeConfig argument to pbjs.setConfig. |
ortb2Imp |
Optional | Object | OpenRTB first-party data specific to this bidder. This is merged with, and takes precedence over, adUnit.ortb2Imp . |
renderer |
Optional | Object | Custom renderer. Takes precedence over adUnit.renderer , but applies only to this bidder. |
See the table below for the list of properties in the mediaTypes
object of the ad unit. For example ad units showing the different media types, see the Examples below.
Name | Scope | Type | Description |
---|---|---|---|
banner |
At least one of the banner , native , or video objects are required. |
Object | Defines properties of a banner ad. For examples, see adUnit.mediaTypes.banner . |
native |
At least one of the banner , native , or video objects are required. |
Object | Defines properties of a native ad. For properties, see adUnit.mediaTypes.native . |
video |
At least one of the banner , native , or video objects are required. |
Object | Defines properties of a video ad. For examples, see adUnit.mediaTypes.video . |
Name | Scope | Type | Description |
---|---|---|---|
sizes |
Required | Array[Number] or Array[Array[Number]] | All sizes this ad unit can accept. Examples: [400, 600] , [[300, 250], [300, 600]] . Prebid recommends that the sizes auctioned by Prebid should be the same auctioned by AdX and GAM OpenBidding, which means AdUnit sizes should match the GPT sizes. |
pos |
Optional | Integer | OpenRTB page position value: 0=unknown, 1=above-the-fold, 3=below-the-fold, 4=header, 5=footer, 6=sidebar, 7=full-screen |
name |
Optional | String | Name for this banner ad unit. Can be used for testing and debugging. |
The native
object contains properties that correspond to the assets of the native ad.
See Prebid Native Implementation for details.
Name | Scope | Type | Description |
---|---|---|---|
pos |
Optional | Integer | OpenRTB page position value: 0=unknown, 1=above-the-fold, 3=below-the-fold, 4=header, 5=footer, 6=sidebar, 7=full-screen |
context |
Recommended | String | The video context, either 'instream' , 'outstream' , or 'adpod' (for long-form videos). Example: context: 'outstream' . Defaults to ‘instream’. |
useCacheKey |
Optional | Boolean | Defaults to false . While context 'instream' always will return an vastUrl in bidResponse, 'outstream' will not. Setting this true will use cache url defined in global options also for outstream responses. |
placement |
Recommended | Integer | 1=in-stream, 2=in-banner, 3=in-article, 4=in-feed, 5=interstitial/floating. Highly recommended because some bidders require more than context=outstream. |
playerSize |
Optional | Array[Integer,Integer] | The size (width, height) of the video player on the page, in pixels. Example: playerSize: [640, 480] |
api |
Recommended | Array[Integer] | List of supported API frameworks for this impression. If an API is not explicitly listed, it is assumed not to be supported. For list, see OpenRTB 2.5 spec. If your video player or video ads SDK supports Open Measurement, recommended to set 7 for OMID-1 |
mimes |
Recommended | Array[String] | Content MIME types supported, e.g., "video/x-ms-wmv" , "video/mp4" . Required by OpenRTB when using Prebid Server. |
protocols |
Optional | Array[Integer] | Array of supported video protocols. For list, see OpenRTB 2.5 spec. Required by OpenRTB when using Prebid Server. |
playbackmethod |
Optional | Array[Integer] | Allowed playback methods. If none specified, all are allowed. For list, see OpenRTB 2.5 spec. Required by OpenRTB when using Prebid Server. |
minduration |
Recommended | Integer | Minimum video ad duration in seconds, see OpenRTB 2.5 spec. |
maxduration |
Recommended | Integer | Maximum video ad duration in seconds, see OpenRTB 2.5 spec. |
w |
Recommended | Integer | Width of the video player in device independent pixels (DIPS)., see OpenRTB 2.5 spec. |
h |
Recommended | Integer | Height of the video player in device independent pixels (DIPS)., see OpenRTB 2.5 spec. |
startdelay |
Recommended | Integer | Indicates the start delay in seconds, see OpenRTB 2.5 spec. |
linearity |
Optional | Integer | Indicates if the impression must be linear, nonlinear, etc, see OpenRTB 2.5 spec. |
skip |
Optional | Integer | Indicates if the player will allow the video to be skipped, where 0 = no, 1 = yes., see OpenRTB 2.5 spec. |
skipmin |
Optional | Integer | Videos of total duration greater than this number of seconds can be skippable; only applicable if the ad is skippable., see OpenRTB 2.5 spec. |
skipafter |
Optional | Integer | Number of seconds a video must play before skipping is enabled; only applicable if the ad is skippable., see OpenRTB 2.5 spec. |
minbitrate |
Optional | Integer | Minimum bit rate in Kbps., see OpenRTB 2.5 spec. |
maxbitrate |
Optional | Integer | Maximum bit rate in Kbps., see OpenRTB 2.5 spec. |
delivery |
Optional | Array[Integer] | Supported delivery methods (e.g., streaming, progressive), see OpenRTB 2.5 spec. |
pos |
Optional | Integer | Ad position on screen, see OpenRTB 2.5 spec. |
playbackend |
Optional | Integer | The event that causes playback to end, see OpenRTB 2.5 spec. |
If 'video.context'
is set to 'adpod'
then the following parameters are also available.
Name | Scope | Type | Description |
---|---|---|---|
adPodDurationSec |
Required | Number | The length of the adpod in seconds. Example: adPodDurationSec = 120 |
durationRangeSec |
Required | Array[Number] | An array of numbers represents a list of the potential/accepted duration values that the creatives can be in the adpod block. Example: durationRangeSec = [30, 60, 90] |
requireExactDuration |
Optional | Boolean | Whether the returned creatives running time must match the value of adPodDurationSec . Example: requireExactDuration = true |
tvSeriesName |
Optional | String | The name of the television series video the adpod will appear in. Example: tvSeriesName = 'Once Upon A Time' |
tvEpisodeName |
Optional | String | The name of the episode of the television series video the adpod will appear in. Example: tvEpisodeName = 'Pilot' |
tvSeasonNumber |
Optional | Number | A number representing the season number of the television series video the adpod will appear in. Example: tvSeasonNumber = 1 |
tvEpisodeNumber |
Optional | Number | A number representing the episode number of the television series video the adpod will appear in. Example: tvEpisodeNumber = 1 |
contentLengthSec |
Optional | Number | A number representing the length of the video in seconds. Example: contentLengthSec = 1 |
contentMode |
Optional | String | A string indicating the type of content being displayed in the video player. There are two options, live and on-demand . Example: contentMode = 'on-demand' |
See the table below for the list of properties in the video
object of the ad unit. For example ad units, see the Example below.
Note: your Ad Unit must have mediaTypes.video
defined and your prebid instance should be configured to use the Video Module.
When using the Video Module, the mediaTypes.video properties get filled out automatically. Any values already set by the Publisher will not be replaced by the Video Module.
Field | Scope | Type | Description |
---|---|---|---|
divId |
required | string | Unique identifier of the player provider, used to specify which player should be used to render the ad. Equivalent to the HTML Div Id of the player. |
adServer |
optional | object | Configuration for ad server integration. Supersedes video.adServer configurations defined in the Prebid Config. |
adServer.vendorCode |
required if adServer is defined |
string | The identifier of the AdServer vendor (i.e. gam, etc). |
adServer.baseAdTagUrl |
required if adServer.params is not defined |
string | Your AdServer Ad Tag. The targeting params of the winning bid will be appended. |
adServer.params |
required if adServer.baseAdTagUrl is not defined |
object | Querystring parameters that will be used to construct the video ad tag URL. |
For an example of a banner ad unit, see below. For more detailed instructions, see Getting Started.
pbjs.addAdUnits({
code: slot.code,
mediaTypes: {
banner: {
sizes: [[300, 250]]
}
},
bids: [
{
bidder: 'appnexus',
params: {
placementId: 13144370
}
}
]
});
For an example of a video ad unit linked to the Video Module, see below. For more detailed instructions see the Video Module docs.
pbjs.addAdUnits({
code: slot.code,
mediaTypes: {
video: {},
},
video: {
divId: 'playerDiv',
adServer: {
vendorCode: 'gam', // constant variable is GAM_VENDOR - see vendorCodes.js in the video library
baseAdTagUrl: 'https://pubads.g.doubleclick.net/gampad/ads?iu=/12345/'
}
},
bids: [{
bidder: 'appnexus',
params: {
placementId: 13232361
}
}]
});
For an example of an instream video ad unit that you handle on your own, see below. For more detailed instructions, see Show Video Ads.
pbjs.addAdUnits({
code: slot.code,
mediaTypes: {
video: {
context: 'instream',
playerSize: [640, 480],
mimes: ['video/mp4'],
protocols: [1, 2, 3, 4, 5, 6, 7, 8],
playbackmethod: [2],
skip: 1
},
},
bids: [{
bidder: 'appnexus',
params: {
placementId: 13232361
}
}]
});
For an example of an outstream video ad unit that you handle on your own, see below. For more detailed instructions, see Show Outstream Video Ads.
pbjs.addAdUnits({
code: slot.code,
mediaTypes: {
video: {
context: 'outstream',
useCacheKey: false,
playerSize: [640, 480]
}
},
renderer: {
url: 'https://cdn.adnxs.com/renderer/video/ANOutstreamVideo.js',
render: function(bid) {
ANOutstreamVideo.renderAd({
targetId: bid.adUnitCode,
adResponse: bid.adResponse,
});
}
},
...
});
An example of an outstream video ad unit using useCacheKey:
pbjs.addAdUnits({
code: slot.code,
mediaTypes: {
video: {
context: 'outstream',
useCacheKey: true,
playerSize: [640, 480]
}
},
renderer: {
url: 'https://example.com/myVastVideoPlayer.js',
render: function(bid) {
let vastUrl = bid.vastUrl;
myVastVideoPlayer.setSrc({
src: vastUrl,
...
});
}
},
...
});
For an example of an adpod video ad unit that you handle on your own, see below. For more detailed instructions, see Show Long-Form Video Ads.
var longFormatAdUnit = {
video: {
// required params
context: 'adpod',
playerSize: [640, 480],
adPodDurationSec: 300,
durationRangeSec: [15, 30],
// optional params
requireExactDuration: true,
tvSeriesName: 'TvName',
tvEpisodeName: 'episodeName',
tvSeasonNumber: 3,
tvEpisodeNumber: 6,
contentLength: 300, // time in seconds,
contentMode: 'on-demand'
}
bids: [{
bidder: 'appnexus',
params: {
placementId: '123456789',
}
}]
}
For an example of a native ad unit, see below. For more detailed instructions, see Show Native Ads.
pbjs.addAdUnits({
code: slot.code,
mediaTypes: {
native: {
ortb: {
ver: "1.2",
assets: [{
required: 1,
img: {
type: 1,
hmin: 50
},
},{
required: 1,
title: {
len: 80
},
},{
required: 1,
data: {
type: 1,
len: 30
},
},{
required: 1,
data: {
type: 2,
len: 100
},
},{
required: 1,
img: {
type: 3,
hmin: 200,
wmin: 267
}
}]
}
}
},
bids: [
{
bidder: 'appnexus',
params: {
placementId: 13232354
}
}
]
});
For an example of a multi-format ad unit, see below. For more detailed instructions, see Show Multi-Format Ads.
It’s ok to have multiple AdUnits with the same code
. This can be useful in scenarios
where bidders have different capabilities for the same spot on the page. e.g.
In this example, bidderA gets both banner and outstream, while bidderB gets only banner.
In this example, bidderA receives 2 bidRequest objects while bidderB receives one. If a bidder provides more than one bid for the same AdUnit.code, Prebid.js will use the highest bid when it’s time to set targeting.
Example of an adunit-specific block of first party data:
Notes:
Example of an adunit-specific interstitial signal:
For more information on Interstitial ads, reference the Interstitial feature page.
When using PBS stored impressions, bids
is not required:
pbjs.addAdUnits({
code: "test-div",
ortb2Imp: {
ext: {
prebid: {
storedrequest: {
id: 'stored-request-id'
}
}
}
}
})
To use stored impressions together with client-side bidders - or stored impressions from other instances of Prebid Server - use bids[].module
:
pbjs.addAdUnits({
code: "test-div",
bids: [
{
module: "pbsBidAdapter",
params: {
configName: "server-1"
},
ortb2Imp: {
ext: {
prebid: {
storedrequest: {
id: 'stored-request-server-1'
}
}
}
}
},
{
module: "pbsBidAdapter",
params: {
configName: "server-2"
},
ortb2Imp: {
ext: {
prebid: {
storedrequest: {
id: 'stored-request-server-2'
}
}
}
}
},
{
bidder: 'client-bidder',
// ...
}
]
});