| layout | title | description | top_nav_section | nav_section | pid | sidebarType |
|---|---|---|---|---|---|---|
page_v2 |
Ad Unit Reference |
Ad Unit Reference |
dev_docs |
reference |
10 |
1 |
{:.no_toc}
The ad unit object is where you configure what kinds of ads you will show in a given ad slot on your page, including:
- Allowed sizes
- Allowed media types (e.g., banner, native, and/or video)
It's also where you will configure bidders, e.g.:
- Which bidders are allowed to bid for that ad slot
- What information is passed to those bidders via their parameters
This page describes the properties of the adUnit object.
- TOC {:toc}
See the table below for the list of properties on the ad unit. For example ad units, see the Examples below.
{: .table .table-bordered .table-striped }
| Name | Scope | Type | Description |
|--------------+----------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| code | Required | String | Unique identifier 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 sizes this ad unit can accept. Examples: [400, 600], [[300, 250], [300, 600]]. For 1.0 and later, define sizes within the appropriate mediaTypes.{banner,native,video} object. |
| bids | Required | 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. |
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.
{: .table .table-bordered .table-striped }
| Name | Scope | Type | Description |
|------------+----------+---------------+------------------------------------------------------------------------------------------------------------------------------------------|
| bidder | Required | String | Unique code identifying the bidder. For bidder codes, see the bidder param reference. |
| 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. |
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.
{: .table .table-bordered .table-striped }
| 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. |
{: .table .table-bordered .table-striped }
| 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]]. |
| name | Optional | String | Name for this banner ad unit. Can be used for testing and debugging. |
The native object contains the following properties that correspond to the assets of the native ad.
{: .table .table-bordered .table-striped }
| Name | Scope | Type | Description |
|---------------+----------+--------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| type | Optional | String | A pre-defined native type used as a shorthand, e.g., type: 'image' implies required fields image, title, sponsoredBy, clickUrl. |
| title | Optional | Object | The title object is to be used for the title element of the native ad. For properties, see native.title. |
| body | Optional | Object | The body object is to be used for the body element of the native ad. For properties, see native.body. |
| sponsoredBy | Optional | Object | The name of the brand associated with the ad. For properties, see native.sponsoredBy. |
| icon | Optional | Object | The brand icon that will appear with the ad. For properties, see native.icon. |
| image | Optional | Object | The image object is to be used for the main image of the native ad. For properties, see native.image. |
| clickUrl | Optional | Object | Where the user will end up if they click the ad. For properties, see native.clickUrl. |
| cta | Optional | String | Call to Action text, e.g., "Click here for more information". |
{: .table .table-bordered .table-striped }
| Name | Scope | Type | Description |
|-----------------+----------+---------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------|
| required | Optional | Boolean | Whether this asset is required. |
| sizes | Optional | Array[Number] or Array[Array[Number]] | All sizes this ad unit can accept. Examples: [400, 600], [[300, 250], [300, 600]]. |
| aspect_ratios | Optional | Array[Object] | Alongside sizes, you can define allowed aspect ratios. For properties, see image.aspect_ratios. |
{: .table .table-bordered .table-striped }
| Name | Scope | Type | Description |
|----------------+----------+---------+------------------------------------------------------------------------------------------------------|
| min_width | Optional | Integer | The minimum width required for an image to serve (in pixels). |
| ratio_height | Required | Integer | This, combined with ratio_width, determines the required aspect ratio for an image that can serve. |
| ratio_width | Required | Integer | See above. |
{: .table .table-bordered .table-striped }
| Name | Scope | Type | Description |
|------------+----------+---------+------------------------------------------------------|
| required | Optional | Boolean | Whether a title asset is required on this native ad. |
| len | Optional | Integer | Maximum length of title text, in characters. |
{: .table .table-bordered .table-striped }
| Name | Scope | Type | Description |
|------------+----------+---------+-----------------------------------------------------------|
| required | Optional | Boolean | Whether a brand name asset is required on this native ad. |
{: .table .table-bordered .table-striped }
| Name | Scope | Type | Description |
|------------+----------+---------+----------------------------------------------------------|
| required | Optional | Boolean | Whether a click URL asset is required on this native ad. |
{: .table .table-bordered .table-striped }
| Name | Scope | Type | Description |
|------------+----------+---------+---------------------------------------------------|
| required | Optional | Boolean | Whether body text is required for this native ad. |
| len | Optional | Integer | Maximum length of body text, in characters. |
{: .table .table-bordered .table-striped }
| Name | Scope | Type | Description |
|-----------------+----------+---------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------|
| required | Optional | Boolean | Whether an icon asset is required on this ad. |
| sizes | Optional | Array[Number] or Array[Array[Number]] | All sizes this ad unit can accept. Examples: [400, 600], [[300, 250], [300, 600]]. |
| aspect_ratios | Optional | Array[Object] | Instead of sizes, you can define allowed aspect ratios. For properties, see icon.aspect_ratios. |
{: .table .table-bordered .table-striped }
| Name | Scope | Type | Description |
|----------------+----------+---------+------------------------------------------------------------------------------------------------------|
| min_width | Optional | Integer | The minimum width required for an image to serve (in pixels). |
| ratio_height | Required | Integer | This, combined with ratio_width, determines the required aspect ratio for an image that can serve. |
| ratio_width | Required | Integer | See above. |
{: .table .table-bordered .table-striped }
| Name | Scope | Type | Description |
|------------------+-------------+------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| context | Optional | String | The video context, either 'instream' or 'outstream'. Example: 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 spec. |
| 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 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 spec. Required by OpenRTB when using Prebid Server. |
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 an instream video ad unit, see below. For more detailed instructions, see Show Video Ads.
pbjs.addAdUnits({
code: slot.code,
mediaTypes: {
video: {
context: 'instream',
playerSize: [640, 480],
},
},
bids: [{
bidder: 'appnexus',
params: {
placementId: 13232361,
video: {
skippable: true,
playback_methods: ['auto_play_sound_off']
}
}
}]
});For an example of an outstream video ad unit, see below. For more detailed instructions, see Show Outstream Video Ads.
pbjs.addAdUnits({
code: slot.code,
mediaTypes: {
video: {
context: 'outstream',
playerSize: [640, 480]
}
},
renderer: {
url: 'http://cdn.adnxs.com/renderer/video/ANOutstreamVideo.js',
render: function(bid) {
ANOutstreamVideo.renderAd({
targetId: bid.adUnitCode,
adResponse: bid.adResponse,
});
}
},
...
});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
}
}
]
});For an example of a multi-format ad unit, see below. For more detailed instructions, see Show Multi-Format Ads.
{% highlight js %}
pbjs.addAdUnits([{ code: 'div-banner-native', mediaTypes: { banner: { sizes: [ [300, 250] ] }, native: { type: 'image' }, }, bids: [{ bidder: 'appnexus', params: { placementId: 13232392, } }] },
{
code: 'div-banner-outstream',
mediaTypes: {
banner: {
sizes: [
[300, 250]
]
},
video: {
context: 'outstream',
playerSize: [300, 250]
},
},
bids: [{
bidder: 'appnexus',
params: {
placementId: 13232392,
}
}, ]
},
{
code: 'div-banner-outstream-native',
mediaTypes: {
banner: {
sizes: [
[300, 250]
]
},
native: {
type: 'image'
},
video: {
context: 'outstream',
playerSize: [300, 250]
},
},
bids: [{
bidder: 'appnexus',
params: {
placementId: 13232392,
}
}, ]
}
]);
{% endhighlight %}