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:
- 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 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”.
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:
|
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¶m2=value2",
"ptpln": "podtemplate"
}
}
Response
HTTP/1.1 200 OK
{
"assetKey": "asset1",
"expectedDuration": "30s",
"custParams": "param1=value1¶m2=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¶m2=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)