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