تطبيق مشغّل الفيديو التابع للعميل لبث الفيديوهات عند الطلب

تتيح لك Google DAI Pod Serving API تنفيذ ميزة إدراج الإعلانات من جهة الخادم باستخدام "إعلانات Google" مع الحفاظ على التحكّم في عملية دمج الفيديوهات.

يوضّح لك هذا الدليل كيفية التفاعل مع واجهة برمجة التطبيقات Pod Serving API وتحقيق وظائف مشابهة باستخدام حزمة تطوير البرامج (SDK) لعرض الإعلانات الديناميكية في "إعلانات الوسائط التفاعلية". إذا كانت لديك أسئلة محدّدة حول الوظائف المتوافقة، يُرجى التواصل مع مدير حسابك على Google.

تتيح واجهة برمجة التطبيقات Pod Serving API بث ملفات البودكاست باستخدام بروتوكولَي البث HLS أو MPEG-DASH. يركّز هذا الدليل على أحداث البث باستخدام بروتوكول HLS ويسلّط الضوء على الاختلافات الرئيسية بين HLS وMPEG-DASH في خطوات محدّدة.

لدمج واجهة برمجة التطبيقات Pod Serving API في تطبيقك لبث الفيديوهات عند الطلب، أكمِل الخطوات التالية:

تقديم طلب تسجيل بث إلى "مدير إعلانات Google"

أرسِل طلب POST إلى نقطة نهاية تسجيل البث. وستتلقّى بدورك ملفًا شخصيًا استجابة JSON يحتوي على معرّف البث لإرساله إلى خادم تعديل البيان ونقاط نهاية Pod Serving API المرتبطة به.

نقطة النهاية لواجهة برمجة التطبيقات

POST: /ondemand/pods/api/v1/network/{network_code}/stream_registration
Host: dai.google.com
Content-Type: application/json

مَعلمات المسار

مَعلمات محتوى JSON

استجابة JSON

مثال على طلب (cURL)

curl -X POST \
     -d '{"targeting_parameters":{"url":"http://example.com"}}' \
     -H 'Content-Type: application/json' \
  https://dai.google.com/ondemand/pods/api/v1/network/21775744923/stream_registration

مثال على إجابة

{
  "media_verification_url": "https://dai.google.com/.../media/",
  "metadata_url": "https://dai.google.com/.../metadata",
  "stream_id": "6e69425c-0ac5-43ef-b070-c5143ba68541:CHS",
  "valid_for": "8h0m0s",
  "valid_until": "2023-03-24T08:30:26.839717986-07:00"
}

في حال حدوث أخطاء، يتم عرض رموز أخطاء HTTP العادية بدون محتوى استجابة JSON.

تحليل استجابة JSON وتخزين القيم ذات الصلة

طلب بيان البث من أداة التحكّم في البيان

ولكل أداة معالجة بيان بيانات تطبيق تنسيقات مختلفة للطلبات والردود. يُرجى التواصل مع موفّر أداة التحكّم لمعرفة متطلباته المحدّدة. إذا كنت بصدد تنفيذ أداة معالجة البيان الخاصة بك، اطّلِع على دليل أداة معالجة البيان للتعرّف على requirements for this component.

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

مثال على طلب (cURL)

curl https://{manifest_manipulator}/video/1331997/stream/6e69425c-0ac5-43ef-b070-c5143ba68541:CHS/vod_manifest.m3u8

مثال على الاستجابة (HLS)

#EXTM3U
#EXT-X-MEDIA:TYPE=SUBTITLES,GROUP-ID="subs0",LANGUAGE="en",NAME="English",AUTOSELECT=YES,DEFAULT=YES,URI="abcd1234_     subitles-en.vtt"
#EXT-X-STREAM-INF:BANDWIDTH=5000000,RESOLUTION=1920x1080,CODECS="avc1.42e00a,mp4a.40.2"
abcd1234_video-1080p.m3u8

تشغيل البث

حمِّل ملف البيان الذي تلقّيته من خادم تعديل البيان في مشغّل فيديو وابدأ التشغيل.

طلب البيانات الوصفية لمجموعة الإعلانات المتسلسلة من "مدير إعلانات Google"

قدِّم طلب GET إلى metadata_url الذي تلقّيته في الخطوة الأولى. يجب تنفيذ هذه الخطوة بعد استلام البيان المُدمَج من أداة تعديل البيان. وفي المقابل، تتلقّى عنصر JSON يحتوي على الجدول التالي المَعلمات:

يمكنك تخزين هذه القيم لربطها بأحداث البيانات الوصفية الموقّتة ضمن بث الفيديو.

مثال على طلب (cURL)

curl https://dai.google.com/.../metadata

مثال على إجابة

{
  "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
    },
    ...
  }
}

