Early ad break notification

Using the Early Ad Break Notification API

Note: This API is still in beta. Speak to your account manager if you would like to request access to the EABN program.

Early Ad Break Notification (EABN) API allows you to notify the Google Ad Manager of the upcoming ad break with its metadata prior to the start of the ad break. You can send a notification request up to one hour before the ad break. This guide explains how to enable and use the EABN API, and request and response samples.

Caution: EABN requests are immutable, so once a break is created, it cannot be modified. Subsequent requests to create ad breaks for the same event are rejected until the break appears in the manifest for the event.

Calls made to the EABN API must include the following information:

The identifier of the corresponding live stream to which the ad break is being created. This identifier can be one of the following:
The “Asset Key” of the live stream.
The “Custom Asset Key” of the live stream, which allows you to manage your own key space by specifying your own identifier string.
The “Content Source ID” and the “Content ID” of the live stream.

Note: You must be enabled to use this identifier type. For more information, contact your account manager.

The expected duration of the next ad break. The duration needs to be as close to the actual ad break length as possible.

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

In order to use the EABN API, you must create a service account and add the account to your Google Ad Manager network.

Creating a service account

To create a service account for calling the EABN API, complete the following steps: - If you have a Google Cloud account, 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, complete the following steps to create one from the Google API Console:

Create a new project or select an existing project.
In the Credentials page, click Manage service accounts.
In the Service accounts page, click CREATE SERVICE ACCOUNT.
In the Create Service account page, enter the account details. Then, click CREATE.

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

Adding your service account to your Google Ad Manager network

To add your service account to your network, complete the steps in Add a service account user for API access.

Enabling the API

Once you have created the service account, provide the following information to your account manager to enable the API for your account:

Your Google Cloud Account email address
Your service account
The Network Code of your Google Ad Manager Network.

After the API has been enabled by your account manager, complete the following steps to enable the API:

In the Google API library, search for “Google Ad Manager Video API”.
Click ENABLE.

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.

Using the API

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

Authorization

To make authorized 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.

You must include the resulting authorization 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 to one of the three valid EABN URLs, depending on how you prefer to specify the live stream. The following sections explain the differences between the URLs and provide request and response examples.

URLs

There are three valid URLs for early ad break notification. You can use all three types to create an ad break (POST) or get the list of assigned ad breaks (GET).

To use the asset key of a live stream, use:

POST admanagervideo.googleapis.com/v1/networks/{network_code}/assets/{asset_key}/adBreaks

GET admanagervideo.googleapis.com/v1/networks/{network_code}/assets/{asset_key}/adBreaks

To use the custom asset key of a live stream, use:

POST admanagervideo.googleapis.com/v1/networks/{network_code}/customAssets/{custom_asset_key}/adBreaks

GET admanagervideo.googleapis.com/v1/networks/{network_code}/customAssets/{custom_asset_key}/adBreaks

To use the Content Source ID and Content ID approach, use:

POST admanagervideo.googleapis.com/v1/networks/{network_code}/sources/{content_source_id}/content/{content_id}/adBreaks

GET admanagervideo.googleapis.com/v1/networks/{network_code}/sources/{content_source_id}/content/{content_id}/adBreaks

For all the parameters:

network_code represents the network code of your Google Ad Manager network.
asset_key represents the asset key shown in your live stream details page.
custom_asset_key represents the custom asset key of your live stream.
content_source_id represents the id of a content source in Google Ad Manager.
content_id represents the id of a piece of content in Google Ad Manager.

Note: The specified content_source_id/content_id pair must be associated with a live stream in Google Ad Manager.

Request body - only used to create an Ad Break (POST)

Object
`expectedDuration`	Required	The duration of this ad break, using Google’s standard duration format (xx.xxxs where xx.xxx is the number of seconds)
`customParams`	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.
`podTemplateName`	Optional	The ad pod template name
`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=`

Example requests

Create an Ad Break

POST admanagervideo.googleapis.com/v1/networks/.../sources/.../content/.../adBreaks
Content-Type: application/json
Authorization: Bearer …
{
    "expectedDuration": "30s",
    "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==",
    "customParams": "param1=value1&param2=value2",
    "podTemplateName": "podtemplate"
}

Response body

The response body contains all of the parameters sent in the adBreak object, as well as an additional name field, which contains the Google-wide standard ID of the created ad break. This field is returned in the following format:

networks/{network_code}/assets/{asset_key}/adBreaks/{ad_break_id}

Example response

HTTP/1.1 200 OK
{
  "name": "networks/.../assets/.../adBreaks/1",
  "expectedDuration": "30s",
  "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==",
  "customParams": "param1=value1&param2=value2",
  "podTemplateName": "podtemplate"
}

List assigned Ad Breaks

GET admanagervideo.googleapis.com/v1/networks/.../sources/.../content/.../adBreaks
Content-Type: application/json
Authorization: Bearer …

Response body

The response body contains the ad breaks with an additional breakState field for each ad break assigned to the stream. breakState field supports the following values:

 // Ad break decisioning has started.
BREAK_STATE_DECISIONED

// Break has started to be delivered to end users.
BREAK_STATE_COMPLETE

Example response

HTTP/1.1 200 OK
{
  "name": "networks/.../assets/.../adBreaks/1",
  "expectedDuration": "30s",
  "breakState": "BREAK_STATE_COMPLETE"
}