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
- An app implementing DAI API calls for VOD streams. See the DAI API VOD stream guide for more information.
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.
|
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.