The Dynamic Ad Insertion API lets you to request and track DAI
linear (LIVE) streams.

## Service: dai.google.com

All URIs are relative to `https://dai.google.com`

## Method: stream

| Methods ||
|---|---|
| `stream` | `POST /linear/v1/hls/event/{assetKey}/stream` Creates a DAI stream for the given event ID. |

### HTTP request

    POST https://dai.google.com/linear/v1/hls/event/{assetKey}/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 ||
|---|---|
| `assetKey` | `string` The stream's event ID. *Note: The stream asset key is an identifier that can also be found in the [Ad Manager UI](https://support.google.com/admanager/answer/7294289#locate-a-live-linear-stream-url-and-asset-key).* |

### 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/live#stream). For server-side-beaconing streams, this [`Stream`](https://developers.google.com/ad-manager/dynamic-ad-insertion/api/full-service/reference/live#stream)
contains only the `stream_id` and `stream_manifest` fields.

### Open Measurement

The DAI API contains information for Open Measurement verification in the
[`Verifications`](https://developers.google.com/ad-manager/dynamic-ad-insertion/api/full-service/reference/live#verifications) field. This field contains one or more
`Verification` elements that list the resources and metadata required to execute
third-party measurement code in order to verify creative playback. 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 encountering an ad media identifier during playback, immediately make a
request using the **media_verification_url** obtained from the **stream**
endpoint. These 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. |

> [!NOTE]
> **Note:** Progress ID3 events shouldn't be pinged to this endpoint. They are for publishers to differentiate playback within and outside of an ad break, and serve no other ad tracking purposes. Publishers can identify progress events by searching the metadata json file for the media identifier and verifying that the **type** field is set to **progress**.

### HTTP request

    GET https://{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 ad verification
URL prior to making each ad verification request.

## Method: metadata

The metadata endpoint at `metadata_url` returns information used to build an ad
UI. The metadata endpoint isn't available for server-side-beaconing streams,
where the server is responsible for initiating ad media verification.

| Methods ||
|---|---|
| `metadata` | `GET /{metadata_url}/{ad-media-id}` `GET /{metadata_url}` Retrieves ad metadata information. |

> [!NOTE]
> **Note:** It is recommended you provide the ad media ID to the endpoint. Otherwise, use `polling_frequency` to determine how often to connect to this endpoint.

### HTTP request

    GET https://{metadata_url}/{ad-media-id}

    GET https://{metadata_url}

### Query parameters

| Parameters |||
|---|---|---|
| `delta_token` | **optional** | `string` An opaque token representing the client's current synchronization state. If provided, the server returns only the metadata that has changed since the token was generated, along with a new `next_delta_token` in the response. If omitted, the server returns the full metadata for the entire DVR window. |

### Response body

If successful, the response returns an instance of
[`PodMetadata`](https://developers.google.com/ad-manager/dynamic-ad-insertion/api/full-service/reference/live#podmetadata).

### Working with Metadata

Metadata has three discrete sections: `tags`, `ads`, and ad `breaks`. The entry
point into the data is the `tags` section. From there, iterate through the tags
and find the first entry whose name is a prefix for the
[ad media ID](https://developers.google.com/ad-manager/dynamic-ad-insertion/api/full-service/reference/live#ad_media_ids_hls) found in the video stream. For example, you
might have an ad media ID that looks like:

    google_1234567890

Then you find a tag object named `google_12345`. In this case, it matches your
ad media ID. Once you find the correct ad media prefix object, you can look up
ad ids, ad break ids, and the event type. Ad ids are then used to index the
`ads` objects and ad break ids are used to index the `breaks` objects.

## Response data


### Stream

Stream is used to render a list of resources for a newly created stream in JSON format.

| JSON representation |
|---|
| ``` { "stream_id": string, "stream_manifest": string, "hls_master_playlist": string, "media_verification_url": string, "metadata_url": string, "session_update_url": string, "polling_frequency": number, } ``` |

| Fields ||
|---|---|
| `stream_id` | `string` The GAM stream identifier. |
| `stream_manifest` | `string` The stream's manifest URL, used to retrieve the multivariant playlist in HLS or the MPD in DASH. |
| `hls_master_playlist` | `string` (DEPRECATED) HLS multivariant playlist URL. Use "stream_manifest" instead. |
| `media_verification_url` | `string` The media verification URL used as base endpoint for tracking playback events. |
| `metadata_url` | `string` Metadata URL used to poll for periodic information about upcoming stream ad events. |
| `session_update_url` | `string` The session's update URL used to update the targeting parameters for this stream. The original values for the targeting parameters are captured during the initial stream create request. |
| `polling_frequency` | `number` The polling frequency, in seconds, when requesting metadata_url or heartbeat_url. |

### PodMetadata

PodMetadata contains metadata information on ads, ad breaks, and media ID tags.

| JSON representation |
|---|
| ``` { "tags": map[string, object(TagSegment)], "ads": map[string, object(Ad)], "ad_breaks": map[string, object(AdBreak)], "next_delta_token": string, "obsolete_ad_break_ids": [], } ``` |

| Fields ||
|---|---|
| `tags` | `https://developers.google.com/ad-manager/dynamic-ad-insertion/api/full-service/reference/live#tagsegment` Map of tag segments indexed by tag prefix. |
| `ads` | `https://developers.google.com/ad-manager/dynamic-ad-insertion/api/full-service/reference/live#ad` Map of ads indexed by ad ID. |
| `ad_breaks` | `https://developers.google.com/ad-manager/dynamic-ad-insertion/api/full-service/reference/live#adbreak` Map of ad breaks indexed by ad break ID. |
| `next_delta_token` | `string` An opaque token for the client to use on the next poll. |
| `obsolete_ad_break_ids` | `string` A list of ad break IDs that are obsolete and should be removed from the client's cache. |

### TagSegment

TagSegment contains a reference to an ad, its ad break, and event type. TagSegment with type="progress" should not be pinged to the ad media verification endpoint.

| JSON representation |
|---|
| ``` { "ad": string, "ad_break_id": string, "type": string, } ``` |

| Fields ||
|---|---|
| `ad` | `string` The ID of this tag's ad. |
| `ad_break_id` | `string` The ID of this tag's ad break. |
| `type` | `string` This tag's event type. |

### AdBreak

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

| JSON representation |
|---|
| ``` { "type": string, "duration": number, "expected_duration": number, "ads": number, } ``` |

| Fields ||
|---|---|
| `type` | `string` Valid break types are: pre, mid, and post. |
| `duration` | `number` Total ad duration for this ad break, in seconds. |
| `expected_duration` | `number` Expected duration of the ad break (in seconds), including all ads and any slate. |
| `ads` | `number` Number of ads in the ad break. |

### Ad

Ad describes an ad in the stream.

| JSON representation |
|---|
| ``` { "ad_break_id": string, "position": 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, "click_tracking_urls": [], "verifications": [object(Verification)], "slate": boolean, "icons": [object(Icon)], "wrappers": [object(Wrapper)], "universal_ad_id": object(UniversalAdID), "extensions": [], "companions": [object(Companion)], "interactive_file": object(InteractiveFile), } ``` |

| Fields ||
|---|---|
| `ad_break_id` | `string` The ID of this ad's ad break. |
| `position` | `number` Position of this ad in the ad break, starting at 1. |
| `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. |
| `click_tracking_urls` | `string` Optional click tracking URLs. |
| `verifications` | `https://developers.google.com/ad-manager/dynamic-ad-insertion/api/full-service/reference/live#verification` Optional Open Measurement verification entries which list the resources and metadata required to execute third-party measurement code to verify creative playback. |
| `slate` | `boolean` Optional bool indicating the current entry is slate. |
| `icons` | `https://developers.google.com/ad-manager/dynamic-ad-insertion/api/full-service/reference/live#icon` A list of icons, omitted if empty. |
| `wrappers` | `https://developers.google.com/ad-manager/dynamic-ad-insertion/api/full-service/reference/live#wrapper` A list of Wrappers, omitted if empty. |
| `universal_ad_id` | `https://developers.google.com/ad-manager/dynamic-ad-insertion/api/full-service/reference/live#universaladid` Optional universal ad ID. |
| `extensions` | `string` Optional list of all \<Extension\> nodes in the VAST. |
| `companions` | `https://developers.google.com/ad-manager/dynamic-ad-insertion/api/full-service/reference/live#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/live#interactivefile` Optional interactive creative (SIMID) that should be displayed during ad playback. |

### 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/live#clickdata` |
| `creative_type` | `string` |
| `click_fallback_images` | `https://developers.google.com/ad-manager/dynamic-ad-insertion/api/full-service/reference/live#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/live#javascriptresource` List of JavaScript resources for the verification. |
| `tracking_events` | `https://developers.google.com/ad-manager/dynamic-ad-insertion/api/full-service/reference/live#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/live#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/live#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. |