Video Ads in Google RTB protocol

With the launch of video ad support, buyers can purchase video inventory through Authorized Buyers. This document outlines the integration requirements for buying through RTB using the Authorized Buyers protocol. For information about the available protocols see the Select a protocol section of the Get Started guide.

Buyers can purchase video inventory across placements, currently in-stream and interstitial. See Interstitial Ads for details.

Buyer requirements

New RTB buyers should develop their bidders using the latest protocol buffer and the information outlined in the following sections. To download the protocol, see the real-time bidding reference data page. For information on developing a bidder, see Process the Request and Build the Response.

Supported macros

The following macros are supported on in-stream video creatives:

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

Click macros (such as CLICK_URL_ESC) are not necessary because Authorized Buyers includes its click trackers in a VAST wrapper. Therefore, click macros are not supported for in-stream video ads. For more information about supported macros, see Specify macros under Build the Response.

Callout details

The real-time bidding protocol uses a video message, defined in the real-time-bidding-proto.txt file to identify video requests and to provide additional video-specific information about the request.

The following list of fields in the nested video message also provides detailed descriptions and examples:

description_url

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

EndCapSupport

When enabled, 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.

END_CAP_NOT_ENABLED	Companion ad is not rendered as end cap.
END_CAP_OPTIONAL	End cap is rendered if the response contains an eligible companion banner, but the companion banner is not required.
END_CAP_FORBIDDEN	A response with a companion ad is filtered.
END_CAP_REQUIRED	A response without a companion ad is filtered.

is_embedded_offsite

If this is set to true, the video is embedded on pages outside the publisher's domain.

is_rewarded

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.

max_ad_duration

The maximum allowed duration for the returned ad in milliseconds. When set to 0, there is no maximum duration.

max_ads_in_pod

The maximum number of ads in an Authorized Buyers video pod. A non-zero value indicates that the current ad slot is a video pod that can show multiple video ads. The actual number of video ads shown can be less than or equal to this value but cannot exceed it.

min_ad_duration

The minimum duration in milliseconds of the ad that you should return. If this is not set or has a value less than or equal to zero, there is no minimum duration.

Placement

Describes where the video will play.

UNKNOWN_PLACEMENT	Placement is unknown or undeterminable.
INSTREAM	Instream means the ad plays before, during, or after other video content. This is similar to a traditional TV commercial. The video content the user is watching does not play while the ad is playing.
INTERSTITIAL	Interstitial means the video ad plays in front of non-video content (for example, a news article or video game). The ad covers all or nearly all of the space on the screen occupied by the content and the user is not able to proceed to the content until the ad has finished or been skipped.
IN_FEED	The in-feed video format is a video creative that shows when the user is scrolling through a feed of content, typically a social app feed, a news article, etc. The video renders in the main feed and in the user’s vision and reading flow. The video does not render to the side like in-banner video.

skippable_max_ad_duration

The maximum duration in milliseconds for the ad that you should return if this ad is skippable. This generally differs from maximum duration allowed for non-skippable ads. If this field is not set or has a value less than or equal to zero, any duration is allowed.

VideoPlaybackMethod

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	means the ad plays automatically with the sound on.
AUTO_PLAY_SOUND_OFF	means the ad plays automatically with the sound off.
CLICK_TO_PLAY	means the ad doesn't play until it is clicked on.

video_ad_skippable

This is a value of SkippableBidRequestType that contains one of the following values:

ALLOW_SKIPPABLE	means both skippable and non-skippable ads are allowed.
REQUIRE_SKIPPABLE	means only skippable ads may be returned.
BLOCK_SKIPPABLE	means only non-skippable ads may be returned.

The default if this field is not set is to allow skippable ads.

videoad_start_delay

The time in milliseconds from the start of the video to the point where the ad is displayed. 0 means pre-roll and -1 means post-roll. Any other positive values indicate the slot is in the middle of the video.

The value is valid only if this parameter is set. When not set, the display position is unknown.

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

advertising_id

This field is a 16-byte UUID that is set only when using SSL. It is the unencrypted version of encrypted_advertising_id. For iOS devices, it contains the Identifier for Advertisers (IDFA). For Android devices, it contains the Android identifier (ADID). For Connected TV devices, it contains their uniques identifiers (for example, Roku's RIDA).

device_type

Specifies the type of device.

UNKNOWN_DEVICE	is the default value for this field.
HIGHEND_PHONE	includes mobile phones with video capabilities.
TABLET	includes tablet devices.
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).
GAME_CONSOLE	includes dedicated gaming devices.

