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

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

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

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

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

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

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

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

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

TXXXgoogle_1234567890123456789

بالنسبة إلى أحداث البث بتنسيق MP4، يتم إرسالها كأحداث رسائل إلكترونية ضمن النطاق تحاكي الإصدار 2.3 من المعرّف 3 (ID3). . يحتوي كل مربع رسالة إلكترونية ذي صلة على قيمة 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",
  ...
}

تعرض بعض مكتبات مشغّلات الوسائط تلقائيًا أحداث الرسائل الإلكترونية التي تحاكي رقم التعريف 3. كعلامات 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 من تسجيل البث الاستجابة.

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

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

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

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

HTTP/1.1 202 Accepted

مراجع إضافية

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