إنّ واجهة برمجة تطبيقات DAI في مرحلة تجريبية وقد لا تكون متاحة في شبكتك. اتصل بمدير حسابك للحصول على مزيد من المعلومات. ويُنصَح باستخدام حزمة تطوير البرامج لإعلانات الوسائط التفاعلية للأنظمة الأساسية التي تتوفّر فيها.

تستخدم Google تكنولوجيا الذكاء الاصطناعي لترجمة المحتوى إلى لغتك المفضّلة، وقد تتضمّن بعض الأخطاء.

إدارة أحداث البث المباشر التي تتضمّن إعلانات ديناميكية

تتيح لك واجهة برمجة التطبيقات DAI من Google تنفيذ عمليات بث مفعّلة باستخدام DAI من Google في بيئات لا تتوافق مع تنفيذ "حزمة تطوير البرامج للإعلانات التفاعلية". ننصحك بمواصلة استخدام "إعلانات الوسائط التفاعلية" على المنصات التي تتوافق مع حزمة تطوير البرامج هذه.

ننصح باستخدام واجهة برمجة التطبيقات DAI على المنصات التالية:

تلفزيون Samsung الذكي (Tizen)
تلفزيون LG
HbbTV
Xbox (تطبيقات JavaScript)
KaiOS

تتيح واجهة برمجة التطبيقات إمكانات أساسية توفّرها حزمة IMA DAI SDK. للحصول على إجابات عن أسئلة محدّدة حول التوافق أو الميزات المتوافقة، يُرجى التواصل مع مدير حسابك على Google.

تنفيذ واجهة برمجة تطبيقات DAI لأحداث البث المباشر

تتيح واجهة برمجة التطبيقات DAI بث المحتوى الخطي (المباشر) باستخدام بروتوكولَي HLS وDASH. تنطبق الخطوات الموضّحة في هذا الدليل على كلا البروتوكولَين.

لدمج واجهة برمجة التطبيقات في تطبيقك لبث الأحداث المباشرة، أكمِل الخطوات التالية:

1. طلب بث

لطلب بث مباشر من واجهة برمجة تطبيقات DAI، أرسِل طلب POST إلى نقطة نهاية البث. تحتوي استجابة JSON على بيان البث بالإضافة إلى نقاط نهاية وقيم واجهة برمجة تطبيقات DAI المرتبطة.

مثال على نص الطلب

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_id: يمكن استخدام هذه القيمة لتحديد البث الذي تم إرجاعه.
stream_manifest: يتم تمرير عنوان URL هذا إلى مشغّل الوسائط لتشغيل البث.
media_verification_url: عنوان URL هذا هو نقطة النهاية الأساسية لتتبُّع أحداث التشغيل.
metadata_url: يُستخدم عنوان URL هذا لطلب معلومات دورية حول أحداث البث المباشر القادمة.
session_update_url: يُستخدَم عنوان URL هذا لتعديل مَعلمات طلب البث التي يتم إرسالها أثناء طلب البث الأولي. يُرجى العِلم أنّ مَعلمات هذا الطلب تحلّ محل جميع المَعلمات التي تم ضبطها للبث السابق.
polling_frequency: تمثّل هذه السمة معدّل تكرار طلب البيانات الوصفية المعدَّلة لفاصل الإعلانات من واجهة برمجة تطبيقات DAI، ويتم تحديدها بالثواني.

2. التحقّق من توفّر بيانات وصفية جديدة لفواصل الإعلانات

اضبط مؤقتًا لطلب البيانات الوصفية الجديدة لـ AdBreak بشكل متكرر حسب معدل التكرار، وذلك باستخدام عنوان URL الخاص بالبيانات الوصفية. إذا لم يتم تحديدها في استجابة البث، يكون الفاصل الزمني التلقائي المقترَح 10 ثوانٍ.

لتحسين معدل نقل البيانات، اتّبِع الخطوات التالية:

