Learn about DAI Ad Break API

Dynamic Ads Insertion (DAI) Ad Break API lets you create and manage the timing and ad targeting data of upcoming ad breaks in your livestreams.

With DAI Ad Break API, you can do the following:

• Enhance ad fill rate during peak traffic: Give Dynamic Ads Insertion (DAI) services more time to select the highest-yielding ads for your live events. We recommend the DAI Ad Break API when your livestream events have high-concurrency, dynamic ad tags or high-latency ads.
• Take full control of your ad breaks: Create, update, and delete ad breaks in advance, offering more flexibility than in-manifest ad signaling and a higher fill rate for pod serving compared to just-in-time decisioning.
• Deliver an uninterrupted viewer experience: Minimize ad-related playback errors like underfilled or overfilled ad pods by providing precise break information.

This guide describes the DAI Ad Break API methods and walks you through the ad break lifecycle for DAI Full Service and Pod Serving flows.

Learn DAI Ad Break API methods

The API exposes the following standard methods for managing AdBreak resources:

• Create: defines a new AdBreak entity for a LiveStreamEvent entity. Optionally, set the expectedStartTime property to schedule an ad decision to start within 60 seconds before the ad break begins.
• Get: Retrieves the details of a specific AdBreak entity, including ad break state and timing metadata.
• List: Returns a list of AdBreak entities previously created with the API for a given LiveStreamEvent entity, sorted in reverse chronological order. Note that the API doesn't return ad breaks defined only in the content stream manifest.
• Update: Modifies an existing AdBreak entity before the ad decision starts.
• Delete: Cancels the ad decision for a previously created AdBreak entity.

Understand the ad break lifecycle

An AdBreak entity has the following states:

• BREAK_STATE_UNSPECIFIED: The default state.
• BREAK_STATE_SCHEDULED: The ad break has been successfully created and scheduled for ad decision.
• BREAK_STATE_DECISIONED: DAI services have started the ad selection process for the ad break. You can't modify the ad break but can still cancel the ad break with potentially adverse effects on ad servers.

Caution: Canceling an ad break during BREAK_STATE_DECISIONED state prevents ad servers from delivering the ads, which can negatively impact ad server budgeting and frequency capping functionalities.

• BREAK_STATE_COMPLETE: The ad break has been served to users.

The following diagram shows the timeline of an AdBreak entity, from creation to completion.

You can create an AdBreak entity from 1 to 300 minutes before the ad break is expected to start.

• Avoid creating an ad break less than a minute before the break's expected start time, as Google DAI might not have enough time for ad decisions, causing lower ad fill rate.
• Avoid creating an ad break more than 6 hours before the break's expected start time, as ad servers might invalidate the requested ads.

Note: Deactivating a livestream event discards the ad breaks in the BREAK_STATE_SCHEDULED state or the BREAK_STATE_DECISIONED state.

The following sections cover the ad break state transitions in DAI Full Service and Pod Serving flows.

Understand the Full-service DAI flow

Google Full service DAI manages both the content manifest and the ad pods.

For custom ad targeting, use the DAI Ad Break API to create an AdBreak entity ahead of the corresponding ad marker in the content livestream manifest.

• This lead time lets Google DAI services use your AdBreak data for the ad decision.
• When Google DAI detects the manifest ad marker, the system uses ad decisions with the AdBreak entity data and transitions the entity's state to BREAK_STATE_COMPLETE.

Caution: When Google DAI detects the manifest ad marker and the AdBreak entity has BREAK_STATE_SCHEDULED state, the system doesn't use the AdBreak data. The AdBreak entity remains in the BREAK_STATE_SCHEDULED state until you call the delete method to cancel the ad break.

Understand the Pod serving flow

In this flow, you manage the content livestream manifest or use a third party manifest manipulation service to detect the ad markers in the manifest.

Call the DAI Ad Break API before the ad break expected start time, to create an AdBreak entity ahead of when you need to request the ad pod segments or ad manifest.

When your video stitcher detects the manifest ad marker and makes ad segment requests with an ad break ID, Google DAI uses the AdBreak data with the same ID for ad decisions.

After your client requests ad media, the AdBreak entity you created through the API transitions to the BREAK_STATE_COMPLETE state.

Make your first request

To set up API access and make your first request, see Use DAI Ad Break API.