Video Ads

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

Ad Exchange 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 Ad Exchange 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 Ad Exchange 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 smartphones 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] and rounded down to the next multiple of 10. The default value -1 indicates that historical viewability data is not available.

The video bid request also contains information about the inventory such as the vertical, allowed vendors, and channel information. The table below outlines a few particularly useful fields for parsing video requests. All other existing fields in the bid request (for example, detected_vertical) also apply to video.

The following table lists the attributes of a video declared in the ContentAttributes message. They are set to the values specified in the video metadata provided by the video publisher.

title The title of the video. For example, "Packers vs. Steelers."
duration_seconds How many seconds (for example, 200) the video plays.
keywords A list of at most 10 keywords describing the video. They are extracted from the video publishers' content management system. For example, the following: Packers, Steelers, ABC, ABC news.

Additionally, 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.
detected_content_labels
Content labels for video inventory indicate what audiences are appropriate (all, aged 14+, or mature only) or that the video content has not yet been rated. There may also be one or more regular content labels. See the content-labels.txt file for the list of content labels. For example, 39 = Video Content Rating DV-G.
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 Flash 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 campaign for RTB that includes video inventory.

Example bid requests and responses

Send feedback about...

Real-Time Bidding Protocol
Real-Time Bidding Protocol