DAI API در نسخه بتا است و ممکن است در شبکه شما در دسترس نباشد. برای اطلاعات بیشتر با مدیر حساب خود تماس بگیرید. IMA SDK برای پلتفرم هایی که در دسترس است توصیه می شود.

این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

مدیریت پخش‌های زنده DAI، مدیریت پخش‌های زنده DAI، مدیریت پخش‌های زنده DAI، مدیریت پخش‌های زنده DAI

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

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

تلویزیون هوشمند سامسونگ (تایزن)
تلویزیون ال جی
اچ‌بی‌تی‌وی
ایکس‌باکس (اپلیکیشن‌های جاوااسکریپت)
کای او اس

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

پیاده‌سازی API DAI برای پخش زنده

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

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

۱. درخواست پخش زنده

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

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

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

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

نمونه متن پاسخ

{
"stream_id":"c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS",
"stream_manifest":"https://dai.google.com/linear/dash/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/manifest.mpd",
"media_verification_url":"https://dai.google.com/view/p/service/linear/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/loc/ATL/network/51636543/event/0ndl1dJcRmKDUPxTRjvdog/media/",
"metadata_url":"https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/metadata",
"session_update_url":"https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/session",
"polling_frequency":10
}

پاسخ خطا

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

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

شناسه جریان: از این مقدار می‌توان برای شناسایی جریان برگشتی استفاده کرد.
stream_manifest: این URL برای پخش جریانی به پخش‌کننده رسانه شما منتقل می‌شود.
آدرس اینترنتی تایید رسانه: این URL نقطه پایانی پایه برای ردیابی رویدادهای پخش است.
آدرس اینترنتی (url): این نشانی اینترنتی برای نظرسنجی و کسب اطلاعات دوره‌ای در مورد رویدادهای پخش زنده آینده استفاده می‌شود.
آدرس اینترنتی به‌روزرسانی جلسه: این URL برای به‌روزرسانی پارامترهای درخواست جریان ارسال‌شده در طول درخواست اولیه جریان استفاده می‌شود. توجه داشته باشید که پارامترهای این درخواست جایگزین تمام پارامترهای تنظیم‌شده برای جریان قبلی می‌شوند.
فرکانس نظرسنجی: تعداد دفعات، بر حسب ثانیه، هنگام درخواست به‌روزرسانی فراداده AdBreak از API DAI.

۲. نظرسنجی برای فراداده‌های جدید AdBreak

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

برای بهینه سازی پهنای باند، موارد زیر را انجام دهید:

یک درخواست اولیه GET به نقطه پایانی metadata_url ارسال کنید.
- پارامتر کوئری delta_token حذف کنید. این فرآیند به سرور اجازه می‌دهد تا فراداده کامل مربوط به پنجره ضبط‌کننده ویدیوی دیجیتال (DVR) مربوط به پخش زنده را برگرداند. پنجره DVR شامل بازه زمانی پخش موجود برای بیننده جهت عقب و جلو بردن و پخش مجدد است. پاسخ شامل یک فیلد شیء next_delta_token است.
ذخیره ابرداده در سمت کلاینت.
فراخوانی‌های بعدی را با استفاده از مقدار next_delta_token که جدیدترین پاسخ برمی‌گرداند، انجام دهید. هر پاسخ شامل یک مقدار next_delta_token است. همیشه آخرین مقداری را که دریافت می‌کنید، ارسال کنید.
برای ادغام تغییرات و حذف تبلیغات موقت منسوخ شده، متادیتای ذخیره شده را به‌روزرسانی کنید.

سعی نکنید توکن دلتا را تجزیه، ساخت یا تغییر دهید. قالب توکن می‌تواند تغییر کند. توکن را به همان صورت دریافتی ذخیره کنید و توکن را بدون تغییر در درخواست بعدی برگردانید.

مثال درخواست اولیه

درخواست اولیه هیچ پارامتر پرس‌وجویی دریافت نمی‌کند و کل فراداده را برمی‌گرداند:

https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/metadata

مثال درخواست بعدی

هر درخواست بعدی مقدار next_delta_token را از پاسخ قبلی به عنوان پارامتر delta_token ارسال می‌کند. پاسخ شامل موارد زیر است:

