Dynamic Ad Insertion pod serving VOD API

The Dynamic Ad Insertion API lets you request and track DAI on-demand streams.

Service: dai.google.com

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

Method: create stream

This method creates a stream directly from the device, returning all resources needed for the client application to play and track ads, and display UI elements.

Methods
create stream POST: /ondemand/pods/api/v1/network/{network_code}/stream

Create a DAI pod serving VOD session.

HTTP request

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

Path parameters

Parameters
network_code string

The publisher's Google Ad Manager network code.

Request body

The request body is of type application/json and must contain a CreateStreamRequest object.

Response body

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

Method: register stream

This method registers a stream on the Google DAI backend from the device, returning all the resources needed for the client application to track ads and display UI elements. Unlike the create stream method, this method does not return a playable ads manifest. Instead, this action is achieved in a separate server call: decision ad pods.

Methods
register stream POST: /ondemand/pods/api/v1/network/{network_code}/stream_registration

Registers a DAI pod serving VOD session.

HTTP request

POST https://dai.google.com/ondemand/pods/api/v1/network/{network_code}/stream_registration

Path parameters

Parameters
network_code string

The publisher's Google Ad Manager network code.

Request body

The request body is of type application/json and must contain a StreamRegistrationRequest object.

Response body

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

Method: retrieve ad pods

This method follows a register stream call from a device and is necessary to retrieve playable ad manifests to stitch in content manifests.

Methods
decision ad pods POST: /ondemand/pods/api/v1/network/{network_code}/streams/{stream_id}/adpods

Decision ad pods for a DAI pod serving VOD session.

HTTP request

POST https://dai.google.com/ondemand/pods/api/v1/network/{network_code}/streams/{stream_id}/adpods

Path parameters

Parameters
network_code string

The publisher's Google Ad Manager network code.

stream_id string

The stream_id received from a stream_registration call.

Request body

The request body is of type application/json and must contain a AdPodDecisionRequest object.

Response body

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

Method: ad pods metadata

This method returns all the information needed for the client app to track ads and render appropriate UI elements accurately.

Methods
ad pods metadata GET: /ondemand/pods/api/v1/network/.../metadata

Retrieve ad pods metadata for a specific session. This URL is returned in the StreamRegistrationResponse metadata_url attribute.

HTTP request

GET: /ondemand/pods/api/v1/network/.../metadata

Response body

If successful, the response body contains an Ad pods metadata object.

Data

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)],
  "polling_frequency": number,
}
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.
polling_frequency number

Recommended metadata URL polling frequency, in seconds. Populated for VOD streams using On-Demand decisioning.

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.

MatchOpts

MatchOpts specify strict media matching requirements for a stream.
JSON representation
{
  "audio_channels": boolean,
  "audio_sample_rate": boolean,
}
Fields
audio_channels boolean

Match audio channels between content and ads.
audio_sample_rate boolean

Match audio sample rate between content and ads.

CreateStreamRequest

CreateStreamRequest describes the information found in HTTP requests to the VOD pod serving API. Stream create is initiated by the VTP (video tech partner), on behalf of the SDK and the publisher, for every user. The stream created results in decisioned ad pods for the VTP to stitch. This is in contrast to the StreamRegistrationRequest+AdPodDecisionRequest flow which registers a stream and decisions adpods in multiple requests.
JSON representation
{
  "encoding_profiles": [object(EncodingProfile)],
  "ad_tag": string,
  "cuepoints": [],
  "manifest_type": string,
  "enable_hls_asset_list": boolean,
  "targeting_parameters": map[string, string],
  "content_duration_seconds": number,
  "decision_timing_options": object(DecisionTimingOptions),
  "enable_inline_manifests": boolean,
  "dai_options": object(CreateStreamOptions),
}
Fields
encoding_profiles [object(EncodingProfile)]

A list of encoding profiles. Required.
ad_tag string

The base ad tag for decisioning. Required.
cuepoints number

A list of cuepoints, in seconds. Required when the ad tag's response uses positional time offsets.
manifest_type string

Valid manifest types are: hls and dash. Default: hls. Optional.
enable_hls_asset_list boolean

Indicates if HLS asset list interstitials are enabled. When enabled, DAI will return asset list URLs for each adbreak, which can be used for HLS interstitials.
targeting_parameters string

Additional Ad Manager targeting params. Optional.
content_duration_seconds number

