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.
Requirements when using the API
The following functionality 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
You can use the following information for 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:
-
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 -
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": [...]} -
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"} -
For each ad, trigger the
media_verification_urlwith 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/
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 verifying 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:
-
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 -
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",} -
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"}, ...}} -
For each ad, trigger the
media_verification_urlappending 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/
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 verifying that the type field is set to progress. The progress ID3 can be used, for example, for blocking the video controls.
Detect when an ad break started/ended in the stream using DAI API
DAI inserts ID3 metadata for quartile events (such as Start, First Quartile, Midpoint, Third Quartile, and Complete) into ad segments and progress events (every one second) into ad and slate segments. When any such ID3 tag is first observed, the "ad break started" event can be raised. After that, when no such ID3 tags are encountered for say 2.5 seconds, the "ad break ended" can be raised. DAI-inserted ID3 tags can be identified by their "google_" prefix and their presence in the metadata JSON file.
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 and per-user basis (for example, for live sports where the targeting might not be known in advance).