Dynamic Ad Insertion VOD API

    The Dynamic Ad Insertion API enables you to 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.
    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 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, please see the IAB Tech Lab and the VAST 4.1 spec .

    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_urlfor 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_urlfor 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
    [object(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
    object(AppleTV)

    Optional information specific to AppleTV devices. HLS only.
    ad_breaks
    [object(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
    [object(Ad)]

    A list of Ads. Omitted if empty.
    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
    [object(Icon)]

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

    A list of Wrappers. Omitted if empty.
    events
    [object(Event)]

    A list of the events in the ad.
    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.
    universal_ad_id
    object(UniversalAdID)

    Optional universal ad ID.
    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.
    skip_metadata
    object(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
    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.
    Create a Mobile Website
    View Site in Mobile | Classic
    Share by: