DAI Early Ad Break Notification API

When using the Google DAI platform, you may want to provide targeting data for the next upcoming live/linear ad break in a stream. The Early Ad Break Notification (EABN) API allows you to implement break-specific targeting using key-value pairs, which provides scalability for ad decisioning in high-volume streams.

Calls made to the EABN API must include the asset key to target and the expected duration of the next break. The duration needs to be as close to the actual ad break length as possible. If the expected duration sent is shorter than the provided ad break, the Underfill ad break fill type (defaults to blank slate) is used for the remainder of the break. If the expected duration sent is longer than the provided ad break, your ad break may end before the ad is complete.

In addition to these required fields, you can also send custom targeting parameters, the name of an ad pod template to apply, or SCTE35 Cue Out data, if available.

Prerequisites

Create a service account

To access the EABN API, you need a Google service account.

If you have a Google Cloud account, you can use the IAM module to create a service account. For more information, see Creating and managing service accounts.
If you do not have a Google Cloud account, you can create a service account from the Google API Console, by following these steps:
1. Create a new project or select an existing project.
2. In the Credentials page, click Manage service accounts.
3. In the Service accounts page, click CREATE SERVICE ACCOUNT.
4. In the Create service account page, enter the account details. Then click CREATE.

Once you have successfully created a service account, copy the account's JSON key, which will be used for authentication.

Enable the EABN API

Once your service account has been created, ask your account manager to enable the EABN API for that account.

Enable the DAI API

Once the EABN API has been enabled for your service account, enable the DAI API on the account:

In the Google API library, search for “DAI API”.

Note: If the API does not appear in the search results, contact your account manager to confirm that your account has been enabled for the DAI API.
Select and enable the DAI API.

Using the EABN API

You can call the EABN API using JSON/REST requests.

Authentication

To make authenticated calls to the EABN API, you need to generate OAuth2 service account credentials using the JSON key from your service account and the scope https://www.googleapis.com/auth/video-ads. For more information, see Using OAuth 2.0 for Server to Server Applications.

The must include the resulting authentication token as an Auth header for each call to the EABN API.

Sending an early ad break notification

To send an early ad break notification, send a POST request using the following URL and request body:

POST dai.googleapis.com/v1/adBreaks

Request body

Object
`adBreak`	Required	The wrapper object for `adBreak` properties
`assetKey`	Required	A unique identifier for the `LiveStreamEvent` for which the break is created
`expectedDuration`	Required	The duration of this ad break, using Google’s standard duration format (xx.xxxs where xx.xxx is the number of seconds)
`scte35CueOut`	Optional	Base-64-encoded data from the scte35 cue out. Can include the `splice_insert()` or `time_signal()` command. Examples: `time_signal()`: `/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==` `splice_insert()`: `/DAvAAAAAAAA///wFAVIAACPf+/+c2nALv4AUsz1AAAAAAAKAAhDVUVJAAABNWLbowo=`
`custParams`	Optional	Key-value pairs to be included on ad requests for this break for custom criteria targeting in AM360, separated by `=` and joined by `&`. Example: `key=value&key2=value2,value3` For more information on targeting, see Supply targeting parameters to your stream.
`ptpln`	Optional	The ad pod template name

Response header

HTTP/1.1 200 OK

Response body

The response body contains all of the parameters sent in the adBreak object, as well as an additional daiBreakId field, which contains the internal DAI identifier for the created ad break within the stream.

Example

Request

POST /v1/adBreaks HTTP/1.1
Content-Type: application/json

{
  "adBreak": {
    "assetKey": "asset1",
    "expectedDuration": "30s",
    "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==",
    "custParams": "param1=value1&param2=value2",
    "ptpln": "podtemplate"
  }
}

Response

HTTP/1.1 200 OK

{
  "assetKey": "asset1",
  "expectedDuration": "30s",
  "custParams": "param1=value1&param2=value2",
  "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==",
  "ptpln": "podtemplate",
  "daiBreakId": 1
}

Sample implementation (Python)

from __future__ import absolute_import
from __future__ import division
from __future__ import print_function

from absl import app

from google.auth.transport.requests import AuthorizedSession
from google.oauth2 import service_account

SERVICE_ACCOUNT_KEY_FILE = "~/eabn_key.json"
ASSET_KEY = "asset1"

SCOPES = ['https://www.googleapis.com/auth/video-ads']
EABN_API_URL = 'https://dai.googleapis.com/v1/adBreaks'


def main():
  credentials = service_account.Credentials.from_service_account_file(
      SERVICE_ACCOUNT_KEY_FILE, scopes=SCOPES)

  authed_session = AuthorizedSession(credentials)

  data = {
      'assetKey': ASSET_KEY,
      'expectedDuration': '120s',
      'custParams': 'param1=value1&param2=value2',
      'scte35CueOut': '/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==',
  }

  r = authed_session.post(EABN_API_URL, json={'adBreak': data})
  print(r.status_code)
  print(r.headers)
  print(r.text)

if __name__ == '__main__':
  app.run(main)