أرسِل طلب 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 بفواصل الإعلانات التي يجب إزالتها من البيانات الوصفية المخزّنة

يحذف الخادم الفواصل الإعلانية التي لم تتغيّر. يعرض المثال التالي عملية استطلاع لاحقة تستخدم رمزًا مميزًا للتغيير لجلب هذه التغييرات الحديثة فقط:

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
      }
   }
}

3- الاستماع إلى أحداث ID3 وتتبُّع أحداث التشغيل

للتأكّد من وقوع أحداث معيّنة في بث فيديو، اتّبِع الخطوات التالية للتعامل مع أحداث ID3:

خزِّن أحداث الوسائط في قائمة انتظار، مع حفظ رقم تعريف كل وسيط مع الطابع الزمني الخاص به (إذا كان مشغّل الوسائط يعرضه).
في كل مرة يتم فيها تعديل الوقت من المشغّل، أو بمعدّل تكرار محدّد (يُنصح بـ 500 ملي ثانية)، تحقَّق من قائمة انتظار أحداث الوسائط بحثًا عن الأحداث التي تم تشغيلها مؤخرًا من خلال مقارنة الطوابع الزمنية للأحداث بموضع التشغيل.
بالنسبة إلى أحداث الوسائط التي تتأكّد من تشغيلها، تحقَّق من النوع من خلال البحث عن معرّف الوسائط في علامات فواصل الإعلانات المخزّنة. يُرجى العِلم أنّ العلامات المخزّنة لا تحتوي إلا على بادئة لرقم تعريف الوسائط، وبالتالي لا يمكن الحصول على تطابق تام.
بما أنّ تطبيق مشغّل الفيديو يستطلع عنوان 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

يمكنك التحقّق من أحداث التتبُّع في أداة مراقبة نشاط البث.

4. تعديل مَعلمات جلسة البث المباشر

قد تحتاج إلى تعديل مَعلمات الجلسة بعد إنشاء بث. لإجراء ذلك، أرسِل طلبًا إلى عنوان URL لتعديل الجلسة.

مثال على نص الطلب

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

القيود

في حال استخدام واجهة برمجة التطبيقات ضمن عروض الويب، تنطبق القيود التالية فيما يتعلق بالاستهداف:

UserAgent: يتم تمرير مَعلمة وكيل المستخدم كقيمة خاصة بالمتصفّح بدلاً من النظام الأساسي.
‫rdid، idtype، is_lat: لم يتم تمرير معرّف الجهاز بشكل صحيح، ما يحدّ من إمكانات الميزات التالية:
- تحديد عدد مرات الظهور
- عرض الإعلانات بالتناوب بشكل تسلسلي
- تقسيم الجمهور إلى شرائح واستهدافه

أفضل الممارسات

يُرجى العِلم أنّ نقطة نهاية البيانات الوصفية لفهارس البث المباشر تستند إلى بادئة علامة ID3 المقابلة. تم تصميم ذلك لمنع استخدام نقطة نهاية البيانات الوصفية لإرسال إشارات فورية إلى جميع عُقد التحقّق.

إدارة أحداث البث المباشر التي تتضمّن إعلانات ديناميكية تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

تنفيذ واجهة برمجة تطبيقات DAI لأحداث البث المباشر

1. طلب بث

مثال على نص الطلب

مثال على نص الرد

ردّ يتضمّن خطأ

2. التحقّق من توفّر بيانات وصفية جديدة لفواصل الإعلانات

مثال على الطلب الأوّلي

مثال على الطلب اللاحق

3- الاستماع إلى أحداث ID3 وتتبُّع أحداث التشغيل

أنواع أحداث الإعلانات

مثال على الطلب

أمثلة للردود

4. تعديل مَعلمات جلسة البث المباشر

مثال على نص الطلب

مثال على نص الرد

القيود

أفضل الممارسات

مراجع إضافية

إدارة أحداث البث المباشر التي تتضمّن إعلانات ديناميكية