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

Back to Publisher API Reference