Back to Publisher API Reference
pbjs.addAdUnits(Array|Object)
Takes one ad unit object or an array of ad unit objects and adds them to the Prebid auction. For usage examples, see Examples below and the Getting Started page.
Ad Unit Properties
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 | Unique identifier that you create and assign to this ad unit. Used to set query string targeting on the ad. If using GPT, we recommend setting this to slot element ID. |
sizes |
Required | Array[Number] or Array[Array[Number]] | All the sizes that this ad unit can accept. Examples: [400, 600] , [[300, 250], [300, 600]] . For 1.0 and later, prefer mediaTypes.banner.sizes . |
bids |
Optional | Array[Object] | Each bid represents a request to a bidder. For a list of properties, see Bids below. |
mediaTypes |
Optional | Object | Defines one or multiple media types the ad unit supports. For a list of properties, see Media Types below. |
labelAny |
optional | array |
An array of string labels, used for showing responsive ads. With the labelAny operator, just one label has to match for the condition to be true. Works with the sizeConfig object passed in to pbjs.setConfig. |
labelAll |
optional | array |
An array of string labels, used for showing responsive and conditional ads. With the labelAll conditional, every element of the target array must match an element of the label array in order for the condition to be true. Works with the sizeConfig object passed in to pbjs.setConfig. |
video |
Optional | Object | Used to link an Ad Unit to the Video Module. For allowed params see the adUnit.video reference. |
Bids
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 |
Required | String | Bidder code. Find the complete reference for all supported bidders here. |
params |
Required | Object | Bidder’s preferred way of identifying a bid request. Find the complete reference for all supported bidders here. |
labelAny |
optional | array |
An array of string labels, used for showing responsive ads. With the labelAny operator, just one label has to match for the condition to be true. Works with the sizeConfig object passed in to pbjs.setConfig. |
labelAll |
optional | array |
An array of string labels, used for showing responsive and conditional ads. With the labelAll conditional, every element of the target array must match an element of the label array in order for the condition to be true. Works with the sizeConfig object passed in to pbjs.setConfig. |
Media Types
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 |
optional. If no other properties are specified, this is the default | Object | Defines properties of a banner ad. For examples, see the banner example below. |
native |
optional | Object | Defines properties of a native ad. For an example native ad unit, see the native example below. |
video |
optional | Object | Defines properties of a video ad. For examples, see the video examples below. |
Video
For the list of properties please visit the adUnit.video reference.
Examples
MediaType Native
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: {
image: {
required: true,
sizes: [150, 50]
},
title: {
required: true,
len: 80
},
sponsoredBy: {
required: true
},
clickUrl: {
required: true
},
body: {
required: true
},
icon: {
required: true,
sizes: [50, 50]
}
}
},
bids: [
{
bidder: 'appnexus',
params: {
placementId: 13232354
}
}
]
});
There are two methods for defining sizes for image-like assets (image
and icon
). Both are shown below, but the first example (using sizes
) is more widely supported by demand partners.
Using mediaTypes.native.image.sizes
(or mediaTypes.native.icon.sizes
for icons):
mediaTypes: {
native: {
image: {
required: true,
sizes: [150, 50]
}
}
}
Using mediaTypes.native.image.aspect_ratios
(or mediaTypes.native.icon.aspect_ratios
for icons):
mediaTypes: {
native: {
image: {
required: true,
aspect_ratios: [{
min_width: 300, /* Optional */
min_height: 200, /* Optional */
ratio_width: 2, /* Required */
ratio_height: 3, /* Required */
}]
}
}
}
MediaType Video
If using the Video Module, see below. For more information on the Video Module, 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 where the integration is handled 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, see below. For more detailed instructions, see Show Outstream Video Ads.
pbjs.addAdUnit({
code: slot.code,
mediaTypes: {
video: {
context: 'outstream',
playerSize: [640, 480],
mimes: ['video/mp4'],
protocols: [1, 2, 3, 4, 5, 6, 7, 8],
playbackmethod: [2],
skip: 1
}
},
renderer: {
url: 'https://cdn.adnxs.com/renderer/video/ANOutstreamVideo.js',
render: function(bid) {
ANOutstreamVideo.renderAd({
targetId: bid.adUnitCode,
adResponse: bid.adResponse,
});
}
},
...
})
MediaType Banner
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
}
}
]
})
Multi-format
Multiple media formats may be declared on a single ad unit, allowing any bidder that supports at least one of those media formats to participate in the auction. Any bidder that isn’t compatible with the specified mediaTypes
will be dropped from the ad unit. If mediaTypes
is not specified on an ad unit, banner
is the assumed format and any banner bidder is eligible for inclusion.
For examples of a multi-format ad units and behavior, see below.
// each bidder supports at least one of the formats, so all will participate
pbjs.addAdUnits({
code: 'div-banner-outstream-native',
mediaTypes: {
banner: { sizes: [[300, 250], [300, 600]] },
native: {
title: {required: true},
image: {required: true},
body: {required: false},
},
video: {
context: 'outstream',
playerSize: [640, 480],
mimes: ['video/mp4'],
protocols: [1, 2, 3, 4, 5, 6, 7, 8],
playbackmethod: [2],
skip: 1
},
},
bids: [
{
bidder: 'bannerBidder',
params: {placementId: '481'}
},
{
bidder: 'nativeBidder',
params: {titleAsset: '516'}
},
{
bidder: 'videoBidder',
params: {vidId: '234'}
},
]
});
// only nativeBidder and videoBidder will participate
pbjs.addAdUnits({
code: 'div-native-outstream',
mediaTypes: {
native: { type: 'image' },
video: { context: 'outstream', playerSize: [400, 600] },
},
bids: [
{
bidder: 'bannerBidder',
params: {placementId: '481'}
},
{
bidder: 'nativeBidder',
params: {titleAsset: '516'}
},
{
bidder: 'videoBidder',
params: {vidId: '234'}
},
]
});