Early ad break notification v1
تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
- معرّف البث المباشر المقابل الذي يتم إنشاء الفاصل الإعلاني له. يمكن أن يكون هذا المعرّف أحد العناصر التالية:
- "مفتاح مادة العرض" للبث المباشر
- "مفتاح مادة العرض المخصّص" للبث المباشر، والذي يتيح لك إدارة مساحة المفاتيح الخاصة بك من خلال تحديد سلسلة المعرّف الخاصة بك.
- "رقم تعريف مصدر المحتوى" و"رقم تعريف المحتوى" للبث المباشر
ملاحظة: يجب أن تكون مفعّلاً لاستخدام نوع المعرّف هذا. لمزيد من المعلومات، يُرجى التواصل مع مدير حسابك.
- المدة المتوقّعة للفاصل الإعلاني التالي. يجب أن تكون المدة قريبة من مدة الفاصل الإعلاني الفعلية قدر الإمكان.
بالإضافة إلى هذه الحقول المطلوبة، يمكنك أيضًا إرسال مَعلمات استهداف مخصّصة أو اسم نموذج مجموعة إعلانية متسلسلة لتطبيقه أو بيانات وقت الانتهاء وفقًا لمعيار SCTE35، إذا كانت متاحة.
المتطلبات الأساسية
لاستخدام واجهة برمجة التطبيقات EABN API، عليك إنشاء حساب خدمة وإضافته إلى شبكتك على "مدير إعلانات Google".
إنشاء حساب خدمة
لإنشاء حساب خدمة لاستدعاء واجهة برمجة التطبيقات EABN API، أكمِل الخطوات التالية: - إذا كان لديك حساب على Google Cloud، استخدِم وحدة إدارة الهوية وإمكانية الوصول (IAM) لإنشاء حساب خدمة. لمزيد من المعلومات، يُرجى الاطّلاع على إنشاء حسابات الخدمة وإدارتها. - إذا لم يكن لديك حساب على Google Cloud، أكمِل الخطوات التالية لإنشاء حساب من Google API Console:
- أنشئ مشروعًا جديدًا أو اختَر مشروعًا حاليًا.
- في صفحة بيانات الاعتماد، انقر على إدارة حسابات الخدمة.
- في صفحة حسابات الخدمة، انقر على إنشاء حساب خدمة.
- في صفحة إنشاء حساب خدمة، أدخِل تفاصيل الحساب. بعد ذلك، انقر على إنشاء.
بعد إنشاء حساب خدمة، انسخ مفتاح JSON للحساب الذي يُستخدَم للمصادقة.
تفعيل واجهة برمجة التطبيقات
بعد إنشاء حساب الخدمة، قدِّم المعلومات التالية إلى مدير حسابك لتفعيل واجهة برمجة التطبيقات لحسابك:
- عنوان البريد الإلكتروني لحسابك على Google Cloud
- حساب الخدمة
- رمز الشبكة لشبكة "مدير إعلانات Google".
بعد أن يفعّل مدير حسابك واجهة برمجة التطبيقات، يُرجى إكمال الخطوات التالية لتفعيلها:
- في مكتبة Google API، ابحث عن "Google Ad Manager Video API".
- انقر على تفعيل.
ملاحظة: إذا لم تظهر واجهة برمجة التطبيقات في نتائج البحث، يُرجى التواصل مع مدير حسابك للتأكّد من أنّه تم تفعيل واجهة برمجة التطبيقات DAI 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".
- يمثّل الرمز
asset_key مفتاح مادة العرض المعروض في صفحة تفاصيل البث المباشر.
- يمثّل
custom_asset_key مفتاح مادة العرض المخصّصة لبثك المباشر.
- يمثّل
content_source_id رقم تعريف مصدر محتوى في "مدير إعلانات Google".
- يمثّل
content_id رقم تعريف قطعة محتوى في "مدير إعلانات Google".
ملاحظة: يجب أن يكون الزوج content_source_id/content_id المحدّد مرتبطًا ببث مباشر في "مدير إعلانات Google".
محتوى الطلب: يُستخدَم فقط لإنشاء فاصل إعلاني (POST)
| عنصر |
|---|
|
expectedDuration
| مطلوب | مدة هذا الفاصل الإعلاني، باستخدام تنسيق المدة العادي من Google (xx.xxx ثانية حيث xx.xxx هو عدد الثواني) |
|
customParams
| اختياري | أزواج المفتاح/القيمة التي سيتم تضمينها في طلبات الإعلانات لهذا الفاصل لاستهداف المعايير المخصّصة في "مدير إعلانات شبكة البحث 360"، مفصولة بـ
=
انضم إليهم
&
مثال:
key=value&key2=value2,value3
لمزيد من المعلومات عن الاستهداف، اطّلِع على مقالة إرسال مَعلمات الاستهداف إلى البث.
|
|
podTemplateName
| اختياري | اسم نموذج مجموعة الإعلانات |
|
scte35CueOut
| اختياري | بيانات بترميز Base-64 من إشارة الخروج 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 (حسب التوقيت العالمي المتفَّق عليه)
[null,null,["تاريخ التعديل الأخير: 2025-08-21 (حسب التوقيت العالمي المتفَّق عليه)"],[[["\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 }"]]
