Dynamic Ad Insertion Linear API

  • The Dynamic Ad Insertion API allows requesting and tracking DAI linear (LIVE) streams.

  • You create a DAI stream using a POST request to the /linear/v1/hls/event/{assetKey}/stream endpoint with the asset key in the path and an API key in the header or request body.

  • The API provides endpoints for media verification and metadata retrieval, used for tracking playback events and building the ad UI respectively.

  • Response data includes information about the created stream, ad breaks, ads, and Open Measurement verification details.

  • Metadata, available for client-side beaconing streams, helps match ad media IDs found in the stream with detailed ad and ad break information for UI purposes.

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

Service: dai.google.com

All URIs below 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.

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.
Override Stream Parameters Optional Override default values of a stream creation parameter.
HMAC Authentication Optional Authenticate using an HMAC-based token.

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 DAI API contains information for Open Measurement verification in the 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, please see the IAB Tech Lab and the VAST 4.1 spec.

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, above. 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.

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.

HTTP request

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

GET https://{metadata_url}

Response body

If successful, the response returns an instance of 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 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)],
}
Fields
tags map[string, object(TagSegment)]

Map of tag segments indexed by tag prefix.
ads map[string, object(Ad)]

Map of ads indexed by ad ID.
ad_breaks map[string, object(AdBreak)]

Map of ad breaks indexed by ad break ID.

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 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 [object(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 [object(Icon)]

A list of icons, omitted if empty.
wrappers [object(Wrapper)]

A list of Wrappers, omitted if empty.
universal_ad_id object(UniversalAdID)

Optional universal ad ID.
extensions string

Optional list of all <Extension> nodes in the VAST.
companions [object(Companion)]

Optional companions that may be displayed along with this ad.
interactive_file object(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 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

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 [object(JavaScriptResource)]

List of JavaScript resources for the verification.
tracking_events [object(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 object(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 [object(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.