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

يتناول هذا الدليل كيفية تطوير تطبيق عميل لتحميل بث مباشر بتنسيق 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": "c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb: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 أوليًا إلى نقطة النهاية metadata_url.

    • احذف مَعلمة طلب البحث delta_token. تتيح هذه العملية للخادم عرض البيانات الوصفية الكاملة لفترة التسجيل (DVR) الخاصة بالبث. تحتوي فترة التسجيل (DVR) على الإطار الزمني للبث المتاح للمشاهد لإرجاعه وتشغيله. يتضمّن الردّ حقل next_delta_token.
  3. لتحسين معدل نقل البيانات، يمكنك تخزين قيمة next_delta_token من أحدث ردّ.

  4. في طلبك التالي، أرسِل هذه القيمة كمَعلمة طلب البحث delta_token. يعرض الخادم فقط البيانات الوصفية التي تم تغييرها منذ إنشاء هذا الرمز المميّز. يجب دائمًا إرسال أحدث رمز مميّز تلقّيته. لا تحاول تحليل الرمز المميّز أو تعديله أو إنشائه. لمعرفة التفاصيل، يُرجى الاطّلاع على الطريقة: البيانات الوصفية.

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

    // Initial request (returns full metadata and next_delta_token)
    let response = await fetch(metadata_url);
    let metadata = await response.json();
    let deltaToken = metadata.next_delta_token;
    
    // Subsequent request (returns only changes since deltaToken)
    if (deltaToken) {
      const url = new URL(metadata_url);
      url.searchParams.append('delta_token', deltaToken);
      response = await fetch(url.toString());
      const deltaMetadata = await response.json();
      // Merge deltaMetadata into your local cache
      mergeMetadata(metadata, deltaMetadata);
      deltaToken = deltaMetadata.next_delta_token;
    }
    

    في حال نجاح الطلب، ستتلقّى الاستجابة PodMetadata. إذا قدّمت المَعلمة delta_token، ستحتوي الاستجابة على الإعلانات والفواصل الإعلانية والعلامات التي أضافها الخادم أو عدّلها منذ أن أنشأ الرمز المميّز فقط. تتضمّن الاستجابة أيضًا قيمة جديدة للسمة next_delta_token. إذا كانت أي فواصل إعلانية قديمة، تتضمّن الاستجابة أيضًا قائمة obsolete_ad_break_ids بالفواصل الإعلانية التي يجب إزالتها من ذاكرة التخزين المؤقت.

    {
      "next_delta_token": "eyJyYW5nZXMiOlt7InMiOjEsImUiOjN9XX0",
      "obsolete_ad_break_ids": ["0003069407"],
      "tags":{
        "google_1022389921":{
          "ad":"0003069408_ad1",
          "ad_break_id":"0003069408",
          "type":"start"
        },
        ...
      },
      "ads":{
        "0003069408_ad1":{
          "ad_break_id":"0003069408",
          "position":1,
          "duration":10.01,
          "title":"External - Pod Midroll 1",
          "clickthrough_url":"https://.../",
          ...
        },
        ...
      },
      "ad_breaks":{
        "0003069408":{
          "type":"mid",
          "duration":30,
          "ads":3
        },
        ...
      }
    }
    
  5. احفظ عنصر tags وادمج التعديلات في ذاكرة التخزين المؤقت على جهازك. إذا كانت المَعلمة obsolete_ad_break_ids متوفّرة، عليك إزالة الفواصل الإعلانية والإعلانات والعلامات المرتبطة بها من ذاكرة التخزين المؤقت.

  6. اضبط موقّتًا باستخدام القيمة polling_frequency لطلب البيانات الوصفية بانتظام. في كل استطلاع، أرسِل قيمة next_delta_token التي تم عرضها في أحدث استجابة للبيانات الوصفية كمَعلمة طلب البحث delta_token.

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

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

  • تستخدم أحداث البث المباشر عبر بروتوكول 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_1022389921",
      ...
    }
    
  3. فلترة علامات ID3 باستخدام التنسيق TXXXgoogle_{ad_event_ID}:

    TXXXgoogle_1022389921
    

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

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

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

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

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

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

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

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

    {
      "type":"mid",
      "duration":15,
      "ads":1
    }
    
  5. استخدِم بيانات TagSegment وAdBreak لعرض معلومات حول موضع الإعلان في الفاصل الإعلاني. مثلاً: Ad 1 of 3.

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

يجب إرسال إشعار التحقّق من الوسائط لكل حدث إعلان، باستثناء النوع progress. تتجاهل ميزة "إدراج الإعلان الديناميكي" من 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_1022389921`;
    
    const response = await fetch(completeUrl);
    

    في حال نجاح العملية، ستتلقّى ردًا يتضمّن حالة الرمز 202. وإلا، سيظهر لك رمز الخطأ 404.

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