Early ad break notification v1
קל לארגן דפים בעזרת אוספים
אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.
- המזהה של שידור החי התואם שאליו נוצרת ההפסקה למודעה. המזהה הזה יכול להיות אחד מהערכים הבאים:
- 'מפתח הנכס' של השידור החי.
- 'מפתח נכס מותאם אישית' של השידור החי, שמאפשר לכם לנהל את מרחב המפתחות שלכם על ידי ציון מחרוזת מזהה משלכם.
- 'מזהה מקור התוכן' ו'מזהה התוכן' של השידור החי.
הערה: צריך להיות לכם הרשאה להשתמש בסוג המזהה הזה. למידע נוסף, אפשר לפנות למנהל החשבון.
- משך הזמן הצפוי של ההפסקה הבאה למודעה. משך ההפסקה צריך להיות קרוב ככל האפשר למשך ההפסקה בפועל למודעה.
בנוסף לשדות הנדרשים האלה, אפשר גם לשלוח פרמטרים מותאמים אישית לטירגוט, את השם של תבנית של רצף מודעות שתחול או נתוני סיום של SCTE35, אם הם זמינים.
דרישות מוקדמות
כדי להשתמש ב-EABN API, צריך ליצור חשבון שירות ולהוסיף את החשבון לרשת שלכם ב-Google Ad Manager.
יצירת חשבון שירות
כדי ליצור חשבון שירות לקריאה ל-EABN API, מבצעים את השלבים הבאים: - אם יש לכם חשבון Google Cloud, אתם יכולים להשתמש במודול IAM כדי ליצור חשבון שירות. למידע נוסף, קראו את המאמר יצירה וניהול של חשבונות שירות. - אם אין לכם חשבון Google Cloud, עליכם לפעול לפי השלבים הבאים כדי ליצור חשבון דרך מסוף Google API:
- יוצרים פרויקט חדש או בוחרים פרויקט קיים.
- בדף Credentials, לוחצים על Manage service accounts.
- בדף Service accounts, לוחצים על CREATE SERVICE ACCOUNT.
- בדף Create Service account, מזינים את פרטי החשבון. לאחר מכן, לוחצים על יצירה.
אחרי שיוצרים חשבון שירות, מעתיקים את מפתח ה-JSON של החשבון, שמשמש לאימות.
הפעלת ה-API
אחרי שיוצרים את חשבון השירות, צריך לספק למנהל החשבון את הפרטים הבאים כדי להפעיל את ה-API בחשבון:
- כתובת האימייל של חשבון Google Cloud
- חשבון השירות שלכם
- קוד הרשת של הרשת שלכם ב-Google Ad Manager.
אחרי שמנהל החשבון מפעיל את ה-API, מבצעים את השלבים הבאים כדי להפעיל אותו:
- בספריית Google API, מחפשים את 'Google Ad Manager Video API'.
- לוחצים על ENABLE.
הערה: אם ה-API לא מופיע בתוצאות החיפוש, פנו למנהל החשבון כדי לוודא שהחשבון שלכם הופעל ל-DAI API.
שימוש ב-API
אפשר לקרוא ל-EABN API באמצעות בקשות JSON/REST.
אישור
כדי לבצע קריאות מורשות ל-EABN API, צריך ליצור פרטי כניסה לחשבון שירות של OAuth2 באמצעות מפתח ה-JSON מחשבון השירות וההיקף https://www.googleapis.com/auth/video-ads. למידע נוסף, ראו שימוש ב-OAuth 2.0 לאפליקציות שרת-אל-שרת.
צריך לכלול את אסימון ההרשאה שנוצר ככותרת Auth בכל קריאה ל-EABN API.
כדי לשלוח התראה על הפסקה מוקדמת למודעה, שולחים בקשת POST לאחת משלוש כתובות ה-URL התקפות של EABN, בהתאם לאופן שבו רוצים לציין את השידור החי. בקטעים הבאים מוסבר על ההבדלים בין כתובות ה-URL, ומפורטות דוגמאות לבקשות ולתשובות.
כתובות URL
יש שלוש כתובות URL תקינות לקבלת התראה על הפסקה מוקדמת למודעה. אפשר להשתמש בכל שלושת הסוגים כדי ליצור הפסקה למודעה (POST) או לקבל את רשימת ההפסקות למודעות שהוקצו (GET).
כדי להשתמש במפתח הנכס של שידור חי, צריך להשתמש ב-:
POST admanagervideo.googleapis.com/v1/networks/{network_code}/assets/{asset_key}/adBreaks
GET admanagervideo.googleapis.com/v1/networks/{network_code}/assets/{asset_key}/adBreaks
כדי להשתמש במפתח הנכס המותאם אישית של שידור חי, צריך להשתמש ב-:
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
כדי להשתמש במזהה של מקור התוכן ובגישה של Content ID, צריך להשתמש באפשרויות הבאות:
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
לכל הפרמטרים:
network_code מייצג את קוד הרשת של הרשת ב-Google Ad Manager.asset_key מייצג את מפתח הנכס שמוצג בדף הפרטים של השידור החי.custom_asset_key מייצג את מפתח הנכס המותאם אישית של השידור החי.- השדה
content_source_id מייצג את המזהה של מקור תוכן ב-Google Ad Manager.
content_id מייצג את המזהה של קטע תוכן ב-Google Ad Manager.
הערה: הצמד content_source_id/content_id שצוין צריך להיות משויך לשידור חי ב-Google Ad Manager.
גוף הבקשה – משמש רק ליצירת הפסקה למודעה (POST)
| אובייקט |
|---|
|
expectedDuration
| חובה | משך ההפסקה למודעה, לפי הפורמט הסטנדרטי של Google למשך זמן (xx.xxx שניות, כאשר xx.xxx הוא מספר השניות) |
|
customParams
| אופציונלי | צמדי מפתח/ערך שכלולים בבקשות להצגת מודעות להפסקה הזו לטירגוט לפי קריטריונים מותאמים אישית ב-AM360, מופרדים באמצעות
=
וגם הצטרפו אליה
&
.
דוגמה:
key=value&key2=value2,value3
מידע נוסף על טירגוט זמין במאמר הוספת פרמטרים של טירגוט לשידור.
|
|
podTemplateName
| אופציונלי | שם התבנית של רצף המודעות |
|
scte35CueOut
| אופציונלי | נתונים בקידוד Base64 מהאות לסיום של scte35. יכולים לכלול את
splice_insert()
או
time_signal()
פקודה.
דוגמאות: |
דוגמאות לבקשות
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¶m2=value2",
"podTemplateName": "podtemplate"
}
גוף התשובה
גוף התשובה מכיל את כל הפרמטרים שנשלחו באובייקט adBreak, וגם שדה name נוסף שמכיל את המזהה הסטנדרטי של ההפסקה למודעה שנוצרה ברמת Google. השדה הזה מוחזר בפורמט הבא:
networks/{network_code}/assets/{asset_key}/adBreaks/{ad_break_id}
דוגמה לתשובה
HTTP/1.1 200 OK
{
"name": "networks/.../assets/.../adBreaks/1",
"expectedDuration": "30s",
"scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==",
"customParams": "param1=value1¶m2=value2",
"podTemplateName": "podtemplate"
}
GET admanagervideo.googleapis.com/v1/networks/.../sources/.../content/.../adBreaks
Content-Type: application/json
Authorization: Bearer …
גוף התשובה
גוף התגובה מכיל את ההפסקות למודעות עם שדה breakState נוסף לכל הפסקה למודעה שהוקצתה לשידור. השדה breakState תומך בערכים הבאים:
// Ad break decisioning has started.
BREAK_STATE_DECISIONED
// Break has started to be delivered to end users.
BREAK_STATE_COMPLETE
דוגמה לתשובה
HTTP/1.1 200 OK
{
"name": "networks/.../assets/.../adBreaks/1",
"expectedDuration": "30s",
"breakState": "BREAK_STATE_COMPLETE"
}
אלא אם צוין אחרת, התוכן של דף זה הוא ברישיון Creative Commons Attribution 4.0 ודוגמאות הקוד הן ברישיון Apache 2.0. לפרטים, ניתן לעיין במדיניות האתר Google Developers. Java הוא סימן מסחרי רשום של חברת Oracle ו/או של השותפים העצמאיים שלה.
עדכון אחרון: 2025-08-21 (שעון UTC).
[null,null,["עדכון אחרון: 2025-08-21 (שעון UTC)."],[[["\u003cp\u003eThe Early Ad Break Notification (EABN) API enables you to inform Google Ad Manager about upcoming ad breaks in live streams, including metadata, up to an hour in advance.\u003c/p\u003e\n"],["\u003cp\u003eTo use the EABN API, you must create a service account, add it to your Google Ad Manager network, and have the API enabled by your account manager.\u003c/p\u003e\n"],["\u003cp\u003eThe API requires the live stream identifier (asset key, custom asset key, or content source ID with content ID) and the expected ad break duration.\u003c/p\u003e\n"],["\u003cp\u003eYou can optionally include custom targeting parameters, an ad pod template name, and SCTE35 Cue Out data with your EABN requests.\u003c/p\u003e\n"],["\u003cp\u003eEABN requests are immutable, and subsequent requests for the same event are rejected until the break appears in the event's manifest.\u003c/p\u003e\n"]]],[],null,["# Early ad break notification v1\n\nUsing the Early Ad Break Notification API\n-----------------------------------------\n\n- The identifier of the corresponding live stream to which the ad break is being created. This identifier can be one of the following:\n- The \"Asset Key\" of the live stream.\n- The \"Custom Asset Key\" of the live stream, which allows you to manage your own key space by specifying your own identifier string.\n- The \"Content Source ID\" and the \"Content ID\" of the live stream.\n\nNote: You must be enabled to use this identifier type. For more information, contact your account manager.\n\n- The expected duration of the next ad break. The duration needs to be as close to the actual ad break length as possible.\n\nIn 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.\n\n### Prerequisites\n\nIn order to use the EABN API, you must create a service account and add the account to your Google Ad Manager network.\n\n#### Creating a service account\n\nTo 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](//cloud.google.com/iam/docs/creating-managing-service-accounts). - If you do not have a Google Cloud account, complete the following steps to create one from the [Google API Console](//console.developers.google.com/apis/credentials/):\n\n1. Create a new project or select an existing project.\n2. In the **Credentials** page, click **Manage service accounts**.\n3. In the **Service accounts** page, click **CREATE SERVICE ACCOUNT**.\n4. In the **Create Service account** page, enter the account details. Then, click **CREATE**.\n\nOnce you have created a service account, copy the account's JSON key, which is used for authentication.\n\n#### Adding your service account to your Google Ad Manager network\n\nTo add your service account to your network, complete the steps in [Add a service account user for API access](//support.google.com/admanager/answer/6078734).\n\n### Enabling the API\n\nOnce you have created the service account, provide the following information to your account manager to enable the API for your account:\n\n- Your Google Cloud Account email address\n- Your service account\n- The Network Code of your Google Ad Manager Network.\n\nAfter the API has been enabled by your account manager, complete the following steps to enable the API:\n\n1. In the [Google API library](//console.developers.google.com/apis/library), search for \"Google Ad Manager Video API\".\n2. Click **ENABLE**.\n\nNote: 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.\n\n### Using the API\n\nYou can call the EABN API using JSON/REST requests.\n\n#### Authorization\n\nTo 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](https://developers.google.com/identity/protocols/oauth2/service-account).\n\nYou must include the resulting authorization token as an Auth header for each call to the EABN API.\n\n#### Sending an early ad break notification\n\nTo 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.\n\n##### URLs\n\nThere 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`).\n\nTo use the asset key of a live stream, use: \n\n POST admanagervideo.googleapis.com/v1/networks/{network_code}/assets/{asset_key}/adBreaks\n\n GET admanagervideo.googleapis.com/v1/networks/{network_code}/assets/{asset_key}/adBreaks\n\nTo use the custom asset key of a live stream, use: \n\n POST admanagervideo.googleapis.com/v1/networks/{network_code}/customAssets/{custom_asset_key}/adBreaks\n\n GET admanagervideo.googleapis.com/v1/networks/{network_code}/customAssets/{custom_asset_key}/adBreaks\n\nTo use the Content Source ID and Content ID approach, use: \n\n POST admanagervideo.googleapis.com/v1/networks/{network_code}/sources/{content_source_id}/content/{content_id}/adBreaks\n\n GET admanagervideo.googleapis.com/v1/networks/{network_code}/sources/{content_source_id}/content/{content_id}/adBreaks\n\nFor all the parameters:\n\n- `network_code` represents the network code of your Google Ad Manager network.\n- `asset_key` represents the asset key shown in your live stream details page.\n- `custom_asset_key` represents the custom asset key of your live stream.\n- `content_source_id` represents the id of a content source in Google Ad Manager.\n- `content_id` represents the id of a piece of content in Google Ad Manager.\n\nNote: The specified `content_source_id`/`content_id` pair must be associated with a live stream in Google Ad Manager.\n\n##### Request body - only used to create an Ad Break (POST)\n\n\u003cbr /\u003e\n\n| Object |||\n| \u003cbr /\u003e `expectedDuration` \u003cbr /\u003e | Required | The duration of this ad break, using Google's standard duration format (xx.xxxs where xx.xxx is the number of seconds) |\n| \u003cbr /\u003e `customParams` \u003cbr /\u003e | Optional | Key-value pairs to be included on ad requests for this break for custom criteria targeting in AM360, separated by \u003cbr /\u003e `=` and joined by `&` . Example: `key=value&key2=value2,value3` \u003cbr /\u003e For more information on targeting, see [Supply targeting parameters to your stream](//support.google.com/admanager/answer/7320899). |\n| \u003cbr /\u003e `podTemplateName` \u003cbr /\u003e | Optional | The ad pod template name |\n| \u003cbr /\u003e `scte35CueOut` \u003cbr /\u003e | Optional | Base-64-encoded data from the scte35 cue out. Can include the \u003cbr /\u003e `splice_insert()` or `time_signal()` command. Examples: - time_signal(): \u003cbr /\u003e `/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==` \u003cbr /\u003e - splice_insert(): \u003cbr /\u003e `/DAvAAAAAAAA///wFAVIAACPf+/+c2nALv4AUsz1AAAAAAAKAAhDVUVJAAABNWLbowo=` \u003cbr /\u003e |\n|----------------------------------|----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n\n\u003cbr /\u003e\n\n### Example requests\n\n##### Create an Ad Break\n\n POST admanagervideo.googleapis.com/v1/networks/.../sources/.../content/.../adBreaks\n Content-Type: application/json\n Authorization: Bearer ...\n {\n \"expectedDuration\": \"30s\",\n \"scte35CueOut\": \"/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==\",\n \"customParams\": \"param1=value1¶m2=value2\",\n \"podTemplateName\": \"podtemplate\"\n }\n\n###### Response body\n\nThe 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: \n\n networks/{network_code}/assets/{asset_key}/adBreaks/{ad_break_id}\n\n###### Example response\n\n HTTP/1.1 200 OK\n {\n \"name\": \"networks/.../assets/.../adBreaks/1\",\n \"expectedDuration\": \"30s\",\n \"scte35CueOut\": \"/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==\",\n \"customParams\": \"param1=value1¶m2=value2\",\n \"podTemplateName\": \"podtemplate\"\n }\n\n##### List assigned Ad Breaks\n\n GET admanagervideo.googleapis.com/v1/networks/.../sources/.../content/.../adBreaks\n Content-Type: application/json\n Authorization: Bearer ...\n\n###### Response body\n\nThe 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: \n\n // Ad break decisioning has started.\n BREAK_STATE_DECISIONED\n\n // Break has started to be delivered to end users.\n BREAK_STATE_COMPLETE\n\n###### Example response\n\n HTTP/1.1 200 OK\n {\n \"name\": \"networks/.../assets/.../adBreaks/1\",\n \"expectedDuration\": \"30s\",\n \"breakState\": \"BREAK_STATE_COMPLETE\"\n }"]]
