API درج آگهی پویا برای پخش جریانی زنده

Google DAI API به شما امکان می‌دهد جریان‌های دارای Google DAI را در محیط‌هایی پیاده‌سازی کنید که پیاده‌سازی IMA SDK پشتیبانی نمی‌شود. توصیه می کنیم همچنان از IMA در پلتفرم هایی که IMA SDK پشتیبانی می شود استفاده کنید.

توصیه می کنیم از DAI API در پلتفرم های زیر استفاده کنید:

  • تلویزیون هوشمند سامسونگ (تایزن)
  • تلویزیون ال جی
  • HbbTV
  • Xbox (برنامه های جاوا اسکریپت)
  • KaiOS

API از قابلیت های اساسی ارائه شده توسط IMA DAI SDK پشتیبانی می کند. برای سؤالات خاص در مورد سازگاری یا ویژگی های پشتیبانی شده، با مدیر حساب Google خود تماس بگیرید.

API DAI را برای جریان‌های زنده پیاده‌سازی کنید

DAI API از جریان های خطی (LIVE) با استفاده از پروتکل های HLS و DASH پشتیبانی می کند. مراحل توضیح داده شده در این راهنما برای هر دو پروتکل اعمال می شود.

برای ادغام API در برنامه خود برای پخش جریانی زنده، مراحل زیر را کامل کنید:

1. درخواست یک جریان

برای درخواست پخش زنده از API DAI، یک تماس POST با نقطه پایانی جریان برقرار کنید. پاسخ JSON حاوی مانیفست جریان و همچنین نقاط پایانی و مقادیر DAI API مرتبط است.

نمونه درخواست بدنه

https://dai.google.com/linear/v1/dash/event/0ndl1dJcRmKDUPxTRjvdog/stream

{
  key1 : "value1",
  stream_parameter1 : "value2"
}

نمونه بدن پاسخ 

{
"stream_id":"c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL",
"stream_manifest":"https://dai.google.com/linear/dash/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/manifest.mpd",
"media_verification_url":"https://dai.google.com/view/p/service/linear/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/loc/ATL/network/51636543/event/0ndl1dJcRmKDUPxTRjvdog/media/",
"metadata_url":"https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/metadata",
"session_update_url":"https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/session",
"polling_frequency":10
}

پاسخ خطا

در صورت بروز خطا، کدهای خطای استاندارد HTTP بدون بدنه پاسخ JSON برگردانده می شوند.

پاسخ JSON را تجزیه کنید و مقادیر زیر را ذخیره کنید:

stream_id
از این مقدار می توان برای شناسایی جریان برگشتی استفاده کرد.
stream_manifest
این URL برای پخش جریانی به پخش کننده رسانه شما ارسال می شود.
media_verification_url
این URL نقطه پایانی پایه برای ردیابی رویدادهای پخش است.
metadata_url
این نشانی وب برای نظرسنجی برای اطلاعات دوره‌ای درباره رویدادهای جریانی آتی استفاده می‌شود.
session_update_url
این URL برای به روز رسانی پارامترهای درخواست جریان ارسال شده در طول درخواست جریان اولیه استفاده می شود. توجه داشته باشید که پارامترهای این درخواست جایگزین تمام پارامترهای تنظیم شده برای جریان قبلی می شود.
polling_frequency
فرکانس، در ثانیه، هنگام درخواست متادیتا AdBreak به روز شده از API DAI.

2. نظرسنجی برای ابرداده جدید AdBreak

با استفاده از URL فراداده، یک تایمر برای نظرسنجی برای فراداده جدید AdBreak در فرکانس نظرسنجی تنظیم کنید. اگر در پاسخ جریان مشخص نشده باشد، فاصله پیشنهادی پیش‌فرض 10 ثانیه است.

نمونه بدنه درخواست 

https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/metadata

نمونه بدن پاسخ 