تبلیغات
وقفه‌های تبلیغاتی
تگ‌هایی که سرور از زمان صدور توکن اضافه یا به‌روزرسانی کرده است.
فهرستی از آگهی‌های تبلیغاتی obsolete_ad_break_ids برای حذف از فراداده‌های ذخیره‌شده‌تان

سرور، تبلیغات موقت (ad break) که تغییر نکرده‌اند را حذف می‌کند. مثال زیر یک نظرسنجی بعدی را نشان می‌دهد که از توکن دلتا برای دریافت فقط این تغییرات اخیر استفاده می‌کند:

https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/metadata?delta_token=eyJyYW5nZXMiOlt7InMiOjEsImUiOjJ9XX0

در صورت موفقیت، خروجی مشابه زیر را مشاهده خواهید کرد:

{
   "next_delta_token": "eyJyYW5nZXMiOlt7InMiOjEsImUiOjN9XX0",
   "obsolete_ad_break_ids": ["0003069407"],
   "tags":{
      "google_1022389921":{
         "ad":"0003069408_ad1",
         "ad_break_id":"0003069408",
         "type":"start"
      },
      ...
   },
   "ads":{
      "0003069408_ad1":{
         "ad_break_id":"0003069408",
         "position":1,
         "duration":10.01,
         "title":"External - Pod Midroll 1",
         ...
      }
   },
   "ad_breaks":{
      "0003069408":{
         "type":"mid",
         "duration":30,
         "expected_duration":30,
         "ads":3
      }
   }
}

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

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

رویدادهای رسانه‌ای را در یک صف ذخیره کنید و شناسه هر رسانه را به همراه مهر زمانی آن (در صورت نمایش توسط پخش‌کننده) ذخیره کنید.
در هر به‌روزرسانی از پخش‌کننده، یا با یک فرکانس تنظیم‌شده (توصیه‌شده ۵۰۰ میلی‌ثانیه)، با مقایسه‌ی مهرهای زمانی رویداد با ابتدای پخش، صف رویدادهای رسانه‌ای را برای رویدادهای اخیراً پخش‌شده بررسی کنید.
برای رویدادهای رسانه‌ای که تأیید می‌کنید پخش شده‌اند، نوع آنها را با جستجوی شناسه رسانه در برچسب‌های وقفه تبلیغات ذخیره‌شده بررسی کنید. به خاطر داشته باشید که برچسب‌های ذخیره‌شده فقط حاوی پیشوند شناسه رسانه هستند، بنابراین تطابق دقیق امکان‌پذیر نیست.
از آنجا که برنامه پخش‌کننده ویدیوی شما به صورت دوره‌ای URL فراداده را بررسی می‌کند، ممکن است بین زمانی که پخش‌کننده ویدیوی شما با یک برچسب ID3 در جریان مواجه می‌شود و زمانی که فراداده مرتبط در دسترس است، تأخیری رخ دهد. اگر برچسب ID3 در برچسب‌های ذخیره شده یافت نشد، برچسب را در صف نگه دارید و پس از بررسی فراداده بعدی، برچسب را دوباره پردازش کنید. رویداد را تا زمان اتمام پردازش در صف نگه دارید.
پس از اینکه تگ را در متادیتا پیدا کردید، فیلد type تگ را با انواع رویدادهای تبلیغاتی ذکر شده در بخش زیر مقایسه کنید. برای پیگیری اینکه آیا پخش‌کننده ویدیو در حال پخش یک تبلیغ کوتاه است یا خیر، از رویدادهایی با مقدار progress از فیلد type استفاده کنید. این رویدادها را به نقطه پایانی تأیید رسانه ارسال نکنید. برای سایر انواع رویدادها، شناسه رسانه را به نقطه پایانی تأیید رسانه اضافه کنید و یک درخواست GET برای ردیابی پخش ارسال کنید.
رویداد رسانه‌ای را از صف پخش حذف کنید.

انواع رویدادهای تبلیغاتی

هر تگ در شیء tags متادیتا یکی از انواع رویدادهای زیر را دارد:

نوع رویداد	توضیحات
`start`	در ابتدای تبلیغ نمایش داده می‌شود.
`firstquartile`	در پایان ربع اول تبلیغ اجرا می‌شود.
`midpoint`	در نقطه میانی تبلیغ اجرا می‌شود.
`thirdquartile`	در پایان ربع سوم تبلیغ اجرا می‌شود.
`complete`	در انتهای آگهی نمایش داده می‌شود.
`progress`	به صورت دوره‌ای در طول پخش تبلیغات اجرا می‌شود تا نشان دهد که یک تبلیغ در حال پخش است. این رویدادها را به نقطه پایانی تأیید رسانه ارسال نکنید.

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

