Early ad break notification v1
با مجموعه‌ها، منظم بمانید
ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.
- شناسه جریان مستقیم مربوطه که وقفه آگهی برای آن ایجاد می شود. این شناسه می تواند یکی از موارد زیر باشد:
- «کلید دارایی» پخش زنده.
- "کلید دارایی سفارشی" جریان زنده، که به شما امکان می دهد فضای کلید خود را با تعیین رشته شناسه خود مدیریت کنید.
- «شناسه منبع محتوا» و «شناسه محتوا» پخش زنده.
توجه: برای استفاده از این نوع شناسه باید فعال باشید. برای اطلاعات بیشتر، با مدیر حساب خود تماس بگیرید.
- مدت زمان مورد انتظار وقفه تبلیغاتی بعدی. مدت زمان باید تا حد امکان به مدت زمان استراحت واقعی تبلیغات نزدیک باشد.
علاوه بر این فیلدهای الزامی، می‌توانید پارامترهای هدف‌گیری سفارشی، نام قالب آگهی برای اعمال، یا داده‌های SCTE35 Cue Out را در صورت وجود ارسال کنید.
پیش نیازها
برای استفاده از EABN API، باید یک حساب سرویس ایجاد کنید و حساب را به شبکه Google Ad Manager خود اضافه کنید.
ایجاد یک حساب کاربری خدمات
برای ایجاد یک حساب سرویس برای تماس با EABN API، مراحل زیر را انجام دهید: - اگر یک حساب Google Cloud دارید، از ماژول IAM برای ایجاد یک حساب سرویس استفاده کنید. برای اطلاعات بیشتر، به ایجاد و مدیریت حساب‌های سرویس مراجعه کنید. - اگر حساب Google Cloud ندارید، مراحل زیر را برای ایجاد آن از Google API Console انجام دهید:
- یک پروژه جدید ایجاد کنید یا یک پروژه موجود را انتخاب کنید.
- در صفحه اعتبارنامه‌ها ، روی مدیریت حساب‌های سرویس کلیک کنید.
- در صفحه حساب‌های سرویس ، روی ایجاد حساب سرویس کلیک کنید.
- در صفحه ایجاد حساب کاربری ، جزئیات حساب را وارد کنید. سپس، روی CREATE کلیک کنید.
هنگامی که یک حساب سرویس ایجاد کردید، کلید JSON حساب را کپی کنید، که برای احراز هویت استفاده می شود.
فعال کردن API
پس از ایجاد حساب سرویس، اطلاعات زیر را در اختیار مدیر حساب خود قرار دهید تا API برای حساب شما فعال شود:
- آدرس ایمیل حساب Google Cloud شما
- حساب خدمات شما
- کد شبکه شبکه Google Ad Manager شما.
پس از اینکه API توسط مدیر حساب شما فعال شد، مراحل زیر را برای فعال کردن API انجام دهید:
- در کتابخانه Google API ، «Google Ad Manager Video API» را جستجو کنید.
- روی ENABLE کلیک کنید.
توجه: اگر API در نتایج جستجو ظاهر نشد، با مدیر حساب خود تماس بگیرید تا تأیید کنید که حساب شما برای DAI API فعال شده است.
با استفاده از API
می توانید با استفاده از درخواست های JSON/REST با EABN API تماس بگیرید.
مجوز
برای برقراری تماس‌های مجاز با EABN API، باید اعتبار حساب سرویس OAuth2 را با استفاده از کلید JSON از حساب سرویس خود و محدوده https://www.googleapis.com/auth/video-ads ایجاد کنید. برای اطلاعات بیشتر، استفاده از OAuth 2.0 برای برنامه های کاربردی سرور به سرور را ببینید.
برای هر تماس با EABN API باید کد مجوز حاصل را به عنوان سرصفحه Auth اضافه کنید.
برای ارسال زودهنگام اعلان وقفه تبلیغاتی، بسته به نحوه تعیین جریان زنده، یک درخواست POST به یکی از سه نشانی اینترنتی معتبر 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 Source ID و 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 مرتبط باشد.
بدنه درخواست - فقط برای ایجاد یک Ad Break (POST) استفاده می شود
| شیء |
expectedDuration | مورد نیاز | مدت زمان این وقفه تبلیغاتی، با استفاده از قالب مدت زمان استاندارد Google (xx.xxxs که xx.xxx تعداد ثانیه‌ها است) |
customParams | اختیاری | جفت‌های کلید-مقدار در درخواست‌های آگهی برای این وقفه برای هدف‌یابی معیارهای سفارشی در AM360، با تفکیک = و ملحق شدند & .
مثال:
key=value&key2=value2,value3
برای اطلاعات بیشتر در مورد هدف‌یابی، به تامین پارامترهای هدف‌گیری در جریان خود مراجعه کنید.
|
podTemplateName | اختیاری | نام قالب آگهی |
scte35CueOut | اختیاری | داده های کدگذاری شده با پایه 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 License است. نمونه کدها نیز دارای مجوز Apache 2.0 License است. برای اطلاع از جزئیات، به خطمشیهای سایت Google Developers مراجعه کنید. جاوا علامت تجاری ثبتشده 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 }"]]
