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

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

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

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

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

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

يمكنك تقديم طلب POST إلى نقطة نهاية تسجيل البث. ستتلقى بدورها استجابة JSON تحتوي على معرّف البث لإرساله إلى خادم معالجة البيان ونقاط نهاية واجهة برمجة تطبيقات Pod Present 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":{"cmsid":"12345","vid":"sample-video"}}' \
     -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 وتخزين القيم ذات الصلة.

طلب بيان البث من معالج البيانات

لكل معالج بيانات تنسيقات الطلبات والاستجابة المختلفة. تواصَل مع مزوّد المعالجة لفهم متطلباته الخاصة. إذا كنت تنفّذ أداة معالجة البيانت الخاصة بك، فاقرأ دليل مناولة البيانات لفهم متطلبات هذا المكوّن.

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

مثال على طلب (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.3 ضمن النطاق. لكل علامة بيانات وصفية رقم التعريف TXXX، وتبدأ القيمة بالسلسلة google_ متبوعة بسلسلة من الأحرف. هذه القيمة هي رقم تعريف حدث الإعلان.

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

مثال على علامة رقم التعريف 3

TXXXgoogle_1234567890123456789

بالنسبة إلى مجموعات بث MP4، يتم إرسالها كأحداث رسائل ضمن النطاق تحاكي علامات 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",
  ...
}

تعرض بعض مكتبات مشغّلات الوسائط تلقائيًا أحداث رسائل قصيرة تحاكي علامات 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"
  },
  ...
}

إرسال إشعارات لإثبات ملكية الوسائط

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

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

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

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

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

مثال على ردّ ناجح

HTTP/1.1 202 Accepted

مراجع إضافية

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