VOD stream skippable ads

This guide demonstrates how to use the DAI API to request a VOD stream with skippable ads, render the skip button according to Google Ads requirements, and send the associated tracking events.

Prerequisites

Make a request for skippable ads

To request a VOD stream with skippable ads, you must pass the dai-sas parameter in your stream request.

API endpoint

POST: /ondemand/v1/hls/content/{CMS_ID}/vid/{VIDEO_ID}/stream
Host: dai.google.com
Content-Type: application/x-www-form-urlencoded

Path parameters

{CMS_ID} The stream's CMS ID.
{VIDEO_ID} The stream's video ID.

Body parameters

dai-sas Set dai-sas=1 to enable skippable ads.

Example request (cURL)

For HLS stream requests:

curl -X POST \
     -d 'dai-sas=1' \
     -H 'Content-Type: application/x-www-form-urlencoded' \
https://dai.google.com/ondemand/v1/hls/content/{CMS_ID}/vid/{VIDEO_ID}/stream

Substitute 'dash' in the URL for DASH streams:

https://dai.google.com/ondemand/v1/dash/content/{CMS_ID}/vid/{VIDEO_ID}/stream

Use the following format to include multiple stream parameters in your request's body:

-d 'dai-sas=1&cust_params=key1%3dvalue1%26key2%3dvalue2' \

Handle skipping ads

To handle skipping ads, use the information in either the Ad struct or AdBreak struct depending on if you are skipping the current ad or the whole ad break. Take the start value and add the duration value, then seek to that point in the stream. The SkipMetadata submessage also includes the offset value, which is a value in seconds of the time before the ad can be skipped. The SkipMetadata submessage will only be included on ads that are skippable.

ad_breaks A list of Ad Breaks.
start (number) Position in the stream that the break starts, in seconds.
duration (number) Duration of the ad break, in seconds.
ads (object(Ad)) A list of Ads in the stream.
start (number) Position in the stream that the ad starts, in seconds.
duration (number) Duration of the ad, in seconds.
skip_metadata (object(SkipMetadata)) Optional metadata for skippable ads. If set, this indicates the ad is skippable and includes instructions for how to handle the skip UI and tracking event.
offset (number) Offset indicates the amount of time in seconds into the ad the player should wait to render the skip button. Omitted if not provided in the VAST.
tracking_url (string) A URL that should be pinged on the skip event.

Example response

{
  ...
  "ad_breaks":[
    {
      ...
      "start":0,
      "duration":10,
      "ads":[
        {
          ...
          "start":0,
          "duration":10,
          "skip_metadata":{
            "offset": 5,
            "tracking_url": "https://example_skip_url.com"
          }
        }
    }
}

Once the ad is skipped, ping the skip event URL included in the stream response. It is included in the SkipMetadata submessage.

Skip button requirements

For skippable ads, render the skip button with the following design requirements. Failure to follow these requirements may lead to restrictions being placed on Google ads being served to your site or app.

Countdown timer

The ad must not be skippable until the skipoffset time specified in the VAST. During this unskippable period, you must display a notice to the user informing them that the ad can be skipped in X seconds. The notice must be translated into the user's language.

Skip button position

For a left-to-right language, place the skip button on the bottom right side of the video player. For a right-to-left language, place the skip button on the bottom left side of the video player.

Skip button size

The button and text must be large enough to be clearly legible in a lean-back experience.

Text and icon

The skip button must have both text and iconography. You can use the skip next material icon as your iconography.

Accessibility

The user should be able to navigate to the skip button using a keyboard or remote control. The app should focus the skip button once the countdown is complete.

Internationalization

It is recommended to translate the skip text into the user's language.

Ad pods

The skip button can be used to skip either the current ad in the ad pod, or skip the entire pod.

'Skip ad' translations

Use the skipAdTranslations.json file for translating your 'Skip ad' text based on the user's locale.