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

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

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

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

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

تنفيذ DAI API لأحداث البث المباشر

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

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

1- طلب بث

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

2. استطلاع بشأن البيانات الوصفية الجديدة في AdBreak

اضبط مؤقتًا لاستطلاع آراء البيانات الوصفية الجديدة في AdBreak حسب معدّل الاستطلاع، باستخدام عنوان URL للبيانات الوصفية. إذا لم يتم تحديد ذلك في استجابة البث، يكون الفاصل الزمني التلقائي المقترَح هو 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

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

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

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

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

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

القيود

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

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

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

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

مراجع إضافية