ContentDurationSeconds is the duration of the content in seconds. Required when the ad tag's response uses percent time offsets.
decision_timing_options object(DecisionTimingOptions)

Indicates when adpods should be decisioned.
enable_inline_manifests boolean

Indicates whether break manifests should be inlined in the JSON response.
dai_options object(CreateStreamOptions)

DAIOptions for stream creation.

CreateStreamOptions

CreateStreamOptions represents the options available on the one-step stream create workflow.
JSON representation
{
  "dash_profile": string,
  "match_options": object(MatchOpts),
  "data_sharing_policy_code": string,
  "sam_id": string,
  "session_title": string,
  "dash_inband_event_stream": boolean,
  "distinct_ad_profiles": boolean,
  "tracking_mode": string,
  "emsg_version": uint32,
}
Fields
dash_profile string

MPEG-DASH profile to use, 'live' or 'on-demand'.
match_options object(MatchOpts)

data_sharing_policy_code string

Allows publishers to override the network default data sharing policy.
sam_id string

sam_id is the SAM debug key for the session, optional.
session_title string

session_title is the SAM session title for the stream, optional.
dash_inband_event_stream boolean

dash_inband_event_stream indicates that DAI inserts ID3 messages as inband events (in-media) using the InbandEventStream element, rather than as EventStream elements (in-manifest).
distinct_ad_profiles boolean

If set to true, indicates that the server will use any available ad profile at most once when matching requested encoding profiles.
tracking_mode string

tracking_mode is the type of ad tracking to use for the stream, optional. Valid values are: 'ad_media', 'server', 'client'.
emsg_version uint32

emsg_version forces a specific emsg version to be used for in-media ID3s. Only supported when dash_inband_event_stream is true.

StreamRegistrationRequest

StreamRegistrationRequest registers a stream from the device for future adpod decisioning. This is in contrast to a CreateStreamRequest which creates a stream and decisions adpods in a single request.
JSON representation
{
  "targeting_parameters": map[string, string],
  "dai_options": object(StreamRegistrationOptions),
}
Fields
targeting_parameters string

Additional Ad Manager targeting params. Optional.
dai_options object(StreamRegistrationOptions)

DAIOptions for stream registration.

StreamRegistrationOptions

StreamRegistrationOptions lists the options available for stream creation
JSON representation
{
  "sam_id": string,
  "tracking_mode": string,
  "emsg_version": uint32,
  "skippable_ads_supported": boolean,
}
Fields
sam_id string

sam_id is the SAM debug key for the session, optional.
tracking_mode string

tracking_mode is the type of ad tracking to use for the stream, optional. Valid values are: 'ad_media', 'server', 'client'.
emsg_version uint32

emsg_version forces a specific emsg version to be used for in-media ID3s. Only supported when dash_inband_event_stream is true.
skippable_ads_supported boolean

Indicates if skippable ads are supported.

StreamRegistrationResponse

StreamRegistrationResponse represents the json response sent back to the client in response to a StreamRegistrationRequest. It includes the stream ID and all the URLs the device will need. The stream ID can be referenced in a subsequent adpod decision request. This is in contrast to a CreateStreamResponse which represents a response for creating a stream and decisioning adpods at the same time.
JSON representation
{
  "stream_id": string,
  "media_verification_url": string,
  "valid_for": string,
  "valid_until": string,
  "metadata_url": string,
}
Fields
stream_id string

StreamID is the unique identifier for this viewer’s current stream.
media_verification_url string

MediaVerificationURL is the URL prefix to be used in ad media verification requests described below. Absent for client side beaconing streams.
valid_for string

ValidFor is the duration for which this stream is valid, in "00h00m00s" format.
valid_until string

ValidUntil is the date and time until which this stream is valid.
metadata_url string

MetadataURL is the metadata URL to be used to request adpod metadata.

DecisionTimingOptions

DecisionTimingOptions describes the timing options for decisioning adbreaks for the stream.
JSON representation
{
  "type": string,
  "on_create_breaks": [],
}
Fields
type string

Type describes when adpods are decisioned for the stream. Valid types are: on_create (default), on_demand. When type is on_demand, ads are lazily decisioned when the manifest is requested for a particular break. When type is on_create, ads are all decisioned when the stream is created.
on_create_breaks string

