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 Unique 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.
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.
fpd Optional Object Similar to global first party data configuration, but specific to this adunit.

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.

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.

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]].
name Optional String Name for this banner ad unit. Can be used for testing and debugging.

adUnit.mediaTypes.native

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

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

adUnit.mediaTypes.native.image
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.

adUnit.mediaTypes.native.image.aspect_ratios
Name Scope Type Description
min_height Optional Integer The minimum height required for an image to serve (in pixels).
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.

adUnit.mediaTypes.native.title
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.

adUnit.mediaTypes.native.sponsoredBy
Name Scope Type Description
required Optional Boolean Whether a brand name asset is required on this native ad.

adUnit.mediaTypes.native.clickUrl
Name Scope Type Description
required Optional Boolean Whether a click URL asset is required on this native ad.

adUnit.mediaTypes.native.body
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.

adUnit.mediaTypes.native.icon
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.

adUnit.mediaTypes.native.icon.aspect_ratios
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.

adUnit.mediaTypes.video

Name Scope Type Description
context Optional String The video context, either 'instream', 'outstream', or 'adpod' (for long-form videos). 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.

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'

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

Instream

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

Outstream

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: 'https://cdn.adnxs.com/renderer/video/ANOutstreamVideo.js',
        render: function(bid) {
            ANOutstreamVideo.renderAd({
                targetId: bid.adUnitCode,
                adResponse: bid.adResponse,
            });
        }
    },
    ...
});

Adpod (Long-Form)

For an example of an adpod video ad unit, 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: {
            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
            }
        }
    ]
});

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

First Party Data

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

pbjs.addAdUnits({
    code: "test-div",
    mediaTypes: {
        banner: {
            sizes: [[300,250]]
        }
    },
    fpd: {
         context: {
            pbAdSlot: "homepage-top-rect",
            adUnitSpecificContextAttribute: "123"
         }
    },
    ...
});

Notes:

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

All demos, instructions, documentation and code included on the Prebid.org website are released
under the Apache License. | Credits