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

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

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

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

تقديم طلب بث

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

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

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

    يقدم المثال التالي طلب بث:

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

    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، حدِّد موقع معرّف جلسة البث وخزِّن البيانات الأخرى للخطوات اللاحقة.

البيانات الوصفية للإعلان على شكل استطلاع

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

  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.

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

بالنسبة إلى كل حدث إعلان، باستثناء النوع progress، أرسِل إشارة ping لإثبات صحة الوسائط. تتجاهل ميزة "الإعلانات الديناميكية أثناء البث" من Google أحداث 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) لفحص سجلّ سابق لجميع أحداث الإعلانات. لمعرفة التفاصيل، يُرجى الاطّلاع على مراقبة بث مباشر وتحديد المشاكل وحلّها.