تجهيز العميل لعملية إعادة التوجيه إلى عرض الإعلانات المتسلسلة

يغطّي هذا الدليل تطوير تطبيق عميل لتحميل بث مباشر بتنسيق HLS أو DASH باستخدام Pod serving API ومعالج البيان.

المتطلبات الأساسية

قبل المتابعة، يجب أن يتوفّر لديك ما يلي:

• مفتاح أصل مخصّص لحدث بث مباشر تم إعداده باستخدام نوع DAI ‏Pod serving redirect للحصول على هذا المفتاح، اتّبِع الخطوات التالية:

  • إعداد بث مباشر لإعلانات DAI.

  • استخدِم مكتبة عميل SOAP API لاستدعاء الطريقة LiveStreamEventService.createLiveStreamEvents باستخدام عنصر LiveStreamEvent وضبط السمة dynamicAdInsertionType على قيمة التعداد POD_SERVING_REDIRECT. للاطّلاع على جميع مكتبات العملاء، راجِع مكتبات العملاء ونموذج الرمز البرمجي.

• تحديد ما إذا كانت حزمة تطوير البرامج (SDK) لإعلانات الوسائط التفاعلية (IMA) متاحة على منصّتك ننصحك باستخدام حزمة IMA SDK لزيادة الإيرادات. لمعرفة التفاصيل، يُرجى الاطّلاع على إعداد حزمة IMA SDK لإعلانات DAI.

إرسال طلب بث

عندما يختار المستخدم بثًا، اتّبِع الخطوات التالية:

1. أرسِل طلب POST إلى طريقة خدمة البث المباشر. لمعرفة التفاصيل، يُرجى الاطّلاع على الطريقة: البث.

2. مرِّر مَعلمات استهداف الإعلانات بتنسيق application/x-www-form-urlencoded أو application/json. يسجِّل هذا الطلب جلسة بث باستخدام Google DAI.

   يرسل المثال التالي طلب بث:

   ترميز النموذج

   const url = `https://dai.google.com/ssai/pods/api/v1/` +
         `network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/stream`;
   
   const params = new URLSearchParams({
           cust_params: 'section=sports&page=golf,tennis'
   }).toString();
   
   const response = await fetch(url, {
           method: 'POST',
           headers: {
             'Content-Type': 'application/x-www-form-urlencoded'
           },
           body: params
   });
   
   console.log(await response.json());
   

   ترميز JSON

   const url = `https://dai.google.com/ssai/pods/api/v1/` +
         `network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/stream`;
   
   const response = await fetch(url, {
           method: 'POST',
           headers: {
             'Content-Type': 'application/json'
           },
           body: JSON.stringify({
             cust_params: {
               section: 'sports',
               page: 'golf,tennis'
             }
           })
   });
   
   console.log(await response.json());
   

   إذا كانت الاستجابة ناجحة، سيظهر لك ناتج مشابه لما يلي:

   {
   "stream_id": "8d2b2292-6356-4c0e-94be-cece01d2df2e:DLS",
   "media_verification_url": "https://dai.google.com/view/.../event/c14aZDWtQg-ZwQaEGl6bYA/media/",
   "metadata_url": "https://dai.google.com/linear/pods/hls/.../metadata",
   "session_update_url": "https://dai.google.com/linear/.../session",
   "polling_frequency": 10
   }
   

3. في استجابة JSON، حدِّد معرّف جلسة البث وخزِّن البيانات الأخرى للخطوات اللاحقة.

   ملاحظة مهمة: لكي يعمل تطبيقك، استخدِم عناوين URL المقدَّمة في الاستجابة مباشرةً. لا تنشئ عناوين URL، لأنّ المسارات قد تتغيّر.

التحقّق من البيانات الوصفية للإعلان

للتحقّق من البيانات الوصفية للإعلان، اتّبِع الخطوات التالية:

1. اقرأ قيمة metadata_url من استجابة تسجيل البث.

2. أرسِل طلب GET إلى نقطة النهاية. لمعرفة التفاصيل، يُرجى الاطّلاع على الطريقة: البيانات الوصفية.

   يجلب المثال التالي البيانات الوصفية للإعلان:

   const response = await fetch(metadata_url);
   console.log(await response.json());
   

   إذا كانت الاستجابة ناجحة، ستتلقّى استجابة PodMetadata لفواصل الإعلانات الحالية والقادمة:

   {
     "tags":{
       "google_5555555555":{
         "ad":"0000229834_ad1",
         "ad_break_id":"0000229834",
         "type":"firstquartile"
       },
       "google_1234567890123456789":{
         "ad":"0000229834_ad1",
         "ad_break_id":"0000229834",
         "type":"progress"
       },
       ...
     },
     "ads":{
       "0000229834_ad1":{
         "ad_break_id":"0000229834",
         "position":1,
         "duration":15,
         "clickthrough_url":"https://.../",
         ...
       },
             ...
     },
     "ad_breaks":{
       "0000229834":{
         "type":"mid",
         "duration":15,
         "ads":1
       },
       ...
     }
   }
   

3. احفظ عنصر tags للخطوات اللاحقة.

4. اضبط مؤقتًا باستخدام قيمة polling_frequency لطلب البيانات الوصفية بانتظام لجميع فواصل الإعلانات اللاحقة.

