واجهة برمجة التطبيقات الديناميكية لميزة "إدراج إعلان ديناميكي" في فيديوهات الفيديوهات عند الطلب

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

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

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

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

استخدام DAI API في فيديوهات الفيديوهات المسجّلة

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

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

  1. طلب بث من خلال إجراء اتصال POST إلى نقطة نهاية البث:

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

    https://dai.google.com/ondemand/v1/dash/content/2559737/vid/tos-dash/stream

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

    مثال لنص الاستجابة:

    {
   "stream_id":"d32f8920-612a-4d46-8bc7-d73fd6c17c85",
   "total_duration":636.458,
   "content_duration":596.458,
   "valid_for":"8h0m0s",
   "valid_until":"2020-06-04T20:39:41.274707306-07:00",
   "stream_manifest":"https://dai.google.com/ondemand/dash/content/2559737/vid/tos-dash/ATL/streams/d32f8920-612a-4d46-8bc7-d73fd6c17c85/manifest.mpd",
   "media_verification_url":"https://dai.google.com/view/p/service/vod/stream/d32f8920-612a-4d46-8bc7-d73fd6c17c85/loc/ATL/network/124319096/content/2559737/vid/tos-dash/media/",
   "ad_breaks":[
      {
         "type":"pre",
         "start":0,
         "duration":10,
         "ads":[
            {
               "seq":1,
               "duration":10,
               "title":"External NCA1C1L1 Preroll",
               "description":"External NCA1C1L1 Preroll ad",
               "clickthrough_url":"https://dai.google.com/ondemand/v1/dash/content/2474148/vid/bbb-clear/location/ATL/stream/d32f8920-612a-4d46-8bc7-d73fd6c17c85/videoclick/5489259204425938365",
               "events":[
                  {
                     "time":0.1,
                     "type":"start"
                  },
                  {
                     "time":2.5,
                     "type":"firstquartile"
                  },
                  {
                     "time":4.75,
                     "type":"midpoint"
                  },
                  {
                     "time":7.5,
                     "type":"thirdquartile"
                  },
                  {
                     "time":9,
                     "type":"complete"
                  }
               ]
            }
         ]
      },
      {
         "type":"mid",
         "start":45,
         "duration":10,
         "ads":[
            {.... }
               ]
            }
         ]
      },
      {
         "type":"post",
         "start":626.458,
         "duration":10,
         "ads":[...]
      }
   ]
}

    الرد على الخطأ

    في حال حدوث أخطاء، يتم عرض رموز خطأ HTTP العادية بدون نص استجابة JSON.

  2. تحليل استجابة JSON وتخزين القيم التالية:

    • stream_id
    • stream_manifest
    • media_verification_url
    • ad_breaks

  3. لإجراء عملية التحقّق من خلال الوسائط، يُرجى الاطّلاع على أحداث ID3:

    1. تخزين أحداث الوسائط في قائمة انتظار، مع حفظ كل معرّف وسائط مع طابعه الزمني (إذا ظهره المشغّل).
    2. في كل مرة يتم فيها التحديث من المشغّل، أو بمعدّل تكرار معيّن (يُنصح به 500 ملي ثانية)، اطّلِع على قائمة انتظار أحداث الوسائط للأحداث التي تم تشغيلها مؤخرًا، من خلال مقارنة الطوابع الزمنية للأحداث برأس التشغيل.
    3. بالنسبة إلى أحداث الوسائط التي تأكدت من تشغيلها، يمكنك تتبع التشغيل من خلال إلحاق معرّف الوسائط بنقطة نهاية التحقق من الوسائط وتقديم طلب GET.

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

    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. اختياري: استخدِم بيانات ad_breaks من ساحة المشاركات لإنشاء ردّ للبحث عن نوع الحدث الذي تم تنشيطه.

  5. أزِل الحدث الإعلامي من قائمة الانتظار.

القيود

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

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

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

إنّ ربط علامات ID3 بنوع الحدث المناسب يعد أمرًا شاقًا في الفيديوهات عند الطلب. استخدِم معلومات ad_breaks المعروضة في ملف JSON للبحث عن الفعالية مباشرةً، مثلما تفعل مع المحتوى المباشر.

مراجع إضافية