{
   "tags":{
      "google_0492266569":{
         "ad":"0000229836_ad1",
         "ad_break_id":"0000229836",
         "type":"firstquartile"
      },
      "google_1560331148":{
         "ad":"0000229836_ad1",
         "ad_break_id":"0000229836",
         "type":"thirdquartile"
      },
      "google_1877686714378797835":{
         "ad":"0000229836_slate",
         "ad_break_id":"0000229836",
         "type":"progress"
      },
      "google_1vRyQBYPw_7Gg3MrZ6S5EjmV9aLje-YpW8QHed1DSlU":{
         "ad":"0000229835_ad1",
         "ad_break_id":"0000229835",
         "type":"progress"
      },
      "google_2032765498":{
         "ad":"0000229835_ad1",
         "ad_break_id":"0000229835",
         "type":"midpoint"
      },......
      "google_5646900623":{
         "ad":"0000229837_ad1",
         "ad_break_id":"0000229837",
         "type":"complete"
      }
   },
   "ads":{
      "0000229834_ad1":{
         "ad_break_id":"0000229834",
         "position":1,
         "duration":15.01,
         "title":"truman-e2e-creativeset4",
         "description":"truman-e2e-creativeset4 ad",
         "ad_system":"GDFP",
         "ad_id":"39066884",
         "creative_id":"58092079124",
         "clickthrough_url":"https://pubads.g.doubleclick.net/pcs/click?xai=AKAO...\u0026adurl=http://google.com",
         "universal_ad_id":{
            "id_value":"58092079124",
            "id_registry":"GDFP"
         }
      },
      "0000229834_slate":{
         "ad_break_id":"0000229834",
         "position":-1,
         "duration":14.974977777,
         "slate":true
      },...
   },
   "ad_breaks":{
      "0000229834":{
         "type":"mid",
         "duration":15.01,
         "expected_duration":29.984977776999997,
         "ads":1
      },....
   }
}

3. به رویدادهای ID3 گوش دهید و رویدادهای پخش را دنبال کنید

برای تأیید اینکه رویدادهای خاصی در یک جریان ویدیویی رخ داده است، این مراحل را برای مدیریت رویدادهای ID3 دنبال کنید:

  1. رویدادهای رسانه را در یک صف ذخیره کنید و هر شناسه رسانه را به همراه مهر زمانی آن ذخیره کنید (اگر توسط پخش کننده ظاهر شود).
  2. در هر به‌روزرسانی زمانی از پخش‌کننده، یا در یک فرکانس تعیین‌شده (500 میلی‌ثانیه توصیه می‌شود)، صف رویدادهای رسانه‌ای را برای رویدادهایی که اخیراً پخش شده‌اند، با مقایسه مهرهای زمانی رویداد با هد پخش بررسی کنید.
  3. برای رویدادهای رسانه‌ای که تأیید می‌کنید پخش شده‌اند، با جستجوی شناسه رسانه در برچسب‌های ذخیره‌شده استراحت، نوع آن را بررسی کنید. به خاطر داشته باشید که تگ های ذخیره شده فقط حاوی پیشوندی از شناسه رسانه هستند، بنابراین تطبیق دقیق آن ممکن نیست.
  4. از رویدادهای "پیشرفت" برای پیگیری اینکه آیا کاربر در یک وقفه تبلیغاتی است یا خیر استفاده کنید. این رویدادها را به نقطه پایانی تأیید رسانه ارسال نکنید. برای سایر انواع رویداد، شناسه رسانه را به نقطه پایانی تأیید رسانه اضافه کنید و برای ردیابی پخش درخواست GET کنید.
  5. رویداد رسانه ای را از صف حذف کنید.

نمونه بدنه درخواست 

https://dai.google.com/view/p/service/linear/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/loc/ATL/network/51636543/event/0ndl1dJcRmKDUPxTRjvdog/media/

نمونه پاسخ ها

Accepted for asynchronous verification - HTTP/1.1 202 Accepted
Successful empty response - HTTP/1.1 204 No Content
Media verification not found - HTTP/1.1 404 Not Found
Media verification sent by someone else - HTTP/1.1 409 Conflict

می‌توانید ردیابی رویدادها را در Stream Activity Monitor تأیید کنید.

4. پارامترهای جلسه پخش زنده را به روز کنید

ممکن است بخواهید پس از ایجاد یک جریان، پارامترهای جلسه خود را تنظیم کنید. برای انجام این کار، یک درخواست به آدرس به روز رسانی جلسه ارسال کنید.

نمونه درخواست بدنه 

https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/session

{
  key1 : "value1",
  stream_parameter1 : "value2"
}

نمونه بدن پاسخ 

Successful response would be to look for - HTTP/1.1 200

محدودیت ها

در صورت استفاده از API در وب‌نماها، محدودیت‌های زیر در مورد هدف‌گذاری اعمال می‌شود:

  • UserAgent: پارامتر عامل کاربر به‌جای پلتفرم زیربنایی، به‌عنوان مقدار خاص مرورگر ارسال می‌شود.
  • rdid , idtype , is_lat : شناسه دستگاه به درستی ارسال نشده است که قابلیت های ویژگی های زیر را محدود می کند:
    • محدودیت فرکانس
    • چرخش متوالی تبلیغات
    • تقسیم بندی و هدف گذاری مخاطب

بهترین شیوه ها

به خاطر داشته باشید که نقطه پایانی فراداده برای نمایه های پخش زنده بر اساس پیشوند تگ ID3 مربوطه است. این طراحی برای جلوگیری از استفاده از نقطه پایانی فراداده برای پینگ فوری تمام گره های تأیید است.

منابع اضافی