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.

Dynamic Ad Insertion API for VOD Streams

The Google DAI API allows you to 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 functionality provided by the IMA DAI SDK. For specific questions about compatibility or supported functionality, reach out to your Google account manager.

Implementing the DAI API for VOD streams

The DAI API supports VOD streams using both HLS and DASH protocols. The steps described in this guide apply to both protocols.

To integrate the API into your application for VOD streams, complete the following steps:

  1. Request a stream by making a POST call to the stream endpoint:

    Example request body:

    https://dai.google.com/ondemand/v1/dash/content/2559737/vid/tos-dash/stream
    
      {
        key1 : "value1",
        stream_parameter1 : "value2"
      }
    

    Example response body:

    {
       "stream_id":"d32f8920-612a-4d46-8bc7-d73fd6c17c85",
       "total_duration":636.458,
       "content_duration":596.458,
       "valid_for":"8h0m0s",
       "valid_until":"2020-06-04T20:39:41.274707306-07:00",
       "stream_manifest":"https://dai.google.com/ondemand/dash/content/2559737/vid/tos-dash/ATL/streams/d32f8920-612a-4d46-8bc7-d73fd6c17c85/manifest.mpd",
       "media_verification_url":"https://dai.google.com/view/p/service/vod/stream/d32f8920-612a-4d46-8bc7-d73fd6c17c85/loc/ATL/network/124319096/content/2559737/vid/tos-dash/media/",
       "ad_breaks":[
          {
             "type":"pre",
             "start":0,
             "duration":10,
             "ads":[
                {
                   "seq":1,
                   "duration":10,
                   "title":"External NCA1C1L1 Preroll",
                   "description":"External NCA1C1L1 Preroll ad",
                   "clickthrough_url":"https://dai.google.com/ondemand/v1/dash/content/2474148/vid/bbb-clear/location/ATL/stream/d32f8920-612a-4d46-8bc7-d73fd6c17c85/videoclick/5489259204425938365",
                   "events":[
                      {
                         "time":0.1,
                         "type":"start"
                      },
                      {
                         "time":2.5,
                         "type":"firstquartile"
                      },
                      {
                         "time":4.75,
                         "type":"midpoint"
                      },
                      {
                         "time":7.5,
                         "type":"thirdquartile"
                      },
                      {
                         "time":9,
                         "type":"complete"
                      }
                   ]
                }
             ]
          },
          {
             "type":"mid",
             "start":45,
             "duration":10,
             "ads":[
                {.... }
                   ]
                }
             ]
          },
          {
             "type":"post",
             "start":626.458,
             "duration":10,
             "ads":[...]
          }
       ]
    }
    

    Error Response

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

  2. Parse the JSON response and store the following values:

    • stream_id
    • stream_manifest
    • media_verification_url
    • ad_breaks
  3. To perform media verification, listen for ID3 events:

    1. Store the media events in a queue, saving each media ID along with its timestamp (if surfaced by the player).
    2. On each time update from the player, or at a set frequency (recommended 500ms), check the media events queue for recently played events by comparing the event timestamps to the playhead.
    3. For media events that you confirm have played, track the playback by appending the media ID to the media verification endpoint and making a GET request.

    Example request body:

    https://dai.google.com/view/p/service/linear/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/loc/ATL/network/51636543/event/0ndl1dJcRmKDUPxTRjvdog/media/
    

    Example response body:

    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
    
  4. Optional: Use the ad_breaks library to look up what type of event was fired.

  5. Remove the media event from the queue.

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 functionality of the following features:
    • Frequency capping
    • Sequential ad rotation
    • Audience segmentation and targeting

Best practices

Mapping ID3 tags to the appropriate event type is tedious on VOD. Use the available library to look up the event directly, like you would with live content.

Additional resources