OnCreateBreaks is a list of case-sensitive VMAP breakIDs that should be decisioned on stream create. This field is only allowed if type is on_demand. The special ad break identifiers "preroll" and "postroll" can be used to indicate that the preroll or postroll break should be decisioned at stream create time.

EncodingProfile

EncodingProfile describes the encoding of a single content variant. It may contain only video settings, only audio settings (in the case of the media type), both video and audio settings, or neither in the case of subtitles.
JSON representation
{
  "profile_name": string,
  "type": string,
  "container_type": string,
  "video_settings": object(VideoSettings),
  "audio_settings": object(AudioSettings),
  "subtitle_settings": object(SubtitleSettings),
}
Fields
profile_name string

The publisher provided name for the profile. Unique per stream. Required.
type string

Valid types are: media, iframe, subtitles. Required.
container_type string

Valid types are: mpeg2ts, fmp4cmaf, and hls_packed_audio. Required for Type media and iframe.
video_settings object(VideoSettings)

Video settings are required if the container type is iframe. Otherwise, they are only present if the profile contains video.
audio_settings object(AudioSettings)

Audio settings are present if the profile contains audio. Audio settings are only allowed if the container type is media.
subtitle_settings object(SubtitleSettings)

Subtitles settings are required for Type subtitles.

VideoSettings

VideoSettings describes the video of an encoding profile. If one video setting is present, all must be present.
JSON representation
{
  "codec": string,
  "bitrate": int32,
  "frames_per_second": number,
  "resolution": object(Resolution),
}
Fields
codec string

The RFC6381 codec string of the video.
bitrate int32

The max video bitrate of the encoding profile.
frames_per_second number

The frames per second of the video.
resolution object(Resolution)

The width x height resolution of the video.

AudioSettings

AudioSettings describes the audio of an encoding profile. If one audio setting is present, all must be present.
JSON representation
{
  "codec": string,
  "bitrate": int32,
  "channels": int32,
  "sample_rate": int64,
}
Fields
codec string

The RFC6381 codec string of the audio.
bitrate int32

The max audio bitrate of the encoding profile.
channels int32

The number of audio channels (including low frequency channels).
sample_rate int64

The sample rate of the audio, in hertz.

SubtitleSettings

SubtitleSettings describes the subtitles of an encoding profiles.
JSON representation
{
  "format": string,
  "language": string,
}
Fields
format string

The format of the subtitles: webvtt for hls, webvtt or ttml for dash.
language string

The language to insert in the manifest.

Resolution

Resolution describes the width x height of a video.
JSON representation
{
  "width": int32,
  "height": int32,
}
Fields
width int32

Width of the video, in pixels. Required.
height int32

Height of the video, in pixels. Required.

AdPodDecisionRequest

AdPodDecisionRequest represents a request to decision adpods for a previously registered stream.
JSON representation
{
  "encoding_profiles": [object(EncodingProfile)],
  "ad_tag": string,
  "cuepoints": [],
  "manifest_type": string,
  "enable_hls_asset_list": boolean,
  "targeting_parameters": map[string, string],
  "content_duration_seconds": number,
  "decision_timing_options": object(DecisionTimingOptions),
  "enable_inline_manifests": boolean,
  "dai_options": object(AdPodDecisionOptions),
}
Fields
encoding_profiles [object(EncodingProfile)]

A list of encoding profiles. Required.
ad_tag string

The base ad tag for decisioning. Required.
cuepoints number

A list of cuepoints, in seconds. Required when the ad tag's response uses positional time offsets.
manifest_type string

Valid manifest types are: hls and dash. Default: hls. Optional.
enable_hls_asset_list boolean

Indicates if HLS asset list interstitials are enabled. When enabled, DAI will return asset list URLs for each adbreak, which can be used for HLS interstitials.
targeting_parameters string

Additional Ad Manager targeting params. Optional.
content_duration_seconds number

ContentDurationSeconds is the duration of the content in seconds. Required when the ad tag's response uses percent time offsets.
decision_timing_options object(DecisionTimingOptions)

Indicates when adpods should be decisioned.
enable_inline_manifests boolean

Indicates whether break manifests should be inlined in the JSON response.
dai_options object(AdPodDecisionOptions)

DAIOptions for ad pod decision.

AdPodDecisionResponse

AdPodDecisionResponse represents a response to decision adpods for a previously registered stream. It contains a list of the ad pods decisioned for that stream.
JSON representation
{
  "valid_for": string,
  "valid_until": string,
  "ad_pods": [object(AdPod)],
}
Fields
valid_for string

