Ad Unit Reference

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 media types (e.g., banner, native, and/or video)
  • Allowed sizes
  • AdUnit-specific first party data

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.

AdUnit

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.
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 and onBidBillable 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 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.

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 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.

adUnit.mediaTypes.banner

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.

adUnit.mediaTypes.native

The native object contains properties that correspond to the assets of the native ad.

See Prebid Native Implementation for details.

adUnit.mediaTypes.video

Name Scope Type Description
pos Optional Integer Ad position on screen, see OpenRTB 2.5 spec. 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
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.
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'

adUnit.video

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.

Examples

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
            }
        }
    ]
});

Video

With the Video Module

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
        }
    }]
});

Instream Sound-On

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',
            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
        }
    }]
});

Player contains video content with sound off

The IAB calls this scenario “Accompanying Content”. Previously, this might have been called “instream with sound-off”, but as of April 2023, the IAB has reclassified this scenario.

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
        },
    },
    bids: [{
        bidder: 'appnexus',
        params: {
            placementId: 13232361
        }
    }]
});

Standalone ad wit no video content

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.

pbjs.addAdUnits({
    code: slot.code,
    mediaTypes: {
        video: {
            context: 'outstream',
            plcmt: 4,
            playerSize: [640, 480],
            mimes: ['video/mp4'],
            protocols: [1, 2, 3, 4, 5, 6, 7, 8],
            playbackmethod: [6],
        }
    },
    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',
            plcmt: 4,
            playerSize: [640, 480],
            mimes: ['video/mp4'],
            protocols: [1, 2, 3, 4, 5, 6, 7, 8],
            playbackmethod: [6],
            useCacheKey: true,
        }
    },
    renderer: {
        url: 'https://example.com/myVastVideoPlayer.js',
        render: function(bid) {
            let vastUrl = bid.vastUrl;
            myVastVideoPlayer.setSrc({
                src: vastUrl,
                ...
            });
        }
    },
    ...
});

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.

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',
            }
        }]
}

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: {
            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
            }
        }
    ]
});

Multi-Format

For an example of a multi-format ad unit, see below. For more detailed instructions, see Show Multi-Format Ads.


pbjs.addAdUnits([{
        code: 'div-banner-native',
        mediaTypes: {
            banner: {
                sizes: [
                    [300, 250]
                ]
            },
            native: {
        ortb: {
            ver: "1.2",
            assets: [{
            required: 1,
                    img: {
                type: 1,
                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,
            }
        }, ]
    },

    {
        code: 'div-banner-outstream-native',
        mediaTypes: {
            banner: {
                sizes: [
                    [300, 250]
                ]
            },
            native: {
        ortb: {
            ver: "1.2",
            assets: [{
            required: 1,
                    img: {
                type: 1,
                hmin: 50
            }
            }]
        }
            },
            video: {
                context: 'outstream',
                playerSize: [300, 250]
            },
        },
        bids: [{
            bidder: 'appnexus',
            params: {
                placementId: 13232392,
            }
        }, ]
    }
]);

Twin AdUnit Codes

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.

  • BidderA should receive both media types, while BidderB gets only one
  • BidderA gets one size while BidderB gets another

In this example, bidderA gets both banner and outstream, while bidderB gets only banner.

var adUnits = [
        {
            code: 'test-div',
            mediaTypes: {
                video: {
                    context: "outstream",
                    playerSize: [[300,250]]
                }
            },
            bids: [
                {
                    bidder: 'bidderA',
                    params: {
                            ...
                    }
                }
            ]
        },
        {
            code: 'test-div',
            mediaTypes: {
                banner: {
                    sizes: [[300,250],[300,600],[728,90]]
                }
            },
            bids: [
                {
                    bidder: 'bidderB',
                    params: {
                        ...
                    }
                },{
                    bidder: 'bidderA',
                    params: {
                        ...
                    }
                }
            ]
        }
    ];

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.

First Party Data

Example of an adunit-specific block of first party data:

pbjs.addAdUnits({
    code: "test-div",
    mediaTypes: {
        banner: {
            sizes: [[300,250]]
        }
    },
    ortb2Imp: {
        ext: {
            data: {
                    pbadslot: "homepage-top-rect",
                    adUnitSpecificContextAttribute: "123"
            }
        }
    },
    // ...
});

Notes:

  • Only contextual data should be added on the AdUnit; user-related data goes in the global first party data config.
  • For additional help with analytics and reporting you can use the Prebid Ad Slot, a special type of first party data.

Interstitial Ads

Example of an adunit-specific interstitial signal:

pbjs.addAdUnits({
    code: "test-div",
    mediaTypes: {
        banner: {
            sizes: [[300,250]]
        }
    },
    ortb2Imp: {
        instl:1
    },
    // ...
});

For more information on Interstitial ads, reference the Interstitial feature page. Additionally, to assist with billing optimization and interstitial ads, the triggerBilling and onBidBillable functionality can be utilized. See pbjs.triggerBilling and onBidBillable for more info.

Prebid Server stored impressions

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',
            // ...
        }
    ]
});