Video Ads

This guide outlines the integration requirements, configuration, and relevant OpenRTB protocol fields you may use when placing bids on video inventory. The Google RTB protocol is deprecated, and won't be a focus in this guide. For information about video ads in the Google RTB protocol, see the Video Ads in Google RTB guide.

Google supports in-stream, native, and interstitial video ads. See guides for Native and Interstitial ad formats for more details about those formats.

Buyer requirements

RTB Protocol

This guide will generally refer to the Protobuf format, but field names and paths are equivalent between it and the JSON format unless stated otherwise.

You can find the OpenRTB proto and Google-specific OpenRTB extensions in the Protos and reference data page. For more information about developing a bidder, see Process the Request and Build the Response.

Creative review

Google recommends that you submit creatives for approval before bidding with them. You can use the Real-time Bidding API's Creatives resource to start the review process.

Pretargeting configuration

In order to receive video inventory, your Authorized Buyers account should create a pretargeting configuration that includes video inventory.

Macros

You can specify macros in either the video URL link or VAST XML specified in BidResponse.seatbid.bid.adm. Additionally, if you specify a video URL, you may also place macros within the linked VAST XML document. The following macros are supported for video creatives:

  • %%CACHEBUSTER%%
  • %%WINNING_PRICE%%
  • %%SITE%%

Click macros such as CLICK_URL_ESC aren't supported because Authorized Buyers includes its click trackers in a VAST wrapper. For more information about supported macros, see Specify macros.

Callout details

You can use OpenRTB's BidRequest.imp.video field to identify whether an incoming bid request is for in-stream or intersitial video inventory and find additional video-specific information about the request. Additionally, for native ad inventory, you may use BidRequest.imp.native.{request/request_native}.assets.video for similar video-specific information.

BidRequest.{app/site}.content.producer.domain

The URL, with parameters removed, of the page that describes the video content. The publisher submits this URL to Google. For example:

http://www.publisher.com/watchpagelink
banner.vcm
If set to true, the companion ad can be picked to be rendered as an end cap (info card) in the video slot after the video ad finishes playing. Otherwise, the companion ad is not rendered as an end cap.
BidRequest.imp.rwdd
If set to true, it indicates the user receives a reward for viewing the video ad. Typical rewards might be reading an extra article for free, receiving an extra life in a game, or getting a sponsored ad-free music session.
BidRequest.imp.video.maxduration

The maximum allowed duration in seconds of the ad that you should return. When unset, there is no maximum duration. When BidRequest.imp.video.skip is true, this can behave differently. See Max skippable video duration for more details.

BidRequest.imp.video.maxseq

The maximum number of ads in the video pod. If unset, the ad slot isn't part of a video pod.

The actual number of video ads shown can be less than or equal to this value but cannot exceed it.

BidRequest.imp.video.minduration
The minimum duration in seconds of the ad that you should return. When unset, there is no minimum duration.
BidRequest.imp.video.plcmt
Describes where the video will play.
PLCMT_UNKNOWN Placement is unknown or undeterminable.
PLCMT_INSTREAM Pre-roll, mid-roll, and post-roll ads that are played before, during or after the streaming video content that the consumer has requested. Instream video must be set to "sound on" by default at player start, or have explicitly clear user intent to watch the video content. While there may be other content surrounding the player, the video content must be the focus of the user's visit. It should remain the primary content on the page and the only video player in-view capable of audio when playing. If the player converts to floating/sticky, subsequent ad calls should accurately convey the updated player size.
PLCMT_ACCOMPANYING_CONTENT Pre-roll, mid-roll, and post-roll ads that are played before, during, or after streaming video content. The video player loads and plays before, between, or after paragraphs of text or graphical content, and starts playing only when it enters the viewport. Accompanying content should only start playback upon entering the viewport. It may convert to a floating/sticky player as it scrolls off the page.
PLCMT_INTERSTITIAL Video ads that are played without video content. During playback, it must be the primary focus of the page and take up the majority of the viewport and cannot be scrolled out of view. This can be in placements like in-app video or slideshows.
PLCMT_NO_CONTENT_STANDALONE Video ads that are played without streaming video content. This can be in placements like slideshows, native feeds, in-content or sticky/floating.
BidRequest.imp.video.playbackmethod
Describes how to play the video ad. The playback method is determined to be auto-play or click-to-play based on the best measurement available.
AUTO_PLAY_SOUND_ON Initiates on page load with sound on.
AUTO_PLAY_SOUND_OFF Initiates on page load with sound off.
CLICK_TO_PLAY Initiates on click with sound on.
MOUSE_OVER Initiates on mouse-over with sound on.
ENTER_SOUND_ON Initiates on entering viewport with sound on.
ENTER_SOUND_OFF Initiates on entering viewport with sound off by default.
BidRequest.imp.video.skip
If true, it indicates that the player will allow the video to be skipped, or that skippable ads are allowed. Otherwise, it indicates that skippable ads are not allowed.
BidRequest.imp.video.startdelay

