The DAI API is in Beta and might not be available in your network. Contact your account manager for more information. The IMA SDK is recommended for platforms where it is available.

Manage DAI livestreams

Page Summary

The Google DAI API is designed for environments where the IMA SDK is not supported, such as certain smart TVs and consoles.
The API supports LIVE streams using both HLS and DASH protocols and requires requesting a stream, polling for AdBreak metadata, listening to ID3 events for playback tracking, and optionally updating session parameters.
To request a stream, a POST call is made to the stream endpoint, and the JSON response provides the stream manifest and relevant API endpoints.
AdBreak metadata should be polled periodically at a recommended frequency to get information about upcoming stream events.
Tracking playback events involves listening to ID3 events, verifying them against media IDs, and sending GET requests to the media verification endpoint.

The Google DAI API lets you implement Google DAI-enabled streams in environments where implementing the IMA SDK is not supported. We recommend that you still use IMA on platforms where the IMA SDK is supported.

We recommend using the DAI API on the following platforms:

Samsung Smart TV (Tizen)
LG TV
HbbTV
Xbox (JavaScript apps)
KaiOS

The API supports the basic capabilities provided by the IMA DAI SDK. For specific questions about compatibility or supported features, reach out to your Google account manager.

Implement the DAI API for LIVE streams

The DAI API supports linear (LIVE) streams using both HLS and DASH protocols. The steps described in this guide apply to both protocols.

To integrate the API into your app for LIVE streams, complete the following steps:

1. Request a stream

To request a livestream from the DAI API, make a POST call to the stream endpoint. The JSON response contains the stream manifest as well as associated DAI API endpoints and values.

Example request body

https://dai.google.com/linear/v1/dash/event/0ndl1dJcRmKDUPxTRjvdog/stream

{
  "key1" : "value1",
  "stream_parameter1" : "value2"
}

Example response body

{
"stream_id":"c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS",
"stream_manifest":"https://dai.google.com/linear/dash/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/manifest.mpd",
"media_verification_url":"https://dai.google.com/view/p/service/linear/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/loc/ATL/network/51636543/event/0ndl1dJcRmKDUPxTRjvdog/media/",
"metadata_url":"https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/metadata",
"session_update_url":"https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/session",
"polling_frequency":10
}

Error response

In case of errors, standard HTTP error codes are returned with no JSON response body.

Parse the JSON response and store the following values:

stream_id: This value can be used to identify the returned stream.
stream_manifest: This URL is passed to your media player for stream playback.
media_verification_url: This URL is the base endpoint for tracking playback events.
metadata_url: This URL is used to poll for periodic information about upcoming stream events.
session_update_url: This URL is used to update stream request parameters sent during the initial stream request. Note that the parameters of this request replace all parameters set for the earlier stream.
polling_frequency: The frequency, in seconds, when requesting updated AdBreak Metadata from the DAI API.

2. Poll for new AdBreak Metadata

Set a timer to poll for new AdBreak Metadata at the polling frequency, using the metadata URL. If not specified in the stream response, the default recommended interval is 10 seconds.

To optimize bandwidth, do the following:

Make an initial GET request to the metadata_url endpoint.
- Omit the delta_token query parameter. This process lets the server return the full metadata for the stream's Digital Video Recorder (DVR) window. The DVR window contains the timeframe of the broadcast available for a viewer to rewind and play. The response includes a next_delta_token object field.
Store metadata on the client side.
Make subsequent calls using the next_delta_token value that the most recent response returns. Each response contains a next_delta_token value. Always send the latest value you receive.
Update the stored metadata to merge changes and remove obsolete ad breaks.

Don't attempt to parse, construct, or modify the delta token. The token's format can change. Store the token as received, and pass the token back unchanged in the next request.

Example initial request

The initial request takes no query parameters and returns the full metadata:

https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/metadata

Example subsequent request

Each subsequent request passes the next_delta_token value from the previous response as the delta_token parameter. The response contains the following:

Ads
Ad breaks
Tags that the server added or updated since the server issued the token.
An obsolete_ad_break_ids list of ad breaks to remove from your stored metadata

The server omits ad breaks that haven't changed. The following example shows a subsequent poll using the delta token to fetch only these recent changes:

https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/metadata?delta_token=eyJyYW5nZXMiOlt7InMiOjEsImUiOjJ9XX0

If successful, you see an output similar to the following:

{
   "next_delta_token": "eyJyYW5nZXMiOlt7InMiOjEsImUiOjN9XX0",
   "obsolete_ad_break_ids": ["0003069407"],
   "tags":{
      "google_1022389921":{
         "ad":"0003069408_ad1",
         "ad_break_id":"0003069408",
         "type":"start"
      },
      ...
   },
   "ads":{
      "0003069408_ad1":{
         "ad_break_id":"0003069408",
         "position":1,
         "duration":10.01,
         "title":"External - Pod Midroll 1",
         ...
      }
   },
   "ad_breaks":{
      "0003069408":{
         "type":"mid",
         "duration":30,
         "expected_duration":30,
         "ads":3
      }
   }
}

3. Listen to ID3 events and track playback events

To verify that specific events have occurred in a video stream, follow these steps to handle ID3 events:

Store the media events in a queue, saving each media ID along with its timestamp (if surfaced by the player).
On each time update from the player, or at a set frequency (recommended 500 ms), check the media events queue for recently played events by comparing the event timestamps to the playhead.
For media events that you confirm have played, check the type by looking up the media ID in the stored ad break tags. Keep in mind that the stored tags only contain a prefix of the media ID so an exact match isn't possible.
Because your video player app polls the metadata URL periodically, a delay might occur between when your video player encounters an ID3 tag in the stream and when the associated metadata is available. If an ID3 tag isn't found in the stored tags, keep the tag in a queue and re-process the tag after the next metadata poll. Keep the event in the queue until processing finishes.
After you find the tag in the metadata, check the tag's type field against the ad event types listed in the following section. To keep track of whether the video player is playing an ad break, use events with the value progress from the type field. Don't send these events to the media verification endpoint. For all other event types, append the media ID to the media verification endpoint and make a GET request to track playback.
Remove the media event from the queue.

Ad event types

Each tag in the metadata tags object has one of the following event types:

Event type	Description
`start`	Runs at the beginning of the ad.
`firstquartile`	Runs at the end of the first quartile of the ad.
`midpoint`	Runs at the midpoint of the ad.
`thirdquartile`	Runs at the end of the third quartile of the ad.
`complete`	Runs at the end of the ad.
`progress`	Runs periodically during an ad break, to signal that an ad break is playing. Don't send these events to the media verification endpoint.

Example request

https://dai.google.com/view/p/service/linear/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/loc/ATL/network/51636543/event/0ndl1dJcRmKDUPxTRjvdog/media/google_1022389921

Example responses

Accepted for asynchronous verification - HTTP/1.1 202 Accepted
Successful empty response - HTTP/1.1 204 No Content
Media verification not found - HTTP/1.1 404 Not Found
Media verification sent by someone else - HTTP/1.1 409 Conflict

You can verify tracking events in Stream Activity Monitor.

4. Update livestream session parameters

You might want to adjust your session parameters after a stream has been created. To do so, make a request to the session update URL.

Example request body

https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/session

{
  key1 : "value1",
  stream_parameter1 : "value2"
}

Example response body

Successful response would be to look for - HTTP/1.1 200

Limitations

If using the API within webviews, the following limitations apply with respect to targeting:

UserAgent: The user agent parameter is passed as browser specific value instead of the underlying platform.
rdid, idtype, is_lat: The device ID is not properly passed, which limits the capabilities of the following features:
- Frequency capping
- Sequential ad rotation
- Audience segmentation and targeting

Best practices

Keep in mind that the metadata endpoint for livestream indexes is based on the prefix of the corresponding ID3 tag. This is by design to prevent the use of the metadata endpoint for immediately pinging all of the verification nodes.

Manage DAI livestreams Stay organized with collections Save and categorize content based on your preferences.

Page Summary

Implement the DAI API for LIVE streams

1. Request a stream

Example request body

Example response body

Error response

2. Poll for new AdBreak Metadata

Example initial request

Example subsequent request

3. Listen to ID3 events and track playback events

Ad event types

Example request

Example responses

4. Update livestream session parameters

Example request body

Example response body

Limitations

Best practices

Additional resources

Manage DAI livestreams