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

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

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

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

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

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

وتدعم واجهة برمجة التطبيقات الوظائف الأساسية التي تقدمها أداة تطوير البرامج (SDK) لإدراج إعلان ديناميكي لإعلانات الوسائط التفاعلية (IMA). وإذا كان لديك أسئلة معيّنة حول التوافق أو الوظائف المتوافقة، يُرجى التواصل مع مدير حسابك في 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":"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
يمكن استخدام هذه القيمة لتحديد ساحة المشاركات المعروضة.
بيان_ساحة المشاركات
تمّ تمرير عنوان URL هذا إلى مشغّل الوسائط الخاص بك لتشغيل البث.
media_verification_url
عنوان URL هذا هو نقطة النهاية الأساسية لتتبُّع أحداث التشغيل.
البيانات الوصفية_url
يُستخدم عنوان URL هذا لاستطلاع المعلومات الدورية حول أحداث البث المقبلة.
session_update_url
يُستخدم عنوان URL هذا لتحديث معلمات طلب البث التي تم إرسالها أثناء طلب البث الأولي. يُرجى العِلم أنّ معلَمات هذا الطلب تحل محل كل المعلّمات المحدّدة للبث المباشر السابق.
عدد مرات الاستطلاع
فترة التكرار بالثواني عند طلب البيانات الوصفية المحدثة لبرنامج 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

القيود

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

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

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

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

مراجع إضافية