https://dai.google.com/view/p/service/linear/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/loc/ATL/network/51636543/event/0ndl1dJcRmKDUPxTRjvdog/media/google_1022389921

پاسخ‌های نمونه

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 تأیید کنید.

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

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

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

https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/session

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

نمونه متن پاسخ

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

محدودیت‌ها

اگر از API در داخل webviews استفاده می‌کنید، محدودیت‌های زیر در رابطه با هدف‌گیری اعمال می‌شود:

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

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

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

منابع اضافی

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

تلویزیون هوشمند سامسونگ (تایزن)
تلویزیون ال جی
اچ‌بی‌تی‌وی
ایکس‌باکس (اپلیکیشن‌های جاوااسکریپت)
کای او اس

پیاده‌سازی API DAI برای پخش زنده

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

۱. درخواست پخش زنده

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

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

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

نمونه متن پاسخ

{
"stream_id":"c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS",
"stream_manifest":"https://dai.google.com/linear/dash/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/manifest.mpd",
"media_verification_url":"https://dai.google.com/view/p/service/linear/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/loc/ATL/network/51636543/event/0ndl1dJcRmKDUPxTRjvdog/media/",
"metadata_url":"https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/metadata",
"session_update_url":"https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/session",
"polling_frequency":10
}

پاسخ خطا

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

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

شناسه جریان: از این مقدار می‌توان برای شناسایی جریان برگشتی استفاده کرد.
stream_manifest: این URL برای پخش جریانی به پخش‌کننده رسانه شما منتقل می‌شود.
آدرس اینترنتی تایید رسانه: این URL نقطه پایانی پایه برای ردیابی رویدادهای پخش است.
آدرس اینترنتی (url): این نشانی اینترنتی برای نظرسنجی و کسب اطلاعات دوره‌ای در مورد رویدادهای پخش زنده آینده استفاده می‌شود.
آدرس اینترنتی به‌روزرسانی جلسه: این URL برای به‌روزرسانی پارامترهای درخواست جریان ارسال‌شده در طول درخواست اولیه جریان استفاده می‌شود. توجه داشته باشید که پارامترهای این درخواست جایگزین تمام پارامترهای تنظیم‌شده برای جریان قبلی می‌شوند.
فرکانس نظرسنجی: تعداد دفعات، بر حسب ثانیه، هنگام درخواست به‌روزرسانی فراداده AdBreak از API DAI.

۲. نظرسنجی برای فراداده‌های جدید AdBreak

برای بهینه سازی پهنای باند، موارد زیر را انجام دهید:

یک درخواست اولیه GET به نقطه پایانی metadata_url ارسال کنید.
- پارامتر کوئری delta_token حذف کنید. این فرآیند به سرور اجازه می‌دهد تا فراداده کامل مربوط به پنجره ضبط‌کننده ویدیوی دیجیتال (DVR) مربوط به پخش زنده را برگرداند. پنجره DVR شامل بازه زمانی پخش موجود برای بیننده جهت عقب و جلو بردن و پخش مجدد است. پاسخ شامل یک فیلد شیء next_delta_token است.
ذخیره ابرداده در سمت کلاینت.
فراخوانی‌های بعدی را با استفاده از مقدار next_delta_token که جدیدترین پاسخ برمی‌گرداند، انجام دهید. هر پاسخ شامل یک مقدار next_delta_token است. همیشه آخرین مقداری را که دریافت می‌کنید، ارسال کنید.
برای ادغام تغییرات و حذف تبلیغات موقت منسوخ شده، متادیتای ذخیره شده را به‌روزرسانی کنید.

مثال درخواست اولیه

درخواست اولیه هیچ پارامتر پرس‌وجویی دریافت نمی‌کند و کل فراداده را برمی‌گرداند:

https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/metadata

مثال درخواست بعدی

تبلیغات
وقفه‌های تبلیغاتی
تگ‌هایی که سرور از زمان صدور توکن اضافه یا به‌روزرسانی کرده است.
فهرستی از آگهی‌های تبلیغاتی obsolete_ad_break_ids برای حذف از فراداده‌های ذخیره‌شده‌تان

