تستخدم Google تكنولوجيا الذكاء الاصطناعي لترجمة المحتوى إلى لغتك المفضّلة، وقد تتضمّن بعض الأخطاء.

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

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

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

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

مفتاح أصل مخصّص لحدث بث مباشر تم إعداده باستخدام نوع Pod serving redirect "إدخال الإعلانات الديناميكي" للحصول على هذا المفتاح، اتّبِع الخطوات التالية:
- إعداد بث مباشر باستخدام ميزة "إدراج الإعلانات الديناميكي"
- استخدِم مكتبة عميل SOAP API لاستدعاء الطريقة LiveStreamEventService.createLiveStreamEvents مع العنصر LiveStreamEvent وضبط السمة dynamicAdInsertionType على قيمة التعداد POD_SERVING_REDIRECT. للاطّلاع على جميع مكتبات العملاء، يُرجى الانتقال إلى مكتبات العملاء ونموذج الرمز.
تحديد ما إذا كانت حزمة تطوير البرامج (SDK) لإعلانات الوسائط التفاعلية (IMA) متاحة لمنصتك ننصح باستخدام "أداة تطوير البرامج لإعلانات الوسائط التفاعلية" لزيادة الإيرادات. لمزيد من التفاصيل، يُرجى الاطّلاع على إعداد حزمة تطوير البرامج لإعلانات الوسائط التفاعلية (IMA SDK) من أجل ميزة "الإعلانات الديناميكية أثناء البث" (DAI).

تقديم طلب بث

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

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

مرِّر مَعلمات استهداف الإعلانات بالتنسيق 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
}

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

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

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

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

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

في طلبك التالي، أرسِل هذه القيمة كمَعلمة طلب البحث 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
    },
    ...
  }
}

احفظ عنصر tags وادمج التعديلات في ذاكرة التخزين المؤقت المحلية. إذا كانت المَعلمة obsolete_ad_break_ids متوفّرة، أزِل فواصل الإعلانات والإعلانات والعلامات المرتبطة بها من ذاكرة التخزين المؤقت.
اضبط مؤقتًا باستخدام القيمة 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 محدّدة التوقيت لنقل البيانات الوصفية المحدّدة التوقيت. للحصول على التفاصيل، يُرجى الاطّلاع على لمحة عن تنسيق Common Media Application Format مع بروتوكول البث المباشر وفق بروتوكول HTTP (HLS).
تستخدم بثوث DASH عناصر EventStream لتحديد الأحداث في ملف البيان.
تستخدم بثوث DASH عناصر InbandEventStream عندما تحتوي المقاطع على مربّعات رسائل الأحداث (emsg) لبيانات الحمولة، بما في ذلك علامات ID3. للحصول على التفاصيل، راجِع InbandEventStream.
تستخدم عمليات بث CMAF، بما في ذلك DASH وHLS، مربّعات emsg تحتوي على علامات ID3.

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

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

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

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

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

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

فلترة علامات ID3 بالتنسيق TXXXgoogle_{ad_event_ID}:
```
TXXXgoogle_1022389921
```

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

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

استرجِع العنصر tags الخاص بالبيانات الوصفية للإعلان من البيانات الوصفية الخاصة بإعلان الاستطلاع. العنصر tags هو مصفوفة من عناصر TagSegment.
استخدِم معرّف حدث الإعلان الكامل للعثور على عنصر TagSegment من النوع progress.
استخدِم الأحرف الـ 17 الأولى من معرّف حدث الإعلان للعثور على عنصر TagSegment من أنواع أخرى.

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

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

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

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

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

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