ValidFor is the duration for which this stream is valid, in "00h00m00s" format.
valid_until string

ValidUntil is the date and time until which this stream is valid.
ad_pods [object(AdPod)]

A list of ad pod ordered by insertion order.

CreateStreamResponse

CreateStreamResponse represents the json response sent back to the client in response to a CreateStreamRequest.
JSON representation
{
  "valid_for": string,
  "valid_until": string,
  "ad_pods": [object(AdPod)],
  "stream_id": string,
  "media_verification_url": string,
  "pod_metadata": object(PodMetadata),
  "metadata_url": string,
}
Fields
valid_for string

ValidFor is the duration for which this stream is valid, in "00h00m00s" format.
valid_until string

ValidUntil is the date and time until which this stream is valid.
ad_pods [object(AdPod)]

A list of ad pod ordered by insertion order.
stream_id string

StreamID is the unique identifier for this viewer’s current stream.
media_verification_url string

MediaVerificationURL is the URL prefix to be used in ad media verification requests described below. Absent for client side beaconing streams.
pod_metadata object(PodMetadata)

PodMetadata contains the extra information required to render the pod on the device and trigger verification. As described in the Dynamic Ad Insertion Linear API docs. Only included for client side beaconing streams.
metadata_url string

MetadataURL is the metadata URL to be used to request adpod metadata.

AdPod

AdPod represents a decisioned ad break ready for playback.
JSON representation
{
  "manifest_uris": map[string, string],
  "multivariant_uri": string,
  "mpd_uri": string,
  "manifests": map[string, string],
  "multivariant_manifest": string,
  "mpd_manifest": string,
  "asset_list_uri": string,
  "start": number,
  "duration": number,
  "type": string,
  "midroll_index": number,
}
Fields
manifest_uris string

ManifestURIs is a map of encoding profile name to HLS variant manifest_uris for HLS content.
multivariant_uri string

MultivariantURI is the URI for the multivariant manifest for HLS content.
mpd_uri string

MPDURI is the URI for the MPD for DASH content.
manifests string

Manifests is a map of encoding profile name to the HLS variant manifest. Populated only if the stream has enable_inline_manifests set to true.
multivariant_manifest string

MultivariantManifest is the multivariant manifest for HLS content. Populated only if the stream has enable_inline_manifests set to true.
mpd_manifest string

MPDManifest is the MPD manifest for DASH content. Populated only if the stream has enable_inline_manifests set to true.
asset_list_uri string

AssetListURI is the URI for the HLS interstitial asset-list for HLS content. Populated only if the stream has HLS asset-list interstitials enabled.
start number

Start time of the ad pod in the asset timeline (without including the preceding ad pods) in floating point seconds.
duration number

Duration of the ad pod in floating point seconds.
type string

Ad break type.
midroll_index number

1-based index of midrolls in a stream, based on VMAP break ID. Omitted for preroll and postrolls.

AdPodDecisionOptions

AdPodDecisionOptions represents additional options for the stream.
JSON representation
{
  "dash_profile": string,
  "match_options": object(MatchOpts),
  "data_sharing_policy_code": string,
  "sam_id": string,
  "session_title": string,
  "dash_inband_event_stream": boolean,
  "distinct_ad_profiles": boolean,
}
Fields
dash_profile string

MPEG-DASH profile to use, 'live' or 'on-demand'.
match_options object(MatchOpts)

data_sharing_policy_code string

Allows publishers to override the network default data sharing policy.
sam_id string

sam_id is the SAM debug key for the session, optional.
session_title string

session_title is the SAM session title for the stream, optional.
dash_inband_event_stream boolean

dash_inband_event_stream indicates that DAI inserts ID3 messages as inband events (in-media) using the InbandEventStream element, rather than as EventStream elements (in-manifest).
distinct_ad_profiles boolean

If set to true, indicates that the server will use any available ad profile at most once when matching requested encoding profiles.

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,
  "valid_for": string,
  "valid_until": string,
  "media_verification_url": string,
}
Fields
stream_id string

Stream identifier.
valid_for string

Duration stream is valid for, in "00h00m00s" format.
valid_until string

Date the stream is valid until, in RFC 3339 format.
media_verification_url string

Media verification URL.

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.