https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/metadata?delta_token=eyJyYW5nZXMiOlt7InMiOjEsImUiOjJ9XX0

در صورت موفقیت، خروجی مشابه زیر را مشاهده خواهید کرد:

{
   "next_delta_token": "eyJyYW5nZXMiOlt7InMiOjEsImUiOjN9XX0",
   "obsolete_ad_break_ids": ["0003069407"],
   "tags":{
      "google_1022389921":{
         "ad":"0003069408_ad1",
         "ad_break_id":"0003069408",
         "type":"start"
      },
      ...
   },
   "ads":{
      "0003069408_ad1":{
         "ad_break_id":"0003069408",
         "position":1,
         "duration":10.01,
         "title":"External - Pod Midroll 1",
         ...
      }
   },
   "ad_breaks":{
      "0003069408":{
         "type":"mid",
         "duration":30,
         "expected_duration":30,
         "ads":3
      }
   }
}

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

رویدادهای رسانه‌ای را در یک صف ذخیره کنید و شناسه هر رسانه را به همراه مهر زمانی آن (در صورت نمایش توسط پخش‌کننده) ذخیره کنید.
در هر به‌روزرسانی از پخش‌کننده، یا با یک فرکانس تنظیم‌شده (توصیه‌شده ۵۰۰ میلی‌ثانیه)، با مقایسه‌ی مهرهای زمانی رویداد با ابتدای پخش، صف رویدادهای رسانه‌ای را برای رویدادهای اخیراً پخش‌شده بررسی کنید.
برای رویدادهای رسانه‌ای که تأیید می‌کنید پخش شده‌اند، نوع آنها را با جستجوی شناسه رسانه در برچسب‌های وقفه تبلیغات ذخیره‌شده بررسی کنید. به خاطر داشته باشید که برچسب‌های ذخیره‌شده فقط حاوی پیشوند شناسه رسانه هستند، بنابراین تطابق دقیق امکان‌پذیر نیست.
از آنجا که برنامه پخش‌کننده ویدیوی شما به صورت دوره‌ای URL فراداده را بررسی می‌کند، ممکن است بین زمانی که پخش‌کننده ویدیوی شما با یک برچسب ID3 در جریان مواجه می‌شود و زمانی که فراداده مرتبط در دسترس است، تأخیری رخ دهد. اگر برچسب ID3 در برچسب‌های ذخیره شده یافت نشد، برچسب را در صف نگه دارید و پس از بررسی فراداده بعدی، برچسب را دوباره پردازش کنید. رویداد را تا زمان اتمام پردازش در صف نگه دارید.
پس از اینکه تگ را در متادیتا پیدا کردید، فیلد type تگ را با انواع رویدادهای تبلیغاتی ذکر شده در بخش زیر مقایسه کنید. برای پیگیری اینکه آیا پخش‌کننده ویدیو در حال پخش یک تبلیغ کوتاه است یا خیر، از رویدادهایی با مقدار progress از فیلد type استفاده کنید. این رویدادها را به نقطه پایانی تأیید رسانه ارسال نکنید. برای سایر انواع رویدادها، شناسه رسانه را به نقطه پایانی تأیید رسانه اضافه کنید و یک درخواست GET برای ردیابی پخش ارسال کنید.
رویداد رسانه‌ای را از صف پخش حذف کنید.

انواع رویدادهای تبلیغاتی

هر تگ در شیء tags متادیتا یکی از انواع رویدادهای زیر را دارد:

نوع رویداد	توضیحات
`start`	در ابتدای تبلیغ نمایش داده می‌شود.
`firstquartile`	در پایان ربع اول تبلیغ اجرا می‌شود.
`midpoint`	در نقطه میانی تبلیغ اجرا می‌شود.
`thirdquartile`	در پایان ربع سوم تبلیغ اجرا می‌شود.
`complete`	در انتهای آگهی نمایش داده می‌شود.
`progress`	به صورت دوره‌ای در طول پخش تبلیغات اجرا می‌شود تا نشان دهد که یک تبلیغ در حال پخش است. این رویدادها را به نقطه پایانی تأیید رسانه ارسال نکنید.

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