A value of 0 means pre-roll, -1 means mid-roll, and -2 means post-roll.

Any other positive value is the time in seconds from the start of the video to the point where the ad is displayed.

These signals are not unique to video creatives, but are particularly valuable for bidders to read:

BidRequest.device.ifa
This field is a 36-character UUID that is set only when using SSL, and is not hashed. It is the unencrypted version of BidRequest.device.dpidm5. For iOS devices, it contains the Identifier for Advertisers (IDFA) in all uppercase characters. For Android devices, it contains the Android identifier (ADID) in all lowercase characters. For Connected TV devices, it contains their uniques identifiers (for example, Roku's RIDA).
BidRequest.device.devicetype
Specifies the type of device.
MOBILE An obsolete alias for HIGHEND_PHONE or TABLET.
PERSONAL_COMPUTER Includes desktop and laptop devices.
CONNECTED_TV includes both connected TVs (that is, smart TVs) and connected devices (such as Roku, Apple TV, and so on).
HIGHEND_PHONE Includes highend phone devices.
TABLET Includes tablet devices.
CONNECTED_DEVICE Includes dedicated gaming devices.
SET_TOP_BOX Includes set top box devices.
OOH_DEVICE Includes out-of-home advertising devices; for example, digital billboards.
BidRequest.device.make
Specifies the brand (such as Nokia or Samsung) of the device.
BidRequest.device.model
Specifies the exact model (such as N70 or Galaxy) of the device if available, otherwise contains a generic model such as "iphone" or "ipad".
BidRequest.imp.metric
When Metric.type is set to completion_rate, Metric.value will be a fraction in the range [0.0, 1.0] representing the historical completion rate for video ads served in the ad slot. The default value of -1.0 indicates that historical completion rate data isn't available.
BidRequest.imp.video.poddur
The length of time in seconds of the entire ad break, including all slots that the pod consists of. This is set to the value specified in the video metadata provided by the video publisher.

The video bid request also contains information about the inventory such as the vertical, allowed vendors, and channel information. All other existing fields in the bid request also apply to video.

The width and height fields in the AdSlot message of a video request correspond to the size of the video ad player.

BidRequest.imp.ext.allowed_vendor_type
The allowed vendors. See the vendors.txt file in the technical documentation for a list of IDs. For example, 309 = DFA Video Unit.
BidRequest.imp.video.mimes
An allowlist describing the supported content MIME types for ads served in response to the bid request; for example, "video/mp4". The bid response should indicate support for at least one of them.
BidRequest.imp.video.protocols
Describes a publisher's supported VAST versions for video ad requests. Contains an array of Protocol enum values, including: VAST_2_0, VAST_3_0, VAST_2_0_WRAPPER, VAST_3_0_WRAPPER, VAST_4_0, VAST_4_0_WRAPPER, and more.
BidRequest.imp.video.companionad
This field includes an array of Banner objects representing companion ads if they are available.
BidRequest.site.page

The URL of the video watch page or the URL of the page into which the video has been embedded. For example:

http://www.publisher.com/watchpagelink

When responding to a video request, the bidder should return a VAST redirect URL, or VAST XML in the BidResponse.seatbid.bid.adm field. The bid response should also contain the proper declaration for the video ad. The following is an extract of a proper video bid response: 

id: "cRPF1960K8WH788KM8ZT5k"
seatbid {
  bid {
    id: "99862J52T2r9f8n6hzY"
    impid: "1"
    price: 0.2873480215418293
    adid: "test_creative_id_958969"
    adm: "https://video.test.com/ads?id=123456&wprice=%%WINNING_PRICE%%"
    adomain: "google.com"
    cid: "80831705186"
    crid: "test_creative_id_958969"
    w: 480
    h: 854
  }
  seat: "5731:4728:218110"
}
bidid: "dR2wx766-444e907U-Xpv0-634m58Wa5V73"
cur: "USD"

The important fields in a video bid response are the following:

BidResponse.seatbid.bid.ext.attribute
Attributes for the ads that may be shown from this snippet. See the buyer-declarable-creative-attributes.txt file for the list of IDs. We check to ensure that none of these attributes match those disallowed by the publisher in the bid request. For example, setting if either field included 30, that would indicate the ad requires VPAID support to render.
BidResponse.seatbid.bid.adm

For video ads, this is the VAST redirect URL of the video ad. For example:

http://ad.doubleclick.net/pfadx/N270.132652.1516607168321/B3442378.3;dcadv=1379578;sz=0x0;ord=79879;dcmt=text/xml

Alternatively, this may be raw VAST XML.

Example bid requests and responses

Video Formats

How buyers can include video

The following tables illustrate ways in which buyers can include video in their creatives and placements they can be served into for web and mobile app respectively.

Web

Video creative Instream (all) In-feed/article Native in-feed/article Interstitial In-banner

VPAID + VAST

 

VAST

 

MRAID + JS

 

 

 

 

 

Custom JS

 

Native + VAST

 

Mobile App

Video creative Instream (all) In-feed/article Native in-feed/article Interstitial In-banner

VPAID + VAST

 

 

 

 

 

VAST

MRAID + JS

Custom JS

Native + VAST

Key: Format/technology not available

Video creative accepted in this placement, subject to publisher blocks

Video creative not available on this placement

OpenRTB recommended signals

The following tables illustrate OpenRTB recommended signals for all video formats for desktop & mobile web, and mobile app.

Desktop and mobile web

Video format Recommended signals (video relevant signals only) Related signals (video relevant signals only)

Instream (VPAID)

VIDEO object present   &
video.placement = INSTREAM   &

Instream (no VPAID)

VIDEO object present   &
video.placement = INSTREAM    &
video.api = 1 VPAID 1.0 or 2:VPAID 2.0

Non-instream

VIDEO object present

video.linearity: linear
placement depends on actual
placement, values as below
Video.startdelay = 0

In-feed

VIDEO object present   &
video.placement = IN-FEED

In-article

VIDEO object present   &
video.placement = IN-ARTICLE

Native

NATIVE object present &

In-banner

Video object not present &
banner.battr ≠ 6 In-Banner Video (Auto-Play) &
banner.battr ≠ 7 In-Banner Video (User Initiated)

Mobile app

Video format Bid request details (only the video relevant details)

Instream

VIDEO object present   &
video.placement = INSTREAM    &

video.api = 1 VPAID 1.0 or 2: VPAID 2.0

Non-instream

VIDEO object present

video.linearity: linear
placement depends on actual
placement, values as below
Video.startdelay = 0

In-feed

VIDEO object present   &
video.placement = IN-FEED

In-article

VIDEO object present   &
video.placement = IN-ARTICLE

Native

NATIVE object present &

Interstitial (VAST)

VIDEO object present   &
video.placement = INTERSTITIAL

Interstitial (no VAST)

VIDEO object present   &
video.placement = INTERSTITIAL

Filtered

In-banner (MRAID)

Video object not present &
banner.battr ≠ 6 In-Banner Video (Auto-Play) &
banner.battr ≠ 7 In-Banner Video (User-Initiated)

In-banner

(no MRAID)

Video object not present &
banner.battr ≠ 6 In-Banner Video (Auto-Play) &
banner.battr ≠ 7 In-Banner Video (User-Initiated)

How publishers can allow/disallow video

The following table illustrate ways in which publishers can allow/disallow video in their placements.

Pub option Applicable formats Described in bid request as

Specify Instream video an unit

Instream (all)

Video object present &
video.placement = INSTREAM

Opt into VPAID

Instream web

Video object present &
video.api = 1 (VPAID 1.0) or 2 (VPAID 2.0)

Opt into IBV

In-banner

Interstitial

banner.battr ≠ 6 In-Banner Video (Auto-Play) &/or 7 In-Banner Video (User-Initiated)

Opt in to (instructions)

In-feed

In-article

Video object present &
video.placement = IN-FEED or IN-ARTICLE

Opt in to Non-instream (instructions)

Native

Native object present

Block Video interstitial

Interstitial app

VIDEO object not present

Edge cases

# Case Description Comments Bid request

1

Delayed custom close using MRAID

For interstitials, closing the ad can send a notification to the Buyer using MRAID, even if they didn't use custom close.


The Authorized Buyers applied X will always appear on top of any custom close, even if the custom close appears underneath after 5 seconds

Glossary

See Authorized Buyers video glossary.

Relevant fields for Instream and Non-Instream formats

See OpenRTB 2.5 (starting from page 47)

BidRequest.Video.
Placement
Instream mWeb

1: In-Stream
2: In-Banner

mApp

1: In-Stream
2: In-Banner
Non-instream mApp Interstitial

5: Interstitial

Native

3: In-Article
4: In-Feed

Rewarded

is_rewarded_inventory: OpenRTB Extension bool
linearity

Indicates if the impression must be linear, nonlinear, etc. If none are specified, assume that all are allowed.

Instream mWeb

1: LINEAR (In-stream)

mApp

1: LINEAR (In-stream)
Non-instream mApp Interstitial

2: INTERSTITIAL

Native

3: IN_FEED
5: IN_ARTICLE
videoad_start_delay
Instream mWeb

>0: start delay in seconds
 0: PRE_ROLL
-1: GENERIC_MID_ROLL
-2: GENERIC_POST_ROLL

mApp

>0: start delay in seconds
 0: PRE_ROLL
-1: GENERIC_MID_ROLL
-2: GENERIC_POST_ROLL
Non-instream Rewarded

>0: start delay in seconds
 0: PRE_ROLL
-1: GENERIC_MID_ROLL
-2: GENERIC_POST_ROLL

Bid request value source

OpenRTB
Object		 Fields Authorized Buyers
/Exchange
Bidding
Non-instream		 Sample Values Who determines it?
/Where this value derives
from?
Object
Video mimes yes ["application/javascript",
"video/mp4"]",		 Google
minduration no Publisher Configured
maxduration yes Publisher Configured
playbackmet
hod		 yes [6] Usually Publisher
Configured
api (MRAID) yes [1,2] Google
protocols yes [2,3,5,6,7,8] Google
linearity yes [1] Google
placement yes [1] Google
player width yes 400,400,300 Google
player height yes 225,300,153 Google
start delay yes 0 Google, default 5 sec
skip yes 1 Publisher/Google
- for Interstitial => Google
- for Instream => Publisher
decides whether to allow
skippable, non-skippable, or both.
Reward ads, always non skip;
min bitrate No Google
max bitrate no Google
pos yes 1 Google
Device
Px ratio yes 1 Google
impression
Secure yes 1 Google
default to true
because adtag is always
secure