DAI Early Ad Break Notification API

هنگام استفاده از پلتفرم Google DAI، ممکن است بخواهید داده های هدفمندی را برای وقفه تبلیغاتی زنده/خطی بعدی در یک جریان ارائه دهید. Early Ad Break Notification (EABN) API به شما اجازه می دهد تا با استفاده از جفت های کلید-مقدار، هدف گذاری مخصوص شکست را پیاده سازی کنید، که مقیاس پذیری را برای تصمیم گیری تبلیغات در جریان های با حجم بالا فراهم می کند.

تماس‌های برقرار شده با EABN API باید شامل کلید دارایی برای هدف و مدت زمان مورد انتظار استراحت بعدی باشد. مدت زمان باید تا حد امکان به مدت زمان استراحت واقعی تبلیغات نزدیک باشد. اگر مدت زمان مورد انتظار ارسال شده کوتاهتر از وقفه آگهی ارائه شده باشد، از نوع پر کردن استراحت آگهی Underfill (پیش‌فرض به صفحه خالی) برای باقیمانده وقفه استفاده می‌شود. اگر مدت زمان مورد انتظار ارسال بیشتر از وقفه تبلیغاتی ارائه شده باشد، ممکن است وقفه تبلیغاتی شما قبل از تکمیل آگهی به پایان برسد.

علاوه بر این فیلدهای الزامی، می‌توانید پارامترهای هدف‌گیری سفارشی، نام قالب آگهی برای اعمال، یا داده‌های SCTE35 Cue Out را در صورت وجود ارسال کنید.

پیش نیازها

یک حساب کاربری ایجاد کنید

برای دسترسی به EABN API، به یک حساب سرویس Google نیاز دارید.

  • اگر یک حساب Google Cloud دارید، می توانید از ماژول IAM برای ایجاد یک حساب سرویس استفاده کنید. برای اطلاعات بیشتر، به ایجاد و مدیریت حساب‌های سرویس مراجعه کنید.
  • اگر حساب Google Cloud ندارید، می‌توانید با دنبال کردن این مراحل، یک حساب سرویس از کنسول API Google ایجاد کنید:
    1. یک پروژه جدید ایجاد کنید یا یک پروژه موجود را انتخاب کنید.
    2. در صفحه اعتبارنامه‌ها ، روی مدیریت حساب‌های سرویس کلیک کنید.
    3. در صفحه حساب‌های سرویس ، روی ایجاد حساب سرویس کلیک کنید.
    4. در صفحه ایجاد حساب سرویس ، جزئیات حساب را وارد کنید. سپس روی CREATE کلیک کنید.

هنگامی که با موفقیت یک حساب سرویس ایجاد کردید، کلید JSON حساب را کپی کنید، که برای احراز هویت استفاده می شود.

EABN API را فعال کنید

هنگامی که حساب سرویس شما ایجاد شد، از مدیر حساب خود بخواهید که EABN API را برای آن حساب فعال کند.

DAI API را فعال کنید

هنگامی که EABN API برای حساب سرویس شما فعال شد، API DAI را در حساب فعال کنید:

  1. در کتابخانه Google API ، «DAI API» را جستجو کنید.

  2. DAI API را انتخاب و فعال کنید.

با استفاده از EABN API

می توانید با استفاده از درخواست های JSON/REST با EABN API تماس بگیرید.

احراز هویت

برای برقراری تماس‌های احراز هویت شده با EABN API، باید اعتبار حساب سرویس OAuth2 را با استفاده از کلید JSON از حساب سرویس خود و محدوده https://www.googleapis.com/auth/video-ads ایجاد کنید. برای اطلاعات بیشتر، استفاده از OAuth 2.0 برای برنامه های کاربردی سرور به سرور را ببینید.

برای هر تماس با EABN API باید توکن احراز هویت حاصل را به عنوان سرصفحه Auth شامل شود.

ارسال اعلان وقفه تبلیغاتی زودهنگام

برای ارسال زودهنگام اعلان وقفه تبلیغاتی، یک درخواست POST با استفاده از URL و بدنه درخواست زیر ارسال کنید:

POST dai.googleapis.com/v1/adBreaks

درخواست بدن

شیء
adBreak مورد نیاز شی wrapper برای ویژگی های adBreak
assetKey مورد نیاز یک شناسه منحصر به فرد برای LiveStreamEvent که برای آن استراحت ایجاد شده است
expectedDuration مورد نیاز مدت زمان این وقفه تبلیغاتی، با استفاده از قالب مدت زمان استاندارد Google (xx.xxxs که xx.xxx تعداد ثانیه‌ها است)
scte35CueOut اختیاری داده های کدگذاری شده با پایه 64 از نشانه scte35. می تواند شامل دستور splice_insert() یا time_signal() باشد.
مثال ها:
  • time_signal() :
    /DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==
  • splice_insert() : /DAvAAAAAAAA///wFAVIAACPf+/+c2nALv4AUsz1AAAAAAAKAAhDVUVJAAABNWLbowo=
custParams اختیاری جفت‌های کلید-مقدار در درخواست‌های آگهی برای این وقفه برای هدف‌یابی معیارهای سفارشی در AM360 گنجانده می‌شوند که با = جدا شده و با & پیوست می‌شوند.
مثال:
key=value&key2=value2,value3
برای اطلاعات بیشتر در مورد هدف‌یابی، به تامین پارامترهای هدف‌گیری در جریان خود مراجعه کنید.
ptpln اختیاری نام قالب آگهی

سربرگ پاسخ 

HTTP/1.1 200 OK

بدن پاسخگو

بدنه پاسخ شامل تمام پارامترهای ارسال شده در شی adBreak و همچنین یک فیلد daiBreakId اضافی است که حاوی شناسه داخلی DAI برای وقفه تبلیغاتی ایجاد شده در جریان است.

مثال

درخواست کنید 

POST /v1/adBreaks HTTP/1.1
Content-Type: application/json

{
  "adBreak": {
    "assetKey": "asset1",
    "expectedDuration": "30s",
    "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==",
    "custParams": "param1=value1&param2=value2",
    "ptpln": "podtemplate"
  }
}

پاسخ 

HTTP/1.1 200 OK

{
  "assetKey": "asset1",
  "expectedDuration": "30s",
  "custParams": "param1=value1&param2=value2",
  "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==",
  "ptpln": "podtemplate",
  "daiBreakId": 1
}

اجرای نمونه (پایتون) 

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&param2=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)