Dynamic Ad Insertion VOD API

The Dynamic Ad Insertion API enables you to request and track DAI video-on-demand (VOD) streams. HLS and DASH streams are supported.

Service: dai.google.com

The stream method's path is relative to https://dai.google.com

Method: stream

HTTP request

POST https://dai.google.com/ondemand/v1/hls/content/{content-source}/vid/{video-id}/stream

POST https://dai.google.com/ondemand/v1/dash/content/{content-source}/vid/{video-id}/stream

Request header

Authorization: DCLKDAI key="<api-key>"

Path parameters

Request body

The request body is of type application/x-www-form-urlencoded and contains the following parameters:

Response body

If successful, the response body contains a new Stream. For server-side-beaconing streams, this Stream contains only the stream_id and stream_manifest fields.

Open Measurement

The Verifications field contains information for Open Measurement verification for non-server-side-beaconing streams. Verifications contains one or more Verification elements that list the resources and metadata you need to verify creative playback with third-party measurement code. Only JavaScriptResource is supported. For more information, please see the IAB Tech Lab and the VAST 4.1 spec.

Method: media verification

After you encounter an ad media identifier during playback, immediately make a request using the media_verification_url from the stream endpoint. The media_verification_url is an absolute path. Media verification requests aren't necessary for server-side-beaconing streams, where the server initiates media verification.

Requests to the media verification endpoint are idempotent.

HTTP request

GET {media-verification-url}/{ad-media-id}

Response body

media verification returns the following responses:

• HTTP/1.1 204 No Content if media verification succeeds and all pings are sent.
• HTTP/1.1 404 Not Found if the request can't verify the media due to incorrect URL formatting or expiration.
• HTTP/1.1 404 Not Found if a previous verification request for this ID succeeded.
• HTTP/1.1 409 Conflict if another request is already sending pings at this time.

Ad media IDs (HLS)

Ad media identifiers will be encoded in HLS Timed Metadata using the key TXXX, reserved for "user-defined text information" frames. The contents of the frame will be unencrypted and will always begin with the text "google_".

The entire text contents of the frame should be appended to the media_verification_url for each ad verification request.

Ad media IDs (DASH)

Ad media identifiers will be inserted into the manifest through the use of DASH’s EventStream element.

Each EventStream will have a Scheme ID URI of urn:google:dai:2018. They will contain events with the messageData attribute containing an ad media ID beginning with “google_”. The entire content of the messageData attribute should be appended to the media_verification_url for each ad verification request.

Response data

Stream

{
  "stream_id": string,
  "total_duration": number,
  "content_duration": number,
  "valid_for": string,
  "valid_until": string,
  "subtitles": [object(Subtitle)],
  "hls_master_playlist": string,
  "stream_manifest": string,
  "media_verification_url": string,
  "apple_tv": object(AppleTV),
  "ad_breaks": [object(AdBreak)],
}

AppleTV

{
  "interstitials_url": string,
}

AdBreak

{
  "type": string,
  "start": number,
  "duration": number,
  "ads": [object(Ad)],
}

Ad

{
  "seq": number,
  "start": number,
  "duration": number,
  "title": string,
  "description": string,
  "advertiser": string,
  "ad_system": string,
  "ad_id": string,
  "creative_id": string,
  "creative_ad_id": string,
  "deal_id": string,
  "clickthrough_url": string,
  "icons": [object(Icon)],
  "wrappers": [object(Wrapper)],
  "events": [object(Event)],
  "verifications": [object(Verification)],
  "universal_ad_id": object(UniversalAdID),
  "companions": [object(Companion)],
  "interactive_file": object(InteractiveFile),
  "skip_metadata": object(SkipMetadata),
}

Event

{
  "time": number,
  "type": string,
}

Subtitle

{
  "language": string,
  "language_name": string,
  "ttml": string,
  "webvtt": string,
}

SkipMetadata

{
  "offset": number,
  "tracking_url": string,
}

Icon

{
  "click_data": object(ClickData),
  "creative_type": string,
  "click_fallback_images": [object(FallbackImage)],
  "height": int32,
  "width": int32,
  "resource": string,
  "type": string,
  "x_position": string,
  "y_position": string,
  "program": string,
  "alt_text": string,
}

ClickData

{
  "url": string,
}

FallbackImage

{
  "creative_type": string,
  "height": int32,
  "width": int32,
  "resource": string,
  "alt_text": string,
}

Wrapper

{
  "system": string,
  "ad_id": string,
  "creative_id": string,
  "creative_ad_id": string,
  "deal_id": string,
}

Verification

{
  "vendor": string,
  "java_script_resources": [object(JavaScriptResource)],
  "tracking_events": [object(TrackingEvent)],
  "parameters": string,
}

JavaScriptResource

{
  "script_url": string,
  "api_framework": string,
  "browser_optional": boolean,
}

TrackingEvent

{
  "event": string,
  "uri": string,
}

UniversalAdID

{
  "id_value": string,
  "id_registry": string,
}

Companion

{
  "click_data": object(ClickData),
  "creative_type": string,
  "height": int32,
  "width": int32,
  "resource": string,
  "type": string,
  "ad_slot_id": string,
  "api_framework": string,
  "tracking_events": [object(TrackingEvent)],
}

InteractiveFile

{
  "resource": string,
  "type": string,
  "variable_duration": boolean,
  "ad_parameters": string,
}