https://dai.google.com/view/p/service/linear/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/loc/ATL/network/51636543/event/0ndl1dJcRmKDUPxTRjvdog/media/google_1022389921

پاسخ‌های نمونه

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 تأیید کنید.

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

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

https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/session

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

نمونه متن پاسخ

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

محدودیت‌ها

اگر از API در داخل webviews استفاده می‌کنید، محدودیت‌های زیر در رابطه با هدف‌گیری اعمال می‌شود:

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

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

منابع اضافی

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

تلویزیون هوشمند سامسونگ (تایزن)
تلویزیون ال جی
اچ‌بی‌تی‌وی
ایکس‌باکس (اپلیکیشن‌های جاوااسکریپت)
کای او اس

پیاده‌سازی API DAI برای پخش زنده

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

۱. درخواست پخش زنده

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

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

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

نمونه متن پاسخ

{
"stream_id":"c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS",
"stream_manifest":"https://dai.google.com/linear/dash/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/manifest.mpd",
"media_verification_url":"https://dai.google.com/view/p/service/linear/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/loc/ATL/network/51636543/event/0ndl1dJcRmKDUPxTRjvdog/media/",
"metadata_url":"https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/metadata",
"session_update_url":"https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/session",
"polling_frequency":10
}

پاسخ خطا

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

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

شناسه جریان: از این مقدار می‌توان برای شناسایی جریان برگشتی استفاده کرد.
stream_manifest: این URL برای پخش جریانی به پخش‌کننده رسانه شما منتقل می‌شود.
آدرس اینترنتی تایید رسانه: این URL نقطه پایانی پایه برای ردیابی رویدادهای پخش است.
آدرس اینترنتی (url): این نشانی اینترنتی برای نظرسنجی و کسب اطلاعات دوره‌ای در مورد رویدادهای پخش زنده آینده استفاده می‌شود.
آدرس اینترنتی به‌روزرسانی جلسه: این URL برای به‌روزرسانی پارامترهای درخواست جریان ارسال‌شده در طول درخواست اولیه جریان استفاده می‌شود. توجه داشته باشید که پارامترهای این درخواست جایگزین تمام پارامترهای تنظیم‌شده برای جریان قبلی می‌شوند.
فرکانس نظرسنجی: تعداد دفعات، بر حسب ثانیه، هنگام درخواست به‌روزرسانی فراداده AdBreak از API DAI.

۲. نظرسنجی برای فراداده‌های جدید AdBreak

برای بهینه سازی پهنای باند، موارد زیر را انجام دهید:

یک درخواست اولیه GET به نقطه پایانی metadata_url ارسال کنید.
- پارامتر کوئری delta_token حذف کنید. این فرآیند به سرور اجازه می‌دهد تا فراداده کامل مربوط به پنجره ضبط‌کننده ویدیوی دیجیتال (DVR) مربوط به پخش زنده را برگرداند. پنجره DVR شامل بازه زمانی پخش موجود برای بیننده جهت عقب و جلو بردن و پخش مجدد است. پاسخ شامل یک فیلد شیء next_delta_token است.
ذخیره ابرداده در سمت کلاینت.
فراخوانی‌های بعدی را با استفاده از مقدار next_delta_token که جدیدترین پاسخ برمی‌گرداند، انجام دهید. هر پاسخ شامل یک مقدار next_delta_token است. همیشه آخرین مقداری را که دریافت می‌کنید، ارسال کنید.
برای ادغام تغییرات و حذف تبلیغات موقت منسوخ شده، متادیتای ذخیره شده را به‌روزرسانی کنید.

مثال درخواست اولیه

درخواست اولیه هیچ پارامتر پرس‌وجویی دریافت نمی‌کند و کل فراداده را برمی‌گرداند:

https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/metadata

مثال درخواست بعدی

تبلیغات
وقفه‌های تبلیغاتی
تگ‌هایی که سرور از زمان صدور توکن اضافه یا به‌روزرسانی کرده است.
فهرستی از آگهی‌های تبلیغاتی obsolete_ad_break_ids برای حذف از فراداده‌های ذخیره‌شده‌تان

https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/metadata?delta_token=eyJyYW5nZXMiOlt7InMiOjEsImUiOjJ9XX0

در صورت موفقیت، خروجی مشابه زیر را مشاهده خواهید کرد:

{
   "next_delta_token": "eyJyYW5nZXMiOlt7InMiOjEsImUiOjN9XX0",
   "obsolete_ad_break_ids": ["0003069407"],
   "tags":{
      "google_1022389921":{
         "ad":"0003069408_ad1",
         "ad_break_id":"0003069408",
         "type":"start"
      },
      ...
   },
   "ads":{
      "0003069408_ad1":{
         "ad_break_id":"0003069408",
         "position":1,
         "duration":10.01,
         "title":"External - Pod Midroll 1",
         ...
      }
   },
   "ad_breaks":{
      "0003069408":{
         "type":"mid",
         "duration":30,
         "expected_duration":30,
         "ads":3
      }
   }
}

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

رویدادهای رسانه‌ای را در یک صف ذخیره کنید و شناسه هر رسانه را به همراه مهر زمانی آن (در صورت نمایش توسط پخش‌کننده) ذخیره کنید.
در هر به‌روزرسانی از پخش‌کننده، یا با یک فرکانس تنظیم‌شده (توصیه‌شده ۵۰۰ میلی‌ثانیه)، با مقایسه‌ی مهرهای زمانی رویداد با ابتدای پخش، صف رویدادهای رسانه‌ای را برای رویدادهای اخیراً پخش‌شده بررسی کنید.
برای رویدادهای رسانه‌ای که تأیید می‌کنید پخش شده‌اند، نوع آنها را با جستجوی شناسه رسانه در برچسب‌های وقفه تبلیغات ذخیره‌شده بررسی کنید. به خاطر داشته باشید که برچسب‌های ذخیره‌شده فقط حاوی پیشوند شناسه رسانه هستند، بنابراین تطابق دقیق امکان‌پذیر نیست.
از آنجا که برنامه پخش‌کننده ویدیوی شما به صورت دوره‌ای URL فراداده را بررسی می‌کند، ممکن است بین زمانی که پخش‌کننده ویدیوی شما با یک برچسب ID3 در جریان مواجه می‌شود و زمانی که فراداده مرتبط در دسترس است، تأخیری رخ دهد. اگر برچسب ID3 در برچسب‌های ذخیره شده یافت نشد، برچسب را در صف نگه دارید و پس از بررسی فراداده بعدی، برچسب را دوباره پردازش کنید. رویداد را تا زمان اتمام پردازش در صف نگه دارید.
پس از اینکه تگ را در متادیتا پیدا کردید، فیلد type تگ را با انواع رویدادهای تبلیغاتی ذکر شده در بخش زیر مقایسه کنید. برای پیگیری اینکه آیا پخش‌کننده ویدیو در حال پخش یک تبلیغ کوتاه است یا خیر، از رویدادهایی با مقدار progress از فیلد type استفاده کنید. این رویدادها را به نقطه پایانی تأیید رسانه ارسال نکنید. برای سایر انواع رویدادها، شناسه رسانه را به نقطه پایانی تأیید رسانه اضافه کنید و یک درخواست GET برای ردیابی پخش ارسال کنید.
رویداد رسانه‌ای را از صف پخش حذف کنید.

انواع رویدادهای تبلیغاتی

هر تگ در شیء tags متادیتا یکی از انواع رویدادهای زیر را دارد:

نوع رویداد	توضیحات
`start`	در ابتدای تبلیغ نمایش داده می‌شود.
`firstquartile`	در پایان ربع اول تبلیغ اجرا می‌شود.
`midpoint`	در نقطه میانی تبلیغ اجرا می‌شود.
`thirdquartile`	در پایان ربع سوم تبلیغ اجرا می‌شود.
`complete`	در انتهای آگهی نمایش داده می‌شود.
`progress`	به صورت دوره‌ای در طول پخش تبلیغات اجرا می‌شود تا نشان دهد که یک تبلیغ در حال پخش است. این رویدادها را به نقطه پایانی تأیید رسانه ارسال نکنید.

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

https://dai.google.com/view/p/service/linear/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/loc/ATL/network/51636543/event/0ndl1dJcRmKDUPxTRjvdog/media/google_1022389921

پاسخ‌های نمونه

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 تأیید کنید.

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

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

https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/session

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

نمونه متن پاسخ

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

محدودیت‌ها

اگر از API در داخل webviews استفاده می‌کنید، محدودیت‌های زیر در رابطه با هدف‌گیری اعمال می‌شود:

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