The Dynamic Ad Insertion API lets you 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

| Methods ||
|---|---|
| `stream` | `POST /ondemand/v1/hls/content/{content-source}/vid/{video-id}/stream` Creates an HLS DAI stream for the given content source and video ID. `POST /ondemand/v1/dash/content/{content-source}/vid/{video-id}/stream` Creates a DASH DAI stream for the given content source and video ID. |

### 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

| Parameters ||
|---|---|
| `api‑key` | `string` The API key, provided when creating a stream, must be valid for the publisher's network. Instead of providing it in the request body, the API key can be passed in the HTTP Authorization header with the following format: ``` Authorization: DCLKDAI key="<api-key>" ``` |

### Path parameters

| Parameters ||
|---|---|
| `content-source` | `string` The stream's CMS ID. |
| `video-id` | `string` The stream's video ID. |

### Request body

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

| Parameters |||
|---|---|---|
| `dai-ssb` | Optional | Set to `true` to create a server-side-beaconing stream. Defaults to `false`. The default stream's tracking is client-initiated and pinged on the server side. |
| **DFP Targeting Parameters** | Optional | [Additional targeting parameters.](https://support.google.com/dfp_premium/answer/7320899) |
| **Override Stream Parameters** | Optional | [Override default values of a stream creation parameter.](https://support.google.com/dfp_premium/answer/7320898) |
| **HMAC Authentication** | Optional | [Authenticate using an HMAC-based token.](https://support.google.com/dfp_premium/answer/7637490) |

### Response body

If successful, the response body contains a new
[`Stream`](https://developers.google.com/ad-manager/dynamic-ad-insertion/api/full-service/reference/vod#stream). For server-side-beaconing streams, this [`Stream`](https://developers.google.com/ad-manager/dynamic-ad-insertion/api/full-service/reference/vod#stream)
contains only the `stream_id` and `stream_manifest` fields.

### Open Measurement

The [`Verifications`](https://developers.google.com/ad-manager/dynamic-ad-insertion/api/full-service/reference/vod#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,
see the [IAB Tech Lab](https://iabtechlab.com/standards/open-measurement-sdk/)
and the [VAST 4.1 spec](https://iabtechlab.com/wp-content/uploads/2018/06/VAST4.1-June7-FINAL.pdf).

## 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.

| Methods ||
|---|---|
| `media verification` | `GET {media_verification_url}/{ad_media_id}` Notifies the API of a media verification event. |

### 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 is used to render a list of all the resources for a newly created stream in JSON format .

| JSON representation |
|---|
| ``` { "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)], } ``` |

| Fields ||
|---|---|
| `stream_id` | `string` Stream identifier. |
| `total_duration` | `number` Stream duration in seconds. |
| `content_duration` | `number` Duration of the content, without ads, in seconds. |
| `valid_for` | `string` Duration stream is valid for, in "00h00m00s" format. |
| `valid_until` | `string` Date the stream is valid until, in RFC 3339 format. |
| `subtitles` | `https://developers.google.com/ad-manager/dynamic-ad-insertion/api/full-service/reference/vod#subtitle` A list of Subtitles. Omitted if empty. HLS only. |
| `hls_master_playlist` | `string` (DEPRECATED) HLS master playlist URL. Use stream_manifest. HLS only. |
| `stream_manifest` | `string` The stream's manifest. Corresponds to the master playlist in HLS and the MPD in DASH. This is the only field besides "stream_id" that is present in the response when creating a server-side-beaconing stream. |
| `media_verification_url` | `string` Media verification URL. |
| `apple_tv` | `https://developers.google.com/ad-manager/dynamic-ad-insertion/api/full-service/reference/vod#appletv` Optional information specific to AppleTV devices. HLS only. |
| `ad_breaks` | `https://developers.google.com/ad-manager/dynamic-ad-insertion/api/full-service/reference/vod#adbreak` A list of AdBreaks. Omitted if empty. |

### AppleTV

AppleTV contains information specific to Apple TV devices.

| JSON representation |
|---|
| ``` { "interstitials_url": string, } ``` |

| Fields ||
|---|---|
| `interstitials_url` | `string` Interstitials URL. |

### AdBreak

AdBreak describes a single ad break in the stream. It contains a position, a duration, a type (mid/pre/post) and a list of ads.

| JSON representation |
|---|
| ``` { "type": string, "start": number, "duration": number, "ads": [object(Ad)], } ``` |

| Fields ||
|---|---|
| `type` | `string` Valid break types are: mid, pre, and post. |
| `start` | `number` Position in the stream that the break starts, in seconds. |
| `duration` | `number` Duration of the ad break, in seconds. |
| `ads` | `https://developers.google.com/ad-manager/dynamic-ad-insertion/api/full-service/reference/vod#ad` A list of Ads. Omitted if empty. |

### Ad

Ad describes an ad in the stream. It contains the position of the ad in the break, the duration of the ad and some optional metadata.

| JSON representation |
|---|
| ``` { "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), "extensions": [], } ``` |

| Fields ||
|---|---|
| `seq` | `number` Position of the ad in the break. |
| `start` | `number` Position in the stream that the ad starts, in seconds. |
| `duration` | `number` Duration of the ad, in seconds. |
| `title` | `string` Optional title of the ad. |
| `description` | `string` Optional description of the ad. |
| `advertiser` | `string` Optional advertiser identifier. |
| `ad_system` | `string` Optional ad system. |
| `ad_id` | `string` Optional ad ID. |
| `creative_id` | `string` Optional creative ID. |
| `creative_ad_id` | `string` Optional creative ad ID. |
| `deal_id` | `string` Optional deal ID. |
| `clickthrough_url` | `string` Optional clickthrough URL. |
| `icons` | `https://developers.google.com/ad-manager/dynamic-ad-insertion/api/full-service/reference/vod#icon` A list of icons, omitted if empty. |
| `wrappers` | `https://developers.google.com/ad-manager/dynamic-ad-insertion/api/full-service/reference/vod#wrapper` A list of Wrappers. Omitted if empty. |
| `events` | `https://developers.google.com/ad-manager/dynamic-ad-insertion/api/full-service/reference/vod#event` A list of the events in the ad. |
| `verifications` | `https://developers.google.com/ad-manager/dynamic-ad-insertion/api/full-service/reference/vod#verification` Optional Open Measurement verification entries which list the resources and metadata required to execute third-party measurement code to verify creative playback. |
| `universal_ad_id` | `https://developers.google.com/ad-manager/dynamic-ad-insertion/api/full-service/reference/vod#universaladid` Optional universal ad ID. |
| `companions` | `https://developers.google.com/ad-manager/dynamic-ad-insertion/api/full-service/reference/vod#companion` Optional companions that may be displayed along with this ad. |
| `interactive_file` | `https://developers.google.com/ad-manager/dynamic-ad-insertion/api/full-service/reference/vod#interactivefile` Optional interactive creative (SIMID) that should be displayed during ad playback. |
| `skip_metadata` | `https://developers.google.com/ad-manager/dynamic-ad-insertion/api/full-service/reference/vod#skipmetadata` Optional metadata for skippable ads. If set, this indicates the ad is skippable and includes instructions for how to handle the skip UI and tracking event. |
| `extensions` | `string` Optional list of all \<Extension\> nodes in the VAST. |

### Event

Event contains an event type and a presentation time of an event.

| JSON representation |
|---|
| ``` { "time": number, "type": string, } ``` |

| Fields ||
|---|---|
| `time` | `number` This event's presentation time. |
| `type` | `string` This event's type. |

### Subtitle

Subtitle describes a sidecar subtitle track for the video stream. It stores two subtitle formats: TTML and WebVTT. The TTMLPath attribute contains the URL to the TTML sidecar file and the WebVTTPath attribute similarly contains a URL to the WebVTT sidecar file.

| JSON representation |
|---|
| ``` { "language": string, "language_name": string, "ttml": string, "webvtt": string, } ``` |

| Fields ||
|---|---|
| `language` | `string` A language code, such as 'en' or 'de'. |
| `language_name` | `string` Descriptive name of the language. It differentiates the specific set of subtitles if multiple sets exist for the same language |
| `ttml` | `string` Optional URL to the TTML sidecar file. |
| `webvtt` | `string` Optional URL to the WebVTT sidecar file. |

### SkipMetadata

SkipMetadata provides information needed for clients to handle skip events for skippable ads.

| JSON representation |
|---|
| ``` { "offset": number, "tracking_url": string, } ``` |

| Fields ||
|---|---|
| `offset` | `number` Offset indicates the amount of time in seconds into the ad the player should wait to render the skip button. Omitted if not provided in the VAST. |
| `tracking_url` | `string` TrackingURL contains a URL that should be pinged on the skip event. |

### Icon

Icon contains information about a VAST Icon.

| JSON representation |
|---|
| ``` { "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, } ``` |

| Fields ||
|---|---|
| `click_data` | `https://developers.google.com/ad-manager/dynamic-ad-insertion/api/full-service/reference/vod#clickdata` |
| `creative_type` | `string` |
| `click_fallback_images` | `https://developers.google.com/ad-manager/dynamic-ad-insertion/api/full-service/reference/vod#fallbackimage` |
| `height` | `int32` |
| `width` | `int32` |
| `resource` | `string` |
| `type` | `string` |
| `x_position` | `string` |
| `y_position` | `string` |
| `program` | `string` |
| `alt_text` | `string` |

### ClickData

ClickData contains information about an icon clickthrough.

| JSON representation |
|---|
| ``` { "url": string, } ``` |

| Fields ||
|---|---|
| `url` | `string` |

### FallbackImage

FallbackImage contains information about a VAST fallback image.

| JSON representation |
|---|
| ``` { "creative_type": string, "height": int32, "width": int32, "resource": string, "alt_text": string, } ``` |

| Fields ||
|---|---|
| `creative_type` | `string` |
| `height` | `int32` |
| `width` | `int32` |
| `resource` | `string` |
| `alt_text` | `string` |

### Wrapper

Wrapper contains information about a wrapper ad. It does not include a Deal ID if it does not exist.

| JSON representation |
|---|
| ``` { "system": string, "ad_id": string, "creative_id": string, "creative_ad_id": string, "deal_id": string, } ``` |

| Fields ||
|---|---|
| `system` | `string` Ad system identifier. |
| `ad_id` | `string` Ad ID used for the wrapper ad. |
| `creative_id` | `string` Creative ID used for the wrapper ad. |
| `creative_ad_id` | `string` Creative Ad ID used for the wrapper ad. |
| `deal_id` | `string` Optional deal ID for the wrapper ad. |

### Verification

Verification contains information for Open Measurement, which facilitates third-party viewability and verification measurement. Currently, only JavaScript resources are supported. See https://iabtechlab.com/standards/open-measurement-sdk/

| JSON representation |
|---|
| ``` { "vendor": string, "java_script_resources": [object(JavaScriptResource)], "tracking_events": [object(TrackingEvent)], "parameters": string, } ``` |

| Fields ||
|---|---|
| `vendor` | `string` The verification vendor. |
| `java_script_resources` | `https://developers.google.com/ad-manager/dynamic-ad-insertion/api/full-service/reference/vod#javascriptresource` List of JavaScript resources for the verification. |
| `tracking_events` | `https://developers.google.com/ad-manager/dynamic-ad-insertion/api/full-service/reference/vod#trackingevent` List of tracking events for the verification. |
| `parameters` | `string` An opaque string passed to bootstrap verification code. |

### JavaScriptResource

JavaScriptResource contains information for verification via JavaScript.

| JSON representation |
|---|
| ``` { "script_url": string, "api_framework": string, "browser_optional": boolean, } ``` |

| Fields ||
|---|---|
| `script_url` | `string` URI to javascript payload. |
| `api_framework` | `string` APIFramework is the name of the video framework exercising the verification code. |
| `browser_optional` | `boolean` Whether this script can be run outside of a browser. |

### TrackingEvent

TrackingEvent contains URLs that should be pinged by the client in certain situations.

| JSON representation |
|---|
| ``` { "event": string, "uri": string, } ``` |

| Fields ||
|---|---|
| `event` | `string` The type of the tracking event. |
| `uri` | `string` The tracking event to be pinged. |

### UniversalAdID

UniversalAdID is used to provide a unique creative identifier that is maintained across ad systems.

| JSON representation |
|---|
| ``` { "id_value": string, "id_registry": string, } ``` |

| Fields ||
|---|---|
| `id_value` | `string` The Universal Ad ID of the selected creative for the ad. |
| `id_registry` | `string` A string used to identify the URL for the registry website where the selected creative's Universal Ad ID is cataloged. |

### Companion

Companion contains information for companion ads that may be displayed along with ad.

| JSON representation |
|---|
| ``` { "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)], } ``` |

| Fields ||
|---|---|
| `click_data` | `https://developers.google.com/ad-manager/dynamic-ad-insertion/api/full-service/reference/vod#clickdata` The click data for this companion. |
| `creative_type` | `string` The CreativeType attribute on the \<StaticResource\> node in the VAST if this is a companion of type static. |
| `height` | `int32` The height in pixels of this companion. |
| `width` | `int32` The width in pixels of this companion. |
| `resource` | `string` For static and iframe companions this will be the URL to be loaded and displayed. For HTML companions, this will be the HTML snippet that should be shown as the companion. |
| `type` | `string` Type of this companion. It can be either static, iframe or HTML. |
| `ad_slot_id` | `string` The slot ID for this companion. |
| `api_framework` | `string` The API framework for this companion. |
| `tracking_events` | `https://developers.google.com/ad-manager/dynamic-ad-insertion/api/full-service/reference/vod#trackingevent` List of tracking events for this companion. |

### InteractiveFile

InteractiveFile contains information for interactive creative (i.e. SIMID) that should be displayed during ad playback.

| JSON representation |
|---|
| ``` { "resource": string, "type": string, "variable_duration": boolean, "ad_parameters": string, } ``` |

| Fields ||
|---|---|
| `resource` | `string` The URL to the interactive creative. |
| `type` | `string` The MIME type of the file provided as the resource. |
| `variable_duration` | `boolean` Whether this creative may ask for the duration to be extended. |
| `ad_parameters` | `string` The value of the \<AdParameters\> node in the VAST. |