رصد أحداث الإعلانات

الاستماع إلى البيانات الوصفية المبرمَجة من خلال أحداث الإعلانات التي تم تشغيلها في بث الصوت/الفيديو في مشغّل الفيديو

بالنسبة إلى مصادر بيانات MPEG-TS، تظهر البيانات الوصفية كعلامات ID3 v2.3 ضمن النطاق. تحتوي كل علامة بيانات وصفية على رقم التعريف TXXX، وتبدأ القيمة بالسلسلة google_ متبوعةً بسلسلة من الأحرف. هذه القيمة هي رقم تعريف حدث الإعلان.

العنصر XXX في TXXX ليس عنصرًا نائبًا. السلسلة TXXX هي معرّف علامة ID3 محجوزة "للنص الذي يحدّده المستخدم".

مثال على علامة ID3

TXXXgoogle_1234567890123456789

بالنسبة إلى أحداث MP4، يتم إرسالها كأحداث emsg ضمن النطاق تحاكي علامات ID3 v2.3. يحتوي كل مربّع رسالة إلكترونية ذي صلة على قيمة scheme_id_uri إما https://aomedia.org/emsg/ID3 أو https://developer.apple.com/streaming/emsg-id3 وقيمة message_data تبدأ بالرقم ID3TXXXgoogle_. وقيمة message_data هذه، بدون البادئة ID3TXXX، هي رقم تعريف حدث الإعلان.

مثال على مربّع الرسالة الإلكترونية

قد يختلف هيكل البيانات حسب مكتبة مشغّل الوسائط.

إذا كان معرّف حدث الإعلان هو google_1234567890123456789، سيظهر الردّ على النحو التالي:

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

تعرِض بعض مكتبات مشغّلات الوسائط تلقائيًا أحداث emsg التي تحاكي علامات ID3 كعلامات ID3 أصلية. في هذه الحالة، تعرِض أحداث البث بتنسيق MP4 علامات ID3 متطابقة مثل MPEG_TS.

تعديل واجهة مستخدم تطبيق مشغّل الفيديو لدى العميل

يمكن مطابقة كلّ رقم تعريف حدث إعلان مع مفتاح في عنصر tags من الخطوة 4. تتم مطابقة هذه القيم في خطوتَين:

1. تحقّق من عنصر tags بحثًا عن مفتاح يتطابق مع رقم تعريف الحدث الإعلاني الكامل. في حال العثور على مطابقة، استرجع نوع الحدث والكائنَينad و ad_break المرتبطَين به. يجب أن يكون نوع هذه الأحداث هو progress.

   إذا لم يتم العثور على مطابقة لرقم تعريف حدث الإعلان الكامل، تحقَّق من tags العنصر بحثًا عن مفتاح يتطابق مع أول 17 حرفًا من رقم تعريف حدث الإعلان. استرجع نوع الحدث وعنصرَي ad وad_break المرتبطَين به. من المفترض أن يؤدي ذلك إلى استرداد جميع الأحداث التي لها أنواع غير progress.

2. استخدِم هذه المعلومات التي تم استرجاعها لتعديل واجهة المستخدم الخاصة بتطبيقك. على سبيل المثال، عندتلقّي حدثstart أو حدثprogress الأول، يمكنك إخفاء عناصر التحكّم في التقديم/الترجيع في المشغّل وعرض تراكب يصف موضع الإعلان الحالي في الفاصل الإعلاني، على سبيل المثال: "الإعلان 1 من 3".

أمثلة على أرقام تعريف أحداث الإعلانات

google_1234567890123456789 // Progress event ID
google_5555555555123456789 // First Quartile event ID

مثال على عنصر العلامات

{
  "google_5555555555":{
    "ad":"0000229834_ad1",
    "ad_break_id":"0000229834",
    "type":"firstquartile"
  },
  "google_1234567890123456789":{
    "ad":"0000229834_ad1",
    "ad_break_id":"0000229834",
    "type":"progress"
  },
  ...
}

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

يجب إرسال إشعار إثبات ملكية الوسائط إلى "مدير إعلانات Google" في كل مرة يتم فيها تلقّي حدث إعلان بنوع غير progress.

لإنشاء عنوان URL الكامل لإثبات ملكية الوسائط لحدث إعلاني، يجب إلحاق رقم تعريف حدث الإعلان بالكاملmedia_verification_url بقيمة media_verification_url من استجابة تسجيل البث.

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

مثال على طلب (cURL)

curl https://{...}/media/google_5555555555123456789

مثال على استجابة ناجحة

HTTP/1.1 202 Accepted

مراجع إضافية

• مستندات حزمة تطوير البرامج لإعلانات الوسائط التفاعلية
• مقارنة بين أنواع تنفيذ مشغل الإعلانات الديناميكية أثناء التشغيل