brand

Specifies the brand (such as Nokia or Samsung) of the device. This field is optional; by default it is not specified.

model

Specifies the exact model (such as N70 or Galaxy) of the device. This field is optional; by default it is not specified.

screen_orientation

Specifies the orientation of the device when the ad request is sent. Valid values are LANDSCAPE, PORTRAIT, and UNKNOWN_ORIENTATION.

viewability

Provides an estimate of the likelihood that this slot will be viewable by the end user based on how often it has been viewable in the past. Expressed as a percentage in the range of [0, 100]. The default value -1 indicates that historical viewability data is not available.

content_attributes.duration_seconds

How many seconds (for example, 200) the video plays. This is declared in the ContentAttributes message. 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.

allowed_vendor_type

The allowed vendor. See the vendors.txt file in the technical documentation for a list of IDs. For example, 309 = DFA Video Unit.

allowed_video_formats

Describes the allowed video technologies for ads served in response to this request. The response should indicate support for at least one of them. The values for this repeated field come from the enumeration VideoFormat:

VIDEO_FLASH	Allows videos using the Flash Video (FLV) format.
VIDEO_HTML5	Allows videos using the HTML5 video format.
VPAID_FLASH	Allows videos using the Video Player Ad-Serving Interface Definition (VPAID) Flash video format.
VPAID_JS	Allows videos using the VPAID JavaScript video format.

companion_slot

This field represents a CompanionSlot message that includes the following fields:

height	The available heights for this slot.
width	The available widths for this slot.
CreativeFormat	The creative format represents the possible formats for the creative in this companion slot.

url

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 in the video_url field. The bid response should also contain the proper declaration for the video ad. Below is an extract of a proper video bid response:

protocol_version: 1
  ad {
    adslot {
      id: 1
      max_cpm_micros: 50000000
    }
    click_through_url: "http://google.com/"
    video_url: "http://ad.doubleclick.net/pfadx/N270.132652.1516607168321/
    B3442378.3;dcadv=1379578;sz=0x0;ord=79879;dcmt=text/xml"
  }

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

attribute

All 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 are in the excluded_attribute list of the Bid Request. Only set this field if an HTML snippet or video ad is returned. For example, setting this field to 30 indicates the ad requires VPAID support to render.

protocol

Describes a publisher's supported VAST versions for video ad requests, allowing VAST ads up to and including the given version. Contains an array of supported video ad protocols. This corresponds to and matches the behavior in OpenRTB 2.4. The following values are possible: VAST_2_0, VAST_3_0, VAST_2_0_WRAPPER, VAST_3_0_WRAPPER, VAST_4_0, and VAST_4_0_WRAPPER.

video_url

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

Pretargeting

In order to receive video inventory, RTB buyers must have a pretargeting configuration for RTB that includes video inventory.

Example bid requests and responses

• Sample video bid requests
• Sample video bid responses

AdX Video Formats

• How buyers can include video
• OpenRTB recommended signals for all video formats
• Authorized Buyers proto recommended signals for all video formats
• How publishers can allow/disallow video
• Edge cases

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
Outstream	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
Outstream	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)

AdX proto recommended signals

The following tables illustrate Authorized Buyers proto recommended signals for all video formats for desktop and mobile web, and mobile app.

Desktop and Mobile web

Video format	Recommended video-relevant signals	Related video-relevant signals
Instream (VPAID)	VIDEO message present   & placement = INSTREAM    & Allowed_video_formats = VPAID_JS	Allowed_video_formats = VIDEO_HTML5 Allowed_ad_types = VIDEO
Instream (no VPAID)	VIDEO message present   & placement = INSTREAM    & Allowed_video_formats ≠ VPAID_JS	Allowed_video_formats = VIDEO_HTML5   & excluded_attribute = 30 InstreamVastVideoType: Vpaid Allowed_ad_types = VIDEO
In-feed	VIDEO message present   & placement = IN-FEED	Allowed_video_formats = VIDEO_HTML5   & excluded_attribute = 30 InstreamVastVideoType: Vpaid Allowed_ad_types = VIDEO
In-article	VIDEO message present   & placement = IN-ARTICLE	Allowed_video_formats = VIDEO_HTML5   & excluded_attribute = 30 InstreamVastVideoType: Vpaid Allowed_ad_types = VIDEO
Native	NATIVE message present   & VIDEO = 000x000 within native message	Allowed_ad_types = NATIVE
In-banner	excluded_attribute ≠ 95 VideoType: In-Banner Video (Publisher Blockable)	Allowed_ad_types = BANNER

