تطبيق مشغّل فيديو العميل لأحداث البث المباشر

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

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

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

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

تقديم طلب تسجيل بث في واجهة DAI Pod Inventory API

تقديم طلب POST إلى نقطة نهاية تسجيل البث تتلقى بالدور استجابة JSON تحتوي على رقم تعريف مصدر البيانات لإرسالها إلى التلاعب بالبيان ونقاط نهاية واجهة برمجة التطبيقات Pod Inventory API المرتبطة بها.

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

POST: /ssai/pods/api/v1/network/{network_code}/custom_asset/{custom_asset}/stream
Host: dai.google.com
Content-Type: application/x-www-form-urlencoded

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

{network_code} رمز شبكة "مدير إعلانات Google 360"
{custom_asset} المعرّف المخصّص المرتبط بهذا الحدث في "مدير إعلانات Google"

مَعلمات نص النموذج المرمّز

مجموعة اختيارية من تنسيقات الترميز معلمات الاستهداف .

استجابة JSON

media_verification_url عنوان URL الأساسي لاختبار فحص الاتصال لأحداث تتبُّع التشغيل. عملية تحقّق كاملة من الوسائط يتم إنشاء عنوان URL من خلال إلحاق رقم تعريف حدث إعلان بعنوان URL الأساسي هذا.
metadata_url عنوان URL لطلب البيانات الوصفية لمجموعة الإعلانات المتسلسلة.
stream_id السلسلة المُستخدَمة لتحديد جلسة البث الحالية
valid_for المهلة الزمنية المتبقية لانتهاء صلاحية جلسة البث الحالية تنسيق dhms (الأيام والساعات والدقائق والثواني) على سبيل المثال: تمثّل السمة 2h0m0.000s مدة ساعتَين.
valid_until الوقت الذي تنتهي فيه صلاحية جلسة البث الحالية، كمعيار ISO 8601 سلسلة التاريخ والوقت باللغة yyyy-MM-dd'T'hh:mm:ss.sssssssss[+|-]hh:mm .

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

curl -X POST \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "cust_params=\"section%3Dsports%26page%3Dgolf%2Ctennis\"" \
  https://dai.google.com/ssai/pods/api/v1/network/51636543/custom_asset/ext-doc-ps-redirect-hls/stream

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

{
  "stream_id":"9fe8fe4f-f12e-4fed-b509-0ca269bb1668:TUL",
  "media_verification_url":"https://dai.google.com/.../media/",
  "metadata_url":"https://dai.google.com/.../metadata",
  "session_update_url":"https://dai.google.com/.../session",
  "polling_frequency":10
}

في حال حدوث أخطاء، يتم عرض رموز خطأ 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

تشغيل البث

قم بتحميل البيان الذي استلمته من خادم معالجة البيان في الفيديو وبدء التشغيل.

استطلاع للحصول على البيانات الوصفية الجديدة للفواصل الإعلانية

ويكون التطبيق مسؤولاً عن استرداد البيانات الوصفية لكل فاصل إعلاني، على تحديد مرات الظهور التي يجب تحقيقها. لتحقيق ذلك، ستقوم بتعيين موقت لإجراء استطلاع حول واجهات برمجة تطبيقات DAI بشكل منتظم metadata_url للإعلان الجديد المعلومات. يتم تحديد الفاصل الزمني للاستطلاع في polling_frequency في رد تسجيل البث.

وفي المقابل، ستتلقّى كائن JSON يحتوي على المَعلمات التالية:

tags هي مجموعة من أزواج المفتاح/القيمة تحتوي على جميع أحداث الإعلانات التي تظهر في دفق. تكون المفاتيح إما أوّل 17 حرفًا من حدث إعلاني. المعرّف الذي يظهر في البيانات الوصفية المحددة زمنيًا للبث أو في حالة الأحداث من النوع progress، رقم تعريف حدث الإعلان الكامل.

كلّ قيمة هي عنصر يحتوي على المَعلمات التالية:

ad رقم تعريف إعلان يتطابق مع مفتاح في عنصر ads.
ad_break_id رقم تعريف فاصل إعلاني يتطابق مع مفتاح في ad_breaks الخاص بك.
type نوع حدث الإعلان. أنواع أحداث الإعلانات هي:
start يتم إطلاقه في بداية الإعلان.
firstquartile تم إطلاقها في نهاية الربع الأول.
midpoint يتم إطلاقه في منتصف الإعلان.
thirdquartile تم إطلاقها في نهاية الربع الثالث.
complete يتم إطلاقه في نهاية الإعلان.
progress يتم إطلاقها بشكل دوري في أنحاء الإعلان لإعلام التطبيق بأن الإعلان الاستراحة.
ads مجموعة من أزواج المفتاح/القيمة تصف جميع الإعلانات التي تظهر في ساحة المشاركات. تشير رسالة الأشكال البيانية المفاتيح هي أرقام تعريف إعلانات تتطابق مع القيم المتوفّرة في عنصر tags. الواردة أعلاه. كلّ قيمة هي عنصر يحتوي على المَعلمات التالية:
ad_break_id رقم تعريف فاصل إعلاني يتطابق مع مفتاح في ad_breaks الخاص بك.
position الموضع الذي يظهر فيه هذا الإعلان ضمن مجموعة الإعلانات في الإعلان ينكسر في ثانية النقطة العائمة.
duration مدة الإعلان بالثواني العائم.
clickthrough_url تمثّل هذه السمة عنوان URL الذي يجب فتحه عندما يتفاعل المستخدِم مع هذا الإعلان، إذا كان متاحًا.
ad_breaks مجموعة من أزواج المفتاح/القيمة تصف كل الفواصل الإعلانية التي تظهر في البث المباشر. المفاتيح هي أرقام تعريف الفواصل الإعلانية التي تتطابق مع القيم الواردة في tags. وads كائنًا أعلاه. كل قيمة هي كائن تحتوي على المَعلمات التالية:
type نوع الفاصل الإعلاني. أنواع الفواصل الإعلانية هي pre (إعلانات ما قبل التشغيل). mid (إعلان أثناء التشغيل) وpost (إعلان ما بعد التشغيل)
duration مدة الفاصل الإعلاني بالثواني العائم.
ads عدد الإعلانات في هذا الفاصل الإعلاني.

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

مثال على الطلب (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

مراجع إضافية