diff --git a/_data/sidebar.yml b/_data/sidebar.yml
index a193c37130..98a4e60a74 100644
--- a/_data/sidebar.yml
+++ b/_data/sidebar.yml
@@ -399,6 +399,14 @@
sectionTitle:
subgroup: 3
+- sbSecId: 1
+ title: Renderer
+ link: /dev-docs/renderer.html
+ isHeader: 0
+ isSectionHeader: 0
+ sectionTitle:
+ subgroup: 3
+
- sbSecId: 1
title: Bidder Params
link: /dev-docs/bidders.html
diff --git a/dev-docs/adunit-reference.md b/dev-docs/adunit-reference.md
index 5a6967b77a..9f3c4af33b 100644
--- a/dev-docs/adunit-reference.md
+++ b/dev-docs/adunit-reference.md
@@ -27,64 +27,64 @@ This page describes the properties of the `adUnit` object.
## AdUnit
-See the table below for the list of properties on the ad unit. For example ad units, see the [Examples](#adUnit-examples) below.
+See the table below for the list of properties on the ad unit. For example ad units, see the [Examples](#adUnit-examples) below.
{: .table .table-bordered .table-striped }
-| Name | Scope | Type | Description |
+| 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()](/dev-docs/publisher-api-reference/setTargetingForGPTAsync.html) 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](#adUnit.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`](#adUnit.mediaTypes) below. |
-| `labelAny` | Optional | Array[String] | Used for [conditional ads][conditionalAds]. Works with `sizeConfig` argument to [pbjs.setConfig][configureResponsive]. |
-| `labelAll` | Optional | Array[String] | Used for [conditional ads][conditionalAds]. Works with `sizeConfig` argument to [pbjs.setConfig][configureResponsive]. |
-| `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](/dev-docs/publisher-api-reference/setConfig.html#setConfig-fpd), but specific to this adunit.|
-| `ttlBuffer` | Optional | Number | TTL buffer override for this adUnit. See [setConfig({ttlBuffer})](/dev-docs/publisher-api-reference/setConfig.html#setConfig-ttlBuffer) |
-| `renderer` | Optional | Object | Custom renderer, typically used for [outstream video](/dev-docs/show-outstream-video-ads.html) |
-| `video` | Optional | Object | Used to link an Ad Unit to the [Video Module][videoModule]. For allowed params see the [adUnit.video reference](#adunitvideo). |
+| `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()](/dev-docs/publisher-api-reference/setTargetingForGPTAsync.html) 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](#adUnit.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`](#adUnit.mediaTypes) below. |
+| `labelAny` | Optional | Array[String] | Used for [conditional ads][conditionalAds]. Works with `sizeConfig` argument to [pbjs.setConfig][configureResponsive]. |
+| `labelAll` | Optional | Array[String] | Used for [conditional ads][conditionalAds]. Works with `sizeConfig` argument to [pbjs.setConfig][configureResponsive]. |
+| `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](/dev-docs/publisher-api-reference/setConfig.html#setConfig-fpd), but specific to this adunit.|
+| `ttlBuffer` | Optional | Number | TTL buffer override for this adUnit. See [setConfig({ttlBuffer})](/dev-docs/publisher-api-reference/setConfig.html#setConfig-ttlBuffer) |
+| `renderer` | Optional | Object | Custom renderer, typically used for [outstream video](/dev-docs/show-outstream-video-ads.html) |
+| `video` | Optional | Object | Used to link an Ad Unit to the [Video Module][videoModule]. For allowed params see the [adUnit.video reference](#adunitvideo). |
| `deferBilling` | Optional | Boolean | Used by a publisher to flag adUnits as being separately billable. This allows for a publisher to trigger billing manually for winning bids. See [pbjs.triggerBilling](/dev-docs/publisher-api-reference/triggerBilling.html) and [onBidBillable](/dev-docs/bidder-adaptor.html#registering-on-bid-billable) for more info. |
### adUnit.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](#adUnit-examples) below.
+See the table below for the list of properties in the `bids` array of the ad unit. For example ad units, see the [Examples](#adUnit-examples) below.
Note that `bids` is optional only for [Prebid Server stored impressions](#stored-imp), and required in all other cases.
{: .table .table-bordered .table-striped }
-| Name | Scope | Type | Description |
+| Name | Scope | Type | Description |
|------------+----------+---------------+------------------------------------------------------------------------------------------------------------------------------------------|
-| `bidder` | Optional | String | Unique code identifying the bidder. For bidder codes, see the [bidder param reference]({{site.baseurl}}/dev-docs/bidders.html). |
-| `module` | Optional | String | Module code - for requesting bids from modules that are not bid adapters. See [Prebid Server stored impressions](#stored-imp). |
-| `params` | Required | Object | Bid request parameters for a given bidder. For allowed params, see the [bidder param reference]({{site.baseurl}}/dev-docs/bidders.html). |
-| `labelAny` | Optional | Array[String] | Used for [conditional ads][conditionalAds]. Works with `sizeConfig` argument to [pbjs.setConfig][configureResponsive]. |
-| `labelAll` | Optional | Array[String] | Used for [conditional ads][conditionalAds]. Works with `sizeConfig` argument to [pbjs.setConfig][configureResponsive]. |
-| `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. |
+| `bidder` | Optional | String | Unique code identifying the bidder. For bidder codes, see the [bidder param reference]({{site.baseurl}}/dev-docs/bidders.html). |
+| `module` | Optional | String | Module code - for requesting bids from modules that are not bid adapters. See [Prebid Server stored impressions](#stored-imp). |
+| `params` | Required | Object | Bid request parameters for a given bidder. For allowed params, see the [bidder param reference]({{site.baseurl}}/dev-docs/bidders.html). |
+| `labelAny` | Optional | Array[String] | Used for [conditional ads][conditionalAds]. Works with `sizeConfig` argument to [pbjs.setConfig][configureResponsive]. |
+| `labelAll` | Optional | Array[String] | Used for [conditional ads][conditionalAds]. Works with `sizeConfig` argument to [pbjs.setConfig][configureResponsive]. |
+| `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. |
### adUnit.mediaTypes
-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](#adUnit-examples) below.
+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](#adUnit-examples) below.
{: .table .table-bordered .table-striped }
-| Name | Scope | Type | Description |
+| Name | Scope | Type | Description |
|---------------------------------------+--------------------------------------------------------------------------+--------+------------------------------------------------------------------------------------------------------------------|
-| [`banner`](#adUnit.mediaTypes.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`](#adUnit.mediaTypes.banner). |
-| [`native`](#adUnit.mediaTypes.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`](#adUnit.mediaTypes.native). |
-| [`video`](#adUnit.mediaTypes.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`](#adUnit.mediaTypes.video). |
+| [`banner`](#adUnit.mediaTypes.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`](#adUnit.mediaTypes.banner). |
+| [`native`](#adUnit.mediaTypes.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`](#adUnit.mediaTypes.native). |
+| [`video`](#adUnit.mediaTypes.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`](#adUnit.mediaTypes.video). |
#### adUnit.mediaTypes.banner
{: .table .table-bordered .table-striped }
-| Name | Scope | Type | Description |
+| 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. |
+| `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. |
@@ -99,46 +99,46 @@ See [Prebid Native Implementation](/prebid/native-implementation.html) for detai
#### adUnit.mediaTypes.video
{: .table .table-bordered .table-striped }
-| Name | Scope | Type | Description |
+| Name | Scope | Type | Description |
|------------------+-------------+------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `pos` | Optional | Integer | Ad position on screen, see [OpenRTB 2.5 spec][openRTB]. 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. |
-| `plcmt` | Recommended | Integer | 1=in-stream, 2=accompanying content, 3=interstitial, 4=no content/standalone. **Highly recommended** to comply with new IAB video specifications. See [AdCOM v1 spec](https://github.com/InteractiveAdvertisingBureau/AdCOM/blob/develop/AdCOM%20v1.0%20FINAL.md#list_plcmtsubtypesvideo) |
-| `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][openRTB]. If your video player or video ads SDK supports [Open Measurement][OpenMeasurement], **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][pbServer]**. |
-| `protocols` | Optional | Array[Integer] | Array of supported video protocols. For list, see [OpenRTB 2.5 spec][openRTB]. **Required by OpenRTB when using [Prebid Server][pbServer]**. |
-| `playbackmethod` | Optional | Array[Integer] | Allowed playback methods. If none specified, all are allowed. For list, see [OpenRTB 2.5 spec][openRTB]. **Required by OpenRTB when using [Prebid Server][pbServer]**. |
-| `minduration` | Recommended | Integer | Minimum video ad duration in seconds, see [OpenRTB 2.5 spec][openRTB]. |
-| `maxduration` | Recommended | Integer | Maximum video ad duration in seconds, see [OpenRTB 2.5 spec][openRTB]. |
-| `w` | Recommended | Integer | Width of the video player in device independent pixels (DIPS)., see [OpenRTB 2.5 spec][openRTB]. |
-| `h` | Recommended | Integer | Height of the video player in device independent pixels (DIPS)., see [OpenRTB 2.5 spec][openRTB]. |
-| `startdelay` | Recommended | Integer | Indicates the start delay in seconds, see [OpenRTB 2.5 spec][openRTB]. |
-| `linearity` | Optional | Integer | Indicates if the impression must be linear, nonlinear, etc, see [OpenRTB 2.5 spec][openRTB]. |
-| `skip` | Optional | Integer | Indicates if the player will allow the video to be skipped, where 0 = no, 1 = yes., see [OpenRTB 2.5 spec][openRTB]. |
-| `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][openRTB]. |
-| `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][openRTB]. |
-| `minbitrate` | Optional | Integer | Minimum bit rate in Kbps., see [OpenRTB 2.5 spec][openRTB]. |
-| `maxbitrate` | Optional | Integer | Maximum bit rate in Kbps., see [OpenRTB 2.5 spec][openRTB]. |
-| `delivery` | Optional | Array[Integer] | Supported delivery methods (e.g., streaming, progressive), see [OpenRTB 2.5 spec][openRTB]. |
-| `playbackend` | Optional | Integer | The event that causes playback to end, see [OpenRTB 2.5 spec][openRTB]. |
-
-If `'video.context'` is set to `'adpod'` then the following parameters are also available.
+| `pos` | Optional | Integer | Ad position on screen, see [OpenRTB 2.5 spec][openRTB]. 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. |
+| `plcmt` | Recommended | Integer | 1=in-stream, 2=accompanying content, 3=interstitial, 4=no content/standalone. **Highly recommended** to comply with new IAB video specifications. See [AdCOM v1 spec](https://github.com/InteractiveAdvertisingBureau/AdCOM/blob/develop/AdCOM%20v1.0%20FINAL.md#list_plcmtsubtypesvideo) |
+| `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][openRTB]. If your video player or video ads SDK supports [Open Measurement][OpenMeasurement], **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][pbServer]**. |
+| `protocols` | Optional | Array[Integer] | Array of supported video protocols. For list, see [OpenRTB 2.5 spec][openRTB]. **Required by OpenRTB when using [Prebid Server][pbServer]**. |
+| `playbackmethod` | Optional | Array[Integer] | Allowed playback methods. If none specified, all are allowed. For list, see [OpenRTB 2.5 spec][openRTB]. **Required by OpenRTB when using [Prebid Server][pbServer]**. |
+| `minduration` | Recommended | Integer | Minimum video ad duration in seconds, see [OpenRTB 2.5 spec][openRTB]. |
+| `maxduration` | Recommended | Integer | Maximum video ad duration in seconds, see [OpenRTB 2.5 spec][openRTB]. |
+| `w` | Recommended | Integer | Width of the video player in device independent pixels (DIPS)., see [OpenRTB 2.5 spec][openRTB]. |
+| `h` | Recommended | Integer | Height of the video player in device independent pixels (DIPS)., see [OpenRTB 2.5 spec][openRTB]. |
+| `startdelay` | Recommended | Integer | Indicates the start delay in seconds, see [OpenRTB 2.5 spec][openRTB]. |
+| `linearity` | Optional | Integer | Indicates if the impression must be linear, nonlinear, etc, see [OpenRTB 2.5 spec][openRTB]. |
+| `skip` | Optional | Integer | Indicates if the player will allow the video to be skipped, where 0 = no, 1 = yes., see [OpenRTB 2.5 spec][openRTB]. |
+| `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][openRTB]. |
+| `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][openRTB]. |
+| `minbitrate` | Optional | Integer | Minimum bit rate in Kbps., see [OpenRTB 2.5 spec][openRTB]. |
+| `maxbitrate` | Optional | Integer | Maximum bit rate in Kbps., see [OpenRTB 2.5 spec][openRTB]. |
+| `delivery` | Optional | Array[Integer] | Supported delivery methods (e.g., streaming, progressive), see [OpenRTB 2.5 spec][openRTB]. |
+| `playbackend` | Optional | Integer | The event that causes playback to end, see [OpenRTB 2.5 spec][openRTB]. |
+
+If `'video.context'` is set to `'adpod'` then the following parameters are also available.
{: .table .table-bordered .table-striped }
-| Name | Scope | Type | Description |
+| 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'` |
+| `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'` |
@@ -152,9 +152,9 @@ See the table below for the list of properties in the `video` object of the ad u
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.
{: .table .table-bordered .table-striped }
-| Field | Scope | Type | Description |
+| 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. |
+| `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. |
@@ -163,7 +163,7 @@ When using the Video Module, the mediaTypes.video properties get filled out auto
## Examples
* [Banner](#adUnit-banner-example)
-* [Video](#adUnit-video-example)
+* [Video](#adUnit-video-example)
* [With the Video Module](#adUnit-video-module-example)
* [Instream Sound-On](#adUnit-video-example-instream)
* [Accompanying Content](#adUnit-video-example-accompanying)
@@ -178,24 +178,24 @@ When using the Video Module, the mediaTypes.video properties get filled out auto
### Banner
-For an example of a banner ad unit, see below. For more detailed instructions, see [Getting Started]({{site.baseurl}}/dev-docs/getting-started.html).
+For an example of a banner ad unit, see below. For more detailed instructions, see [Getting Started]({{site.baseurl}}/dev-docs/getting-started.html).
```javascript
pbjs.addAdUnits({
- code: slot.code,
- mediaTypes: {
- banner: {
- sizes: [[300, 250]]
- }
+ code: slot.code,
+ mediaTypes: {
+ banner: {
+ sizes: [[300, 250]],
},
- bids: [
- {
- bidder: 'appnexus',
- params: {
- placementId: 13144370
- }
- }
- ]
+ },
+ bids: [
+ {
+ bidder: "appnexus",
+ params: {
+ placementId: 13144370,
+ },
+ },
+ ],
});
```
@@ -211,23 +211,25 @@ For an example of a video ad unit linked to the Video Module, see below. For mor
```javascript
pbjs.addAdUnits({
- code: slot.code,
- mediaTypes: {
- video: {},
+ 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/",
},
- 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,
+ },
},
- bids: [{
- bidder: 'appnexus',
- params: {
- placementId: 13232361
- }
- }]
+ ],
});
```
@@ -239,24 +241,26 @@ For an example of an instream video ad unit that you handle on your own, see bel
```javascript
pbjs.addAdUnits({
- code: slot.code,
- mediaTypes: {
- video: {
- context: 'instream',
- plcmt: 1,
- playerSize: [640, 480],
- mimes: ['video/mp4'],
- protocols: [1, 2, 3, 4, 5, 6, 7, 8],
- playbackmethod: [5],
- skip: 1
- },
+ code: slot.code,
+ mediaTypes: {
+ video: {
+ context: "instream",
+ plcmt: 1,
+ playerSize: [640, 480],
+ mimes: ["video/mp4"],
+ protocols: [1, 2, 3, 4, 5, 6, 7, 8],
+ playbackmethod: [5],
+ skip: 1,
},
- bids: [{
- bidder: 'appnexus',
- params: {
- placementId: 13232361
- }
- }]
+ },
+ bids: [
+ {
+ bidder: "appnexus",
+ params: {
+ placementId: 13232361,
+ },
+ },
+ ],
});
```
@@ -268,24 +272,26 @@ The IAB calls this scenario "Accompanying Content". Previously, this might have
```javascript
pbjs.addAdUnits({
- code: slot.code,
- mediaTypes: {
- video: {
- context: 'instream',
- plcmt: 2,
- playerSize: [640, 480],
- mimes: ['video/mp4'],
- protocols: [1, 2, 3, 4, 5, 6, 7, 8],
- playbackmethod: [6],
- skip: 1
- },
+ code: slot.code,
+ mediaTypes: {
+ video: {
+ context: "instream",
+ plcmt: 2,
+ playerSize: [640, 480],
+ mimes: ["video/mp4"],
+ protocols: [1, 2, 3, 4, 5, 6, 7, 8],
+ playbackmethod: [6],
+ skip: 1,
},
- bids: [{
- bidder: 'appnexus',
- params: {
- placementId: 13232361
- }
- }]
+ },
+ bids: [
+ {
+ bidder: "appnexus",
+ params: {
+ placementId: 13232361,
+ },
+ },
+ ],
});
```
@@ -295,7 +301,7 @@ pbjs.addAdUnits({
This is the scenario formerly known as Outstream. As of April 2023, the IAB now calls this scenario "No Content/Standalone".
-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]({{site.baseurl}}/dev-docs/show-outstream-video-ads.html).
+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]({{site.baseurl}}/dev-docs/show-outstream-video-ads.html).
```javascript
pbjs.addAdUnits({
@@ -357,7 +363,7 @@ pbjs.addAdUnits({
#### Adpod (Long-Form)
-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]({{site.baseurl}}/prebid-video/video-long-form.html).
+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]({{site.baseurl}}/prebid-video/video-long-form.html).
```javascript
var longFormatAdUnit = {
@@ -391,57 +397,63 @@ var longFormatAdUnit = {
### Native
-For an example of a native ad unit, see below. For more detailed instructions, see [Show Native Ads]({{site.baseurl}}/dev-docs/show-native-ads.html).
+For an example of a native ad unit, see below. For more detailed instructions, see [Show Native Ads]({{site.baseurl}}/dev-docs/show-native-ads.html).
```javascript
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
- }
- }]
- }
- }
+ 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
- }
- }
- ]
+ },
+ bids: [
+ {
+ bidder: "appnexus",
+ params: {
+ placementId: 13232354,
+ },
+ },
+ ],
});
```
@@ -449,94 +461,97 @@ pbjs.addAdUnits({
### Multi-Format
-For an example of a multi-format ad unit, see below. For more detailed instructions, see [Show Multi-Format Ads]({{site.baseurl}}/dev-docs/show-multi-format-ads.html).
+For an example of a multi-format ad unit, see below. For more detailed instructions, see [Show Multi-Format Ads]({{site.baseurl}}/dev-docs/show-multi-format-ads.html).
```javascript
-
-pbjs.addAdUnits([{
- code: 'div-banner-native',
- mediaTypes: {
- banner: {
- sizes: [
- [300, 250]
- ]
- },
- native: {
+pbjs.addAdUnits([
+ {
+ code: "div-banner-native",
+ mediaTypes: {
+ banner: {
+ sizes: [[300, 250]],
+ },
+ native: {
ortb: {
- ver: "1.2",
- assets: [{
- required: 1,
- img: {
+ ver: "1.2",
+ assets: [
+ {
+ required: 1,
+ img: {
type: 1,
- hmin: 50
- }
- }]
- }
+ hmin: 50,
+ },
},
+ ],
},
- 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,
},
- 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: {
+ {
+ code: "div-banner-outstream-native",
+ mediaTypes: {
+ banner: {
+ sizes: [[300, 250]],
+ },
+ native: {
ortb: {
- ver: "1.2",
- assets: [{
- required: 1,
- img: {
+ ver: "1.2",
+ assets: [
+ {
+ required: 1,
+ img: {
type: 1,
- hmin: 50
- }
- }]
- }
- },
- video: {
- context: 'outstream',
- playerSize: [300, 250]
+ hmin: 50,
+ },
},
+ ],
},
- bids: [{
- bidder: 'appnexus',
- params: {
- placementId: 13232392,
- }
- }, ]
- }
+ },
+ video: {
+ context: "outstream",
+ playerSize: [300, 250],
+ },
+ },
+ bids: [
+ {
+ bidder: "appnexus",
+ params: {
+ placementId: 13232392,
+ },
+ },
+ ],
+ },
]);
-
```
@@ -605,23 +620,21 @@ Example of an adunit-specific block of first party data and a static floor:
```javascript
pbjs.addAdUnits({
- code: "test-div",
- mediaTypes: {
- banner: {
- sizes: [[300,250]]
- }
+ code: "test-div",
+ mediaTypes: {
+ banner: {
+ sizes: [[300, 250]],
},
- ortb2Imp: {
- bidfloor: 1.00,
- bidfloorcur: "EUR",
- ext: {
- data: {
- pbadslot: "homepage-top-rect",
- adUnitSpecificContextAttribute: "123"
- }
- }
+ },
+ ortb2Imp: {
+ ext: {
+ data: {
+ pbadslot: "homepage-top-rect",
+ adUnitSpecificContextAttribute: "123",
+ },
},
- // ...
+ },
+ // ...
});
```
@@ -638,16 +651,16 @@ Example of an adunit-specific interstitial signal:
```javascript
pbjs.addAdUnits({
- code: "test-div",
- mediaTypes: {
- banner: {
- sizes: [[300,250]]
- }
- },
- ortb2Imp: {
- instl:1
+ code: "test-div",
+ mediaTypes: {
+ banner: {
+ sizes: [[300, 250]],
},
- // ...
+ },
+ ortb2Imp: {
+ instl: 1,
+ },
+ // ...
});
```
@@ -661,60 +674,60 @@ When using [PBS stored impressions](/dev-docs/modules/prebidServer.html#stored-i
```javascript
pbjs.addAdUnits({
- code: "test-div",
- ortb2Imp: {
- ext: {
- prebid: {
- storedrequest: {
- id: 'stored-request-id'
- }
- }
- }
- }
-})
+ 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`:
```javascript
pbjs.addAdUnits({
- code: "test-div",
- bids: [
- {
- module: "pbsBidAdapter",
- params: {
- configName: "server-1"
+ code: "test-div",
+ bids: [
+ {
+ module: "pbsBidAdapter",
+ params: {
+ configName: "server-1",
+ },
+ ortb2Imp: {
+ ext: {
+ prebid: {
+ storedrequest: {
+ id: "stored-request-server-1",
},
- ortb2Imp: {
- ext: {
- prebid: {
- storedrequest: {
- id: 'stored-request-server-1'
- }
- }
- }
- }
+ },
},
- {
- module: "pbsBidAdapter",
- params: {
- configName: "server-2"
+ },
+ },
+ {
+ module: "pbsBidAdapter",
+ params: {
+ configName: "server-2",
+ },
+ ortb2Imp: {
+ ext: {
+ prebid: {
+ storedrequest: {
+ id: "stored-request-server-2",
},
- ortb2Imp: {
- ext: {
- prebid: {
- storedrequest: {
- id: 'stored-request-server-2'
- }
- }
- }
- }
+ },
},
- {
- bidder: 'client-bidder',
- // ...
- }
- ]
+ },
+ },
+ {
+ bidder: "client-bidder",
+ // ...
+ },
+ ],
});
```
diff --git a/dev-docs/renderer.md b/dev-docs/renderer.md
new file mode 100644
index 0000000000..879e624eea
--- /dev/null
+++ b/dev-docs/renderer.md
@@ -0,0 +1,203 @@
+---
+layout: page_v2
+title: Renderer
+description: Renderer Reference
+sidebarType: 1
+---
+
+# Renderer
+
+## What is a Renderer?
+
+A renderer provides publishers with precise control over how ads are displayed on their pages. It's especially valuable for video ads in non-video placements (such as outstream/in-renderer), but can be used with any media type.
+
+In simple terms, a renderer offers publishers:
+
+- The ability to customize how ads appear and behave
+- A way to introduce new ad formats without disrupting user experience
+- Control over maintaining design consistency between ads and site content
+
+## Renderer Object
+
+{: .table .table-bordered .table-striped }
+| Name | Scope | Type | Description |
+|--------------+----------+---------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `url` | Required | String | URL to the renderer script that will be loaded. This script should create a renderer object in the global scope. |
+| `render` | Required | Function | Function that tells Prebid.js how to invoke the renderer script to render a bid. The function receives the bid object as a parameter. |
+| `backupOnly` | Optional | Boolean | if set to true, buyer or adapter renderer will be preferred |
+
+## Renderer Implementation Levels
+
+Renderers can be specified at multiple levels:
+
+1. MediaType Level (adUnit.mediaTypes.video|banner|native.renderer): If a renderer is associated with a specific mediaType (video, banner, or native), it will be used to display any demand associated with that mediaType. This is the preferred method for all ad types.
+2. AdUnit Level (adUnit.renderer): Applied to all bids for this ad unit that don't override it. This is a legacy approach; using the mediaType-level renderer is preferred.
+3. Bidder Level (adUnit.bids[].renderer): Applied only to this bidder, overriding adUnit renderer if both exist.
+4. Default: If no renderer is specified at any level, Prebid will use the default renderer for the media type, if one exists. For banner and native ads, Prebid.js has built-in default rendering capabilities.
+
+### Priority Order
+
+When multiple renderers are defined, the following priority is used:
+
+1. MediaType Level renderer
+2. AdUnit Level renderer
+3. Bidder Level renderer
+4. Default renderer
+
+## Special Cases
+
+### Banner with Custom Renderer
+
+Although renderers are commonly associated with video ads, they can also be used with banner ads to create custom rendering experiences:
+
+```javascript
+pbjs.addAdUnits({
+ code: "custom-banner-container",
+ mediaTypes: {
+ banner: {
+ sizes: [[300, 250]],
+ renderer: {
+ url: "https://cdn.example.com/banner-renderer.js",
+ render: function (bid) {
+ // Create an enhanced banner experience
+ const bannerRenderer = new window.BannerRenderer({
+ adUnitCode: bid.adUnitCode,
+ adHtml: bid.ad,
+ width: bid.width,
+ height: bid.height,
+ // Add animation effects
+ effects: {
+ fadeIn: true,
+ duration: 300,
+ onViewable: true,
+ },
+ });
+ bannerRenderer.render();
+ },
+ },
+ },
+ },
+ bids: [
+ {
+ bidder: "appnexus",
+ params: {
+ placementId: 13144370,
+ },
+ },
+ ],
+});
+```
+
+A banner renderer might be used to:
+
+1. Add entrance/exit animations to standard banner ads
+2. Implement viewability-triggered rendering
+3. Create interactive enhancements to standard banner creatives
+4. Apply custom styling or containers to maintain site design aesthetics
+5. Implement fallback scenarios for different devices or browsers
+
+## Renderer Implementation Example
+
+```javascript
+// Example of a secure custom banner renderer implementation
+window.BannerRenderer = function (config) {
+ return {
+ render: function (bid) {
+ // Get the container element
+ const container = document.getElementById(config.adUnitCode);
+ if (!container) return;
+
+ // Create iframe to provide a secure environment
+ const iframe = document.createElement("iframe");
+ iframe.width = `${config.width}px`;
+ iframe.height = `${config.height}px`;
+ iframe.style.border = "none";
+ iframe.style.transition = `opacity ${config.effects.duration}ms ease-in-out`;
+ iframe.style.opacity = "0";
+ iframe.title = "Advertisement";
+ iframe.setAttribute("scrolling", "no");
+
+ // Add iframe to container
+ container.appendChild(iframe);
+
+ // Set iframe content
+ const iframeDoc = iframe.contentWindow.document;
+ iframeDoc.open();
+ iframeDoc.write(`
+
+
+
+
+
+
+
+
+ ${bid.ad || ""}
+
+
+ `);
+ iframeDoc.close();
+
+ if (config.effects.onViewable) {
+ // Set up IntersectionObserver for viewability-triggered effects
+ const observer = new IntersectionObserver(
+ (entries) => {
+ entries.forEach((entry) => {
+ if (entry.isIntersecting) {
+ // Apply fade-in when ad comes into view
+ iframe.style.opacity = "1";
+ observer.disconnect(); // Only need to trigger once
+ }
+ });
+ },
+ { threshold: 0.5 }
+ );
+
+ observer.observe(container);
+ } else {
+ // Immediate fade-in
+ setTimeout(() => {
+ iframe.style.opacity = "1";
+ }, 10);
+ }
+
+ // Cleanup function
+ return {
+ destroy: function () {
+ if (container && iframe) {
+ container.removeChild(iframe);
+ }
+ },
+ };
+ },
+ };
+};
+```
+
+## Common Renderer Properties
+
+Here are commonly used properties from the bid object that can be accessed in the renderer:
+
+{: .table .table-bordered .table-striped }
+| Property | Description |
+|--------------+------------------------------------------------------- |
+| `adId` | Unique identifier for the bid |
+| `adUnitCode` | The code for the ad unit |
+| `vastUrl` | URL to the VAST XML for video ads |
+| `vastXml` | The VAST XML content (if available instead of vastUrl) |
+| `width` | Width of the creative |
+| `height` | Height of the creative |
+| `playerWidth` | Width of the video player |
+| `playerHeight` | Height of the video player |
+| `mediaType` | Type of media ('video', 'banner', etc.) |
+| `cpm` | The bid's CPM |
+| `ad` | Ad markup |
+| `adUrl` | Ad markup url |