Dynamic Ad Insertion pod serving live API

The Dynamic Ad Insertion API lets you request and track DAI livestreams.

Service: dai.google.com

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

Method: stream

Methods
stream	POST /ssai/pods/api/v1/network/{network_code}/custom_asset/{custom_asset_key}/stream Registers a DAI DAI pod serving livestream session.

HTTP request

POST https://dai.google.com/ssai/pods/api/v1/network/{network_code}/custom_asset/{custom_asset_key}/stream

Path parameters

Parameters
network_code	string The publisher's Google Ad Manager network code.
custom_asset_key	string The custom identifier associated this event in Google Ad Manager.

Request body

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

Parameters
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 object.

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: pod segment

Methods
pod segment	GET /linear/pods/v1/seg/network/{network_code}/custom_asset/{custom_asset_key}/{pod_identifier}/profile/{profile_name}/{segment_number}.{segment_format} Creates a DAI stream for the given event ID.

HTTP request

GET https://dai.google.com/linear/pods/v1/seg/network/{network_code}/custom_asset/{custom_asset_key}/{pod_identifier}/profile/{profile_name}/{segment_number}.{segment_format}

Path parameters

Parameters
network_code	string The publisher's Google Ad Manager network code.
custom_asset_key	string The custom identifier associated this event in Google Ad Manager.
pod_identifier	The following formats are supported: pod/{integer} The numeric identifier for the current ad break. Ad pod IDs are assigned incrementally for each ad break event, starting at 1. ad_break_id/{string} The string identifier for the current ad break. Important: pod_identifier must be of the same format and value for all users viewing the same ad break in the livestream event. The manifest manipulator must insert the same pod_identifier format throughout the lifetime of a livestream event.
profile_name	string The name of the requested Google Ad Manager DAI encoding profile. The encoding profile must be one of the configured encoding profiles for the selected event.
segment_number	integer The index of the requested segment within the current ad pod, starting at zero. Important: When using an MP4 container, the initialization segment can be requested by setting segment_number to init.
segment_format	string The file extension associated with the requested segment format. Accepted extensions are: ts, mp4, vtt, aac, ac3 or eac3.

Query parameters

Parameters
stream_id	required	string The stream ID for the current user's session. This value is returned by a successful request to the stream endpoint.
sd	required^1	integer The duration of the requested segment, in milliseconds.
so	optional	The offset of the requested segment within the ad pod, in milliseconds. If you omit the so parameter, it will be calculated by multiplying the segment duration by the segment number.
pd	required^2	integer The duration of the ad pod, in milliseconds.
auth-token	required	string A signed, url-encoded HMAC token for the current ad pod.
last	optional	boolean Indicates the last segment in the ad break. Omit this parameter for all other segments.
scte35	optional	string Base64-encoded SCTE-35signal for this ad break.
cust_params	optional	string A set of key-value pairs, used for Ad Manager campaign targeting. These pairs must be represented as a url-encoded query string. Example: Parameters section = sports page = golf,tennis Request URL ...&cust_params=section%3Dsports%26page%3Dgolf%2Ctennis...

Footnotes

1. sd is not required for initialization segments. ↩
2. pd is not required for events with durationless ad breaks enabled. ↩

Example

GET https://dai.google.com/linear/pods/v1/seg/network/sandbox_dev/custom_asset/podserving-segredirect-custom-key/ad_break_id/adbreak-2/profile/8b8888cf79ad43f0800482ffc035a1ac_ts_a/1.ts?so=0&sd=10000&pd=30000&stream_id=8e19cbc6-850b-404c-99d7-860aa4a674cb:TEST

GET https://dai.google.com/linear/pods/v1/seg/network/sandbox_dev/custom_asset/podserving-segredirect-custom-key/pod/2/profile/8b8888cf79ad43f0800482ffc035a1ac_ts_a/1.ts?so=0&sd=10000&pd=30000&stream_id=8e19cbc6-850b-404c-99d7-860aa4a674cb:TEST

Response body

If successful, the response body will be a playable stream segment matching the format and parameters specified in the request.

Method: HLS pod manifest

Retrieves an HLS ad pod manifest of a livestream that is ready for a client video player to load and play.

Methods
GET	GET /linear/pods/v1/hls/network/{network_code}/custom_asset/{custom_asset}/pod/{pod_id}.m3u8; API to retrieve an HLS multivariant playlist for an ad pod.

HTTP request

GET https://dai.google.com/linear/pods/v1/hls/network/{network_code}/custom_asset/{custom_asset_key}/pod/{pod_id}.m3u8?stream_id={stream_id}&pd={pod_duration}

Path parameters

Parameters
network_code	string The publisher's Google Ad Manager network code.
custom_asset_key	string The custom identifier associated this event in Google Ad Manager
pod_id	integer The numeric identifier for the current ad break. Ad pod IDs are assigned incrementally for each ad break event, starting at 1. pod_id must be the same for all users viewing the same ad break in the current event.