Mobile app

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

Video format	Video-relevant bid request details	Video-relevant related signals
Instream	VIDEO message present placement = INSTREAM	Allowed_video_formats = VIDEO_HTML5 excluded_attribute = 30 InstreamVastVideoType: Vpaid Allowed_ad_types = VIDEO
In-feed	VIDEO message present   & placement = IN-FEED	Allowed_video_formats = VIDEO_HTML5   & excluded_attribute = 30 InstreamVastVideoType: Vpaid Allowed_ad_types = VIDEO
In-article	VIDEO message present   &placement = IN-ARTICLE	Allowed_video_formats = VIDEO_HTML5   & excluded_attribute = 30 InstreamVastVideoType: Vpaid Allowed_ad_types = VIDEO
Native	NATIVE message present   & VIDEO = 000x000 within native message	Allowed_ad_types = NATIVE
Interstitial	VIDEO message present   & placement = INTERSTITIAL   &	Allowed_video_formats = VIDEO_HTML5   & excluded_attribute = 30 InstreamVastVideoType: Vpaid Allowed_ad_types = VIDEO
In-banner (MRAID)	excluded_attribute ≠ 95 VideoType: In-Banner Video (Publisher Blockable)  & excluded_attribute ≠ 32 MraidType: MRAID	Allowed_video_formats = VIDEO_HTML5   & excluded_attribute = 30 InstreamVastVideoType: Vpaid Allowed_ad_types = BANNER
In-banner (no MRAID)	excluded_attribute ≠ 95 VideoType: In-Banner Video (Publisher Blockable)  & excluded_attribute = 32 MraidType: MRAID	Allowed_video_formats = VIDEO_HTML5   & excluded_attribute = 30 InstreamVastVideoType: Vpaid Allowed_ad_types = BANNER

How publishers can allow/disallow video

The following tables illustrate ways in which publishers can allow/disallow video in their placements and how it manifests in the bid request for OpenRTB, and AdX Proto.

OpenRTB

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 Outstream (instructions)	In-feed In-article	Video object present & video.placement = IN-FEED or IN-ARTICLE
Opt in to Outstream (instructions)	Native	Native object present
Block Video interstitial	Interstitial app	VIDEO object not present

AdX Proto

Pub option	Applicable formats	Described in bid request as (NOTE: these are ALL indicators of the pub option in the bid request - for recommended signals see table below)	Default setting
Specify Instream video an unit	Instream (all)	Video message present & placement = INSTREAM	n/a
Opt into VPAID	Instream web	Video message present & Allowed_video_formats = VPAID_JS & excluded_attribute ≠ 30 InstreamVastVideoType: Vpaid	Opted out
Opt into IBV	In-banner Interstitial	excluded_attribute ≠ 95 VideoType: In-Banner Video (Publisher Blockable)	Opted out
Opt into Outstream (instructions)	In-feed In-article	Video message present & Allowed_video_formats = VIDEO_HTML5 & placement = IN-FEED or IN-ARTICLE	Opted out
Opt into Outstream (instructions)	Native	NATIVE message present & VIDEO = 000x000 within native message	Opted out
Block Video interstitial	Interstitial app	VIDEO message not present & excluded_attribute = 30 InstreamVastVideoType: Vpaid	Opted in

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

AdX and OpenRTB fields in Instream and Outstream formats

AdX Proto

BidRequest.Video.
Placement	Instream mWeb 0: UNKNOWN_PLACEMENT 1: INSTREAM mApp 0: UNKNOWN_PLACEMENT 1: INSTREAM Outstream mApp Interstitial 2: INTERSTITIAL Native 3: IN_FEED 5: IN_ARTICLE Rewarded is_rewarded
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 Outstream Rewarded >0: start delay in seconds  0: PRE_ROLL -1: GENERIC_MID_ROLL -2: GENERIC_POST_ROLL

OpenRTB Proto

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 Outstream 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) Outstream 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 Outstream Rewarded >0: start delay in seconds  0: PRE_ROLL -1: GENERIC_MID_ROLL -2: GENERIC_POST_ROLL

Bid request value source

OpenRTB Object	Fields	AdX /Exchange Bidding Outstream	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