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

• Sample video bid requests
• Sample video bid responses

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

Mobile App

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

Mobile app

How publishers can allow/disallow video

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

Edge cases

Glossary

See Authorized Buyers video glossary.

Relevant fields for Instream and Non-Instream formats

See OpenRTB 2.5 (starting from page 47)

Bid request value source