Query parameters

Parameters
stream_id	Required	string The stream ID for the current user's session. This value is returned by a successful request to the stream endpoint.
pd	Required	integer The duration of the ad pod, in milliseconds.
scte35	optional	string Base64-encoded SCTE-35signal for this ad break.
cust_params	optional	string A set of key-value pairs, used for Ad Manager campaign targeting. These pairs must be represented as a url-encoded query string. Example: Parameters section = sports page = golf,tennis Request URL ...&cust_params=section%3Dsports%26page%3Dgolf%2Ctennis...

Response body

If successful, the response body is an HLS multivariant playlist.

Method: DASH pod manifest

Retrieves an MPEG-DASH ad pod manifest of a livestream that is ready for a client video player to load and play.

Methods
GET	GET /linear/pods/v1/dash/network/{network_code}/custom_asset/{custom_asset}/stream/{stream_id}/pod/{pod_id}/manifest.mpd API to retrieve an MPEG-DASH mpd playlist for an ad pod.

HTTP request

GET https://dai.google.com/linear/pods/v1/dash/network/{network_code}/custom_asset/{custom_asset_key}/stream/{stream_id}/pod/{pod_id}/manifest.mpd?pd={pod_duration}

Path parameters

Parameters
network_code	string The publisher's Google Ad Manager network code.
custom_asset_key	string The custom identifier associated this event in Google Ad Manager
stream_id	string The stream ID for the current user's session. This value is returned by a successful request to the stream endpoint.
pod_id	integer The numeric identifier for the current ad break. Ad pod IDs are assigned incrementally for each ad break event, starting at 1. pod_id must be the same for all users viewing the same ad break in the current event.

Query parameters

Parameters
pd	Required	integer The duration of the ad pod, in milliseconds.
scte35	optional	string Base64-encoded SCTE-35signal for this ad break.
cust_params	optional	string A set of key-value pairs, used for Ad Manager campaign targeting. These pairs must be represented as a url-encoded query string. Example: Parameters section = sports page = golf,tennis Request URL ...&cust_params=section%3Dsports%26page%3Dgolf%2Ctennis...

Response body

If successful, the response body is an MPEG-DASH mpd playlist.

Method: DASH pod period template

Methods

pods

GET /linear/pods/v1/dash/network/{network_code}/custom_asset/{custom_asset_key}/pods.json Requests a DASH period template from Google Ad Manager. This template contains macros that you must populate with your stream parameters. Once these macros are populated, the template becomes your ad break period, and can be stitched into your DASH manifest. Important: Only request this template once per stream session, then cache it for reuse with each ad break.

HTTP request

GET https://dai.google.com/linear/pods/v1/dash/network/{network_code}/custom_asset/{custom_asset_key}/pods.json

Path parameters

Parameters
network_code	string The publisher's Google Ad Manager network code.
custom_asset_key	string The custom identifier associated this event in Google Ad Manager.

Query parameters

Parameters
stream_id	required	string The stream ID for the current user's session. This value is returned by a successful request to the stream endpoint.

Response body

If successful, the response body contains a new PodTemplateResponse object.

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.

Note: Progress ID3 events should not 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

Ad media identifiers will be encoded in a separate metadata track — timed metadata for HLS transport stream, or emsg for mp4 files. Ad media identifiers will always begin with the string google_.

The entire text contents of the metadata entry 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: 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}

Response body

If successful, the response returns an instance of PodMetadata.

Parsing 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, "media_verification_url": string, "metadata_url": string, "session_update_url": string, "heartbeat_url": string, "polling_frequency": number, "pod_manifest_url": string, "manifest_format": string, }

Fields
stream_id	string The GAM stream identifier.
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.
heartbeat_url	string The heartbeat URL, used to keep the server side beaconing stream alive, it must be pinged every {PollingFrequency} seconds. Populated for server side beaconing streams.
polling_frequency	number The polling frequency, in seconds, when requesting metadata_url or heartbeat_url.
pod_manifest_url	string The pod manifest URL template is used to generate the URL to retrieve a stream's pod manifest, corresponding to the URL of the multivariant playlist in HLS or the MPD in DASH. Populated for Livestream events of Dynamic Ad Insertion type POD_SERVING_MANIFEST. https://developers.google.com/ad-manager/api/reference/v202305/LiveStreamEventService.DynamicAdInsertionType
manifest_format	string Manifest format is the format of the manifest retrieved from pod_manifest_url, either dash or hls.

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

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.

PodTemplateResponse

PodTemplateResponse represents the JSON payload returned to a VTP for pod stitching.

JSON representation
{ "dash_period_template": string, "segment_duration_ms": int64, }

Fields
dash_period_template	string DashPeriodTemplate is the xml template for the period to be filled with appropriate data before stitching.
segment_duration_ms	int64 SegmentDurationMS is the duration of the period segments in milliseconds.

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.