Integrate with DAI using the API (Beta)

This is a beta feature and may not be available for your network.

The API for Dynamic Ad Insertion (DAI) allows access to monetized streams where the IMA SDK is not supported (for example, Smart TVs). The IMA SDK is required on platforms where it is available. The API supports all existing DAI features, however, they require publisher implementation.

Compare the features supported for DAI integrations before you choose an implementation type.

Functionality that requires publisher implementation when using the API

  • Accessing the DAI stream via the HTTP endpoint and processing JSON responses
  • Constructing the API parameters and targeting key-values
  • Implementing the user experiences (for example, click-throughs and icons)
  • Listening to ID3 events in the player to implement player controls and ad tracking/measurement for both for live linear and VOD
  • Implementing scrubbing behaviors, snapbacks, and bookmarking functionality
  • Selection of streaming formats: HLS or DASH

View the DAI API developer documentation, the specific linear API/VOD API documentation, and the code samples.

You can use the information below to see how to request and process streams via the API for either video on demand, or live linear streams.

 Video on demand (VOD)

The VOD API follows a simple lifecycle from stream creation to ad playback verification:

  1. Request a stream with HTTP POST using the content source ID (cmsid) and video ID (vid), with API key or HMAC token, and ad targeting parameters.

    https://dai.google.com/ondemand/v1/hls/content/<contentId>/vid/<vid>/stream

  2. Process the response for content playback manifest, subtitles/captions, ad break, and content timing information.

    {

        "content_duration": 123.451,

        "stream_manifest": "https://dai.google.com/.../master.m3u8",

        "media_verification_url": "https://dai.google.com/.../media/",

        "stream_id": "9ca0c62a-3291-4f95-986f-d1721f8b96f0",

        "total_duration": 163.451,

        "valid_for": "8h0m0s",

        "valid_until": "2018-05-16T23:21:16.558053292-07:00",

        "ad_breaks": [...]

    }

  3. For each ad break, process the individual ad details for ad elements, such as click-through, companions, and ad break duration information for UI rendering.

    {

      "clickthrough_url": "https://dai.google.com/.../videoclick/1835622921898938400",

      "description": "Example pre-roll ad",

      "duration": 10,

      "seq": 1,

      "title": "Example pre-roll"

    }

  4. For each ad, trigger the media_verification_url with the ID3 value appended from the ad media playback.

    https://dai.google.com/view/p/service/vod/stream/3647080d-c223-442e-a364-c456ee712ece/loc/CBF/network/124319096/content/2474148/vid/bbb-clear/media/

"Progress ID3" events should not be pinged to this endpoint and might lead to an HTTP 404 error.
The Progress events are provided to differentiate playback within and outside of an ad break, and serve no other ad tracking purposes.

You can identify progress events by searching the metadata json file for the media identifier and verify that the type field is set to progress. The progress ID3 can be used, for example, for blocking the video controls.

 Live linear streams

The linear API follows a simple lifecycle from stream creation to ad playback verification:

  1. Request a stream with HTTP POST using the event ID, with API key or HMAC token, and ad targeting parameters.

    https://dai.google.com/linear/v1/hls/event/<eventid>/stream
    https://dai.google.com/linear/v1/dash/event/<eventid>/stream

  2. Process the response for content playback manifest, subtitles/captions, ad break, and content timing information.

    {

        "stream_manifest": "https://dai.google.com/linear/.../master.m3u8",

        "media_verification_url": "https://dai.google.com/linear/.../media/",

        "metadata_url": "https://dai.google.com/linear/.../metadata",

        "polling_frequency": 10,

        "stream_id": "793bf10c-2323-404d-b23b-0a529d96e651:MRN",

    }

  3. Request the ad metadata either at the polling frequency or for each ID3 ad media id, appending the ad media id to the metadata url in a query parameter.

    {

        "ad_breaks": {

            "0001127859": {

                "ads": 3,

                "duration": 30,

                "type": "mid"

            }

        },

        "ads": {

            "0001127859_ad2": {

                "ad_break_id": "0001127859",

                "ad_id": "39135088",

                "ad_system": "GDFP",

                "clickthrough_url": "http://pubads.g.doubleclick.net/pcs/click?...",

                "creative_id": "103990016608",

                "description": "Example linear 10s ad",

                "duration": 10,

                "position": 2,

                "title": "Example linear ad"

            }

        },

        "tags": {

            "google_0028792773": {

                "ad": "0001127859_ad2",

                "ad_break_id": "0001127859",

                "type": "firstquartile"

            }, ...

        }

    }

  4. For each ad, trigger the media_verification_url appending the ID3 value from the ad media playback.

    https://dai.google.com/view/p/service/linear/stream/f0b8970b-cacb-4a9f-83ee-2ef29db47129:CBF2/loc/CBF2/network/51636543/event/sN_IYUG8STe1ZzhIIE_ksA/media/

"Progress ID3" events should not be pinged to this endpoint and might lead to an HTTP 404 error.
The Progress events are provided to differentiate playback within and outside of an ad break, and serve no other ad tracking purposes.

You can identify progress events by searching the metadata json file for the media identifier and verify that the type field is set to progress. The progress ID3 can be used, for example, for blocking the video controls.

Dynamically update targeting and/or key-values per user stream

The session_update_url can be used to replace all of the ad tag parameters used for upcoming ad requests for a live stream (similar to replaceAdTagParameters). This is useful in cases where the targeting information needs to be updated on a per-program basis (for example, for live sports where the targeting might not be known in advance).

Was this helpful?
How can we improve it?

Need more help?

Sign in for additional support options to quickly solve your issue