تحميل البث في مشغّل الفيديو

بعد الحصول على معرّف الجلسة من استجابة التسجيل، مرِّر المعرّف إلى معالج البيان أو أنشئ عنوان URL لبيان لتحميل البث في مشغّل فيديو.

لمعرفة كيفية تمرير معرّف الجلسة، يُرجى الاطّلاع على مستندات معالج البيان. إذا كنت تطوّر معالج بيان، يُرجى الاطّلاع على معالج البيان للبث المباشر.

يجمع المثال التالي عنوان URL لبيان:

https://<your_manifest_manipulator_url>/manifest.m3u8?DAI_stream_ID=SESSION_ID&network_code=NETWORK_CODE&DAI_custom_asset_key=CUSTOM_ASSET_KEY"

عندما يصبح المشغّل جاهزًا، ابدأ التشغيل.

الاستماع إلى أحداث الإعلانات

تحقَّق من تنسيق حاوية البث للبيانات الوصفية المحدّدة بوقت:

• تستخدم بثوث HLS التي تحتوي على حاويات Transport Stream (TS) علامات ID3 المحدّدة بوقت لنقل البيانات الوصفية المحدّدة بوقت. لمعرفة التفاصيل، يُرجى الاطّلاع على لمحة عن تنسيق Common Media Application Format مع البث المباشر وفق بروتوكول HTTP ‏(HLS).

• تستخدم بثوث DASH عناصر EventStream لتحديد الأحداث في البيان.

• تستخدم بثوث DASH عناصر InbandEventStream عندما تحتوي الشرائح على مربّعات رسالة الحدث (emsg) لبيانات الحمولة، بما في ذلك علامات ID3. لمعرفة التفاصيل، يُرجى الاطّلاع على InbandEventStream.

• تستخدم بثوث CMAF، بما في ذلك DASH وHLS، مربّعات emsg التي تحتوي على علامات ID3.

لاسترداد علامات ID3 من البث، يُرجى الرجوع إلى دليل مشغّل الفيديو. لمعرفة التفاصيل، يُرجى الاطّلاع على دليل التعامل مع البيانات الوصفية المحدّدة بوقت

لاسترداد معرّف حدث الإعلان من علامات ID3، اتّبِع الخطوات التالية:

1. فلتر الأحداث حسب scheme_id_uri باستخدام urn:google:dai:2018 أو https://aomedia.org/emsg/ID3.

2. استخرِج مصفوفة البايت من حقل message_data.

   يفكّ المثال التالي ترميز بيانات emsg إلى JSON:

   {
     "scheme_id_uri": "https://developer.apple.com/streaming/emsg-id3",
     "presentation_time": 27554,
     "timescale": 1000,
     "message_data": "ID3TXXXgoogle_1234567890123456789",
     ...
   }
   

3. فلتر علامات ID3 بالتنسيق TXXXgoogle_{ad_event_ID}:

   TXXXgoogle_1234567890123456789
   

عرض بيانات أحداث الإعلان

للعثور على العنصر TagSegment ، اتّبِع الخطوات التالية:

1. استردِد عنصر البيانات الوصفية للإعلان tags من التحقّق من البيانات الوصفية للإعلان. عنصر tags هو مصفوفة من عناصر TagSegment.

2. استخدِم معرّف حدث الإعلان الكامل للعثور على عنصر TagSegment من النوع progress.

3. استخدِم أول 17 حرفًا من معرّف حدث الإعلان للعثور على عنصر TagSegment من أنواع أخرى.

4. بعد الحصول على TagSegment، استخدِم السمة ad_break_id كمفتاح للعثور على AdBreak عنصر في عنصر ad_breaks للبيانات الوصفية للإعلان.

   يعثر المثال التالي على عنصر AdBreak:

   {
     "type":"mid",
     "duration":15,
     "ads":1
   }
   

5. استخدِم بيانات TagSegment وAdBreak لعرض معلومات عن موضع الإعلان في فاصل الإعلانات. على سبيل المثال، Ad 1 of 3.

إرسال طلبات ping للتحقّق من الوسائط

لكل حدث إعلان، باستثناء النوع progress، أرسِل طلب ping للتحقّق من الوسائط. يتجاهل Google DAI أحداث progress، وقد يؤثر إرسال هذه الأحداث بشكل متكرّر في أداء تطبيقك.

لإنشاء عنوان URL الكامل للتحقّق من الوسائط لحدث إعلان، اتّبِع الخطوات التالية:

1. من استجابة البث، ألحِق معرّف حدث الإعلان الكامل بقيمة media_verification_url.

2. أرسِل طلب GET باستخدام عنوان URL الكامل:

   // media_verification_url: "https://dai.google.com/view/.../event/c14aZDWtQg-ZwQaEGl6bYA/media/"
   const completeUrl = `${media_verification_url}google_5555555555123456789`;
   
   const response = await fetch(completeUrl);
   

   إذا كانت الاستجابة ناجحة، ستتلقّى استجابة برمز الحالة 202. وإلا، ستتلقّى رمز الخطأ 404.

يمكنك استخدام أداة مراقبة نشاط البث (SAM) لفحص سجلّ سابق لجميع أحداث الإعلانات. لمعرفة التفاصيل، يُرجى الاطّلاع على مراقبة بث مباشر وتحديد المشاكل وحلّها