أداة معالجة البيان لأحداث البث عند الطلب

توفّر واجهة برمجة تطبيقات Pod Serving API إمكانية الوصول إلى مجموعات إعلانات الفيديو المتسلسلة التي تعمل بمعدل نقل بيانات تكيُّفي مُعدّة بطريقة يمكن تجميعها مباشرةً في قائمة تشغيل وسائط HLS أو MPEG-DASH الموجّهة للمستخدم.

يركّز هذا الدليل على تنفيذ خادم أساسي لمعالجة بيان عرض الإعلانات على شكل لوحات في أحداث بث الفيديو عند الطلب.

تلقّي طلبات بيان البث

يجب أن يوفّر معالج البيان نقطة نهاية لواجهة برمجة التطبيقات للاستماع إلى طلبات البيان من تطبيق العميل الخاص بمشغّل الفيديو. ويجب أن تجمع نقطة النهاية هذه معرّف البث من تطبيق مشغّل العميل على الأقل. ويتم استخدام رقم تعريف البث هذا لتحديد جلسة البث الخاصة بـ "مدير الإعلانات" في طلبات مجموعة الإعلانات المتسلسلة.

يجب أيضًا جمع بعض المعلومات الأخرى لتحديد مصدر المحتوى المناسب، مثل Content ID.

مثال على نقطة نهاية طلب البيان

GET /api/stream_id/{stream_id}/video/{content_id}.{format}
Host: {your_domain}

استرداد مجموعة بث المحتوى

يمكنك استخدام Content ID الذي تم جمعه من طلب البيان لاختيار مصدر المحتوى المطلوب تركيبه مع الإعلانات.

طلب بيانات مجموعة الإعلانات المتسلسلة

ولطلب الإعلانات من "مدير إعلانات Google"، على الخادم تقديم طلب POST إلى نقطة نهاية مجموعات الإعلانات، مع تمرير الملفات الشخصية للترميز المطلوبة وعلامة الإعلان ومعلَمات الاستهداف. يتضمّن هذا الطلب أيضًا رقم تعريف مصدر البيانات الذي جمعته في الخطوة 1.

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

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

نص JSON

الإجابة

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

curl -X POST \
     -d '@request-body.json' \
     -H 'Content-Type: application/json' \
  https://dai.google.com/ondemand/pods/api/v1/network/21775744923/streams/6e69425c-0ac5-43ef-b070-c5143ba68541:CHS/adpods

مثال لنص الطلب

هذا هو محتوى request_body.json المُشار إليه في طلب cURL أعلاه.

{
  "encoding_profiles": [
   {
     "profile_name": "1080p",
     "type": "media",
     "container_type": "mpeg2ts",
     "video_settings": {
       "codec": "avc1.4d000c",
       "bitrate": 5000000,
       "frames_per_second": 30.0,
       "resolution": {
         "width": 1920,
         "height": 1080
       }
     },
     "audio_settings": {
       "codec": "mp4a.40.5",
       "bitrate": 300000,
       "channels": 2,
       "sample_rate": 48000
     }
   },
   {
     "profile_name": "360p",
     "type": "media",
     "container_type": "mpeg2ts",
     "video_settings": {
       "codec": "avc1.4d000d",
       "bitrate": 1000000,
       "frames_per_second": 30.0,
       "resolution": {
         "width": 640,
         "height": 360
       }
     },
     "audio_settings": {
       "codec": "mp4a.40.5",
       "bitrate": 64000,
       "channels": 2,
       "sample_rate": 48000
     }
   },
   {
     "profile_name": "subtitles-webvtt",
     "type": "subtitles",
     "subtitle_settings": {
       "format": "webvtt"
     }
   }
 ],
 "ad_tag": "https://pubads.g.doubleclick.net/gampad/ads?...",
 "manifest_type": "hls"
}

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

{
  "valid_for": "8h0m0s",
  "valid_until": "2023-03-24T08:30:26.839717986-07:00",
  "ad_pods": [
    {
      "manifest_urls":{
        "1080p": "https://{...}/pod/0/profile/1080p.m3u8",
        "360p": "https://{...}/pod/0/profile.m3u8",
        "subtitles-webvtt": "https://{...}/pod/0/profile/subtitles-en.vtt"
      },
      "type": "pre",
      "duration": 10.0
    },
    {
      "manifest_urls":{
        "1080p": "https://{...}/pod/1/profile/1080p.m3u8",
        "360p": "https://{...}/pod/1/profile.m3u8",
        "subtitles-webvtt": "https://{...}/pod/1/profile/subtitles-en.vtt"
      },
      "type": "mid",
      "start": 15.0,
      "duration": 15.0,
      "midroll_index": 1
    },
    {
      "manifest_urls":{
        ]"1080p": "https://{...}/pod/2/profile/1080p.m3u8",
        "360p": "https://{...}/pod/2/profile.m3u8",
        "subtitles-webvtt": "https://{...}/pod/0/profile/subtitles-en.vtt""
      },
      "type": "post",
      "duration": 10.0
    }
  ]
}

تركيب مجموعات الإعلانات المتسلسلة في محتوى

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

أحداث البث المباشر وفق بروتوكول HTTP (HLS)

إذا كنت تنشئ بثًا بتنسيق HLS، سيكون بث المحتوى قائمة تشغيل متعددة المتغيرات تتضمّن روابط إلى بيانات بث منفصلة، ولكل ملف شخصي للترميز. يجب إدراج مجموعات الإعلانات المتسلسلة في كل بيان من بيانات الصيغ هذه. وتتمثل إحدى الطرق لإجراء ذلك في تحضير جميع بيانات الخيارات وتمريرها إلى شبكة توصيل المحتوى (CDN) للاستضافة. قائمة التشغيل النهائية المتعددة الصِيَغ عبارة عن مجموعة من الروابط المؤدية إلى البيانات التي تستضيفها شبكة توصيل المحتوى (CDN).

التكرار عبر ملفات تعريف الترميز

بالنسبة إلى كل ملف شخصي للترميز، عليك جمع كل بيانات مجموعة الإعلانات المتسلسلة المرتبطة من ردّ "مدير الإعلانات"، بالإضافة إلى أوقات البدء المرتبطة بها. بالنسبة إلى مجموعات الإعلانات المتسلسلة الخاصة بإعلانات ما قبل التشغيل، اضبط وقت البدء على 0. بالنسبة إلى إعلانات ما بعد التشغيل، استخدِم مدة المحتوى كوقت بدء مجموعة الإعلانات المتسلسلة. حدِّد مجموعة بث الإصدار المختلف في قائمة التشغيل المتعددة الصِيَغ التي تتطابق مع إعدادات الصوت والفيديو في كل ملف شخصي للترميز.

مثال على مصفوفة مجموعات الإعلانات المتسلسلة

"ad_pods": [
    {
      "manifest_urls":{
        "1080p": "https://{...}/pod/0/profile/1080p.m3u8",
        "360p": "https://{...}/pod/0/profile/360p.m3u8",
        "subtitles-en": "https://{...}/pod/0/profile/subitles-en.vtt"
      },
      "type": "pre",
      "duration": 10.0
    },
    {
      "manifest_urls":{
        "1080p": "https://{...}/pod/1/profile/1080p.m3u8",
        "360p": "https://{...}/pod/1/profile/360p.m3u8",
        "subtitles-en": "https://{...}/pod/1/profile/subitles-en.vtt"
      },
      "type": "mid",
      "start": 15.0,
      "duration": 15.0,
      "midroll_index": 1
    },
    {
      "manifest_urls":{
        "1080p": "https://{...}/pod/2/profile/1080p.m3u8",
        "360p": "https://{...}/pod/2/profile/360p.m3u8",
        "subtitles-en": "https://{...}/pod/2/profile/subitles-en.vtt"
      },
      "type": "post",
      "duration": 10.0
    }
  ]

مثال على قائمة تشغيل لمحتوى متعدّد الصِيَغ

#EXTM3U
#EXT-X-MEDIA:TYPE=SUBTITLES,GROUP-ID="subs0",LANGUAGE="en",NAME="English",AUTOSELECT=YES,DEFAULT=YES,URI="https://{...}/subitles-en.vtt"
#EXT-X-STREAM-INF:BANDWIDTH=5000000,RESOLUTION=1920x1080,CODECS="avc1.4d000c,mp4a.40.5"
https://{...}/1080p.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=1000000,RESOLUTION=640x360,CODECS="avc1.4d000d,mp4a.40.5"
https://{...}/360p.m3u8

مثال على بيانات خيارات المنتج المجمّعة

Encoding profile: "1080p"
Profile settings: {...}
Content manifest: https://{...}/1080p.m3u8
Ad pods (start time -> manifest):
    0 -> https://{...}/pod/0/profile/1080p.m3u8
   15 -> https://{...}/pod/1/profile/1080p.m3u8
  600 -> https://{...}/pod/2/profile/1080p.m3u8

إدراج الإعلانات في كل بيان خيار

لكل مجموعة من خيارات البث، راجِع أقسام بيان المحتوى مع الاحتفاظ بالإجمالي الفعلي لوقت المحتوى المنقضي. عند الوصول إلى موضع بداية مجموعة الإعلانات المتسلسلة، عليك استخراج قائمة الأقسام من بيان مجموعة الإعلانات المتسلسلة ولفّ قائمة الشرائح في علامتَي #EXT-X-DISCONTINUITY ثم إدراج القائمة في الموقع الحالي ضمن بيان المحتوى. واصِل هذه العملية إلى أن تتم معالجة جميع مجموعات الإعلانات المتسلسلة وأحداث بث الصيغ.

يجب أن تتوافق البيانات الناتجة مع معيار HLS. وبالتالي، بناءً على ميزات المواصفات التي يتضمّنها بيان المحتوى، قد تحتاج إلى تمرير نهائي عبر البيان المجمّع لإصلاح أرقام تسلسلات الوسائط ومدة المحتوى وأرقام تسلسلات عدم الاستمرارية وأي علامات أخرى تحتاج إلى التعديل لمراعاة الشرائح الإعلانية الجديدة. بعد إصلاح أي تناقضات مع المعيار، أرسِل بيان كل متغير خاص بالمستخدم إلى شبكة توصيل المحتوى (CDN) للاستضافة.

إذا كان بيان المحتوى مشفّرًا، يجب تخزين آخر مفتاح تشفير تم العثور عليه قبل بدء مجموعة الإعلانات المتسلسلة الحالية في علامة #EXT-X-KEY. بعد ذلك، عليك إضافة العلامة #EXT-X-KEY:METHOD=NONE لإزالة التشفير قبل القسم الأول من كل مجموعة إعلانات متسلسلة. أخيرًا، عليك إضافة نسخة من علامة #EXT-X-KEY المخزَّنة قبل الجزء الأول من المحتوى بعد كل مجموعة إعلانات متسلسلة، لاستعادة تشفير المحتوى.

مثال على بيانات خيارات المنتج المجمّعة

Encoding profile: "1080p"
Content manifest: https://{...}/1080p.m3u8
Ad pods (start time -> manifest):
    0 -> https://dai.google.com/{...}pod/0/profile/1080p.m3u8
   15 -> https://dai.google.com/{...}pod/1/profile/1080p.m3u8
  600 -> https://dai.google.com/{...}pod/2/profile/1080p.m3u8

مثال على بيان المحتوى

هذا هو محتوى بيان https://{...}/1080p.m3u8 المُدرَج في بيانات خيارات المنتج التي تم جمعها.

#EXTM3U
{...}
#EXTINF:5.000,
https://{...}/1080p/content-segment-0.ts
#EXTINF:5.000,
https://{...}/1080p/content-segment-1.ts
#EXTINF:5.000,
https://{...}/1080p/content-segment-2.ts
#EXTINF:5.000,
https://{...}/1080p/content-segment-3.ts
#EXTINF:5.000,
https://{...}/1080p/content-segment-4.ts
#EXTINF:5.000,
https://{...}/1080p/content-segment-5.ts
{...}

مثال على بيان مجموعة الإعلانات المتسلسلة

هذه هي محتوى بيان https://dai.google.com/{...}/pod/1/profile/1080p.m3u8 الوارد في بيانات خيارات المنتج المجمَّعة.

#EXTM3U
{...}
#EXTINF:5.000,
https://dai.google.com/{...}/0.ts
#EXTINF:5.000,
https://dai.google.com/{...}/1.ts
#EXTINF:5.000,
https://dai.google.com/{...}/2.ts

مثال على بيان الصيغة التي تم تركيبها

سيكون هذا هو البيان الناتج للصيغة التي تم تركيبها، والذي تم تمريره إلى شبكة توصيل المحتوى (CDN) واستضافته في https://cdn.{...}/{userid}/1080p.m3u8.

#EXTM3U
{...}
#EXTINF:5.000,
https://{...}/1080p/content-segment-0.ts
#EXTINF:5.000,
https://{...}/1080p/content-segment-1.ts
#EXTINF:5.000,
https://{...}/1080p/content-segment-2.ts
#EXT-X-DISCONTINUITY
#EXTINF:5.000,
https://dai.google.com/{...}/0.ts
#EXTINF:5.000,
https://dai.google.com/{...}/1.ts
#EXTINF:5.000,
https://dai.google.com/{...}/2.ts
#EXT-X-DISCONTINUITY
#EXTINF:5.000,
https://{...}/1080p/content-segment-3.ts
#EXTINF:5.000,
https://{...}/1080p/content-segment-4.ts
#EXTINF:5.000,
https://{...}/1080p/content-segment-5.ts
{...}

إنشاء قائمة تشغيل متعدّدة الصِيَغ

اجمع عناوين شبكة توصيل المحتوى (CDN) لكل بيان متغير مكتمل، إلى جانب تفاصيل الملف الشخصي للترميز المطابق، واجمع النتائج في ملف بيان جديد متعدد المتغيرات. يتم عرض البيان الخاص بالمستخدم كاستجابة لطلب البيان الذي تلقيته في الخطوة 1.

مثال على قائمة تشغيل نهائية متعددة الصِيَغ

#EXTM3U
#EXT-X-MEDIA:TYPE=SUBTITLES,GROUP-ID="subs0",LANGUAGE="en",NAME="English",AUTOSELECT=YES,DEFAULT=YES,URI="https://cdn.{...}-subitles-en.vtt"
#EXT-X-STREAM-INF:BANDWIDTH=5000000,RESOLUTION=1920x1080,CODECS="avc1.4d000c,mp4a.40.5"
https://cdn.{...}/{userid}/1080p.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=1000000,RESOLUTION=640x360,CODECS="avc1.4d000d,mp4a.40.5"
https://cdn.{...}/{userid}/360p.m3u8

مجموعات بث MPEG DASH

إذا كنت تنشئ مجموعة بث بتنسيق MPEG DASH، فلن تحتاج إلا إلى إنتاج ملف واحد. يسهّل ذلك تركيب مجموعات البث DASH مقارنةً بـ HLS.

يجب أن يتألف ملف وصف العرض التقديمي (MPD) للوسائط MPEG DASH المعد بشكل صحيح من عدة نقاط، ويحتوي كل منها على تمثيلات متعددة. يجب أن يتطابق كل تمثيل مع أحد ملفات الترميز وكل مجموعة إعلانات متسلسلة يتم عرضها من "مدير الإعلانات" هي أيضًا ملف MPD يحتوي على سلسلة من النقاط ذات تمثيلات متطابقة.

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

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

مثال على تنسيق MPD للمحتوى

<?xml version="1.0" encoding="UTF-8"?>
<MPD xmlns="urn:mpeg:dash:schema:mpd:2011" minBufferTime="PT1.500000S" type="static" mediaPresentationDuration="PT0H10M00.000S" profiles="urn:mpeg:dash:profile:isoff-on-demand:2011">
  <ProgramInformation moreInformationURL="http://.../info">
    <Title>Example Stream</Title>
  </ProgramInformation>
  <Period duration="PT0H0M15.000S" id="content-period-1">
    ...
  </Period>
  <Period duration="PT0H0M15.000S" id="content-period-2">
    ...
  </Period>
  <Period duration="PT0H0M15.000S" id="content-period-3">
    ...
  </Period>
  ...
</MPD>

مثال على تنسيق JSON لمجموعة الإعلانات المتسلسلة

[{
  "mpd_uri": "https://{...}pod/1.mpd",
  "type": "mid",
  "start": 15.0,
  "duration": 15.0,
  "midroll_index": 1
}]

مثال على تنسيق MPD لمجموعة الإعلانات المتسلسلة

هذا هو محتوى mpd_uri من مجموعة الإعلانات المتسلسلة بتنسيق JSON أعلاه.

<?xml version="1.0" encoding="UTF-8"?>
<MPD xmlns="urn:mpeg:dash:schema:mpd:2011" minBufferTime="PT1.500000S" type="static" mediaPresentationDuration="PT0H0M15.000S" profiles="urn:mpeg:dash:profile:isoff-on-demand:2011">
  <ProgramInformation moreInformationURL="http://.../info">
    <Title>Ad Pod 1</Title>
  </ProgramInformation>
  <Period duration="PT0H0M5.000S" id="ad-pod-1-period-1">
    ...
  </Period>
  <Period duration="PT0H0M5.000S" id="ad-pod-1-period-2">
    ...
  </Period>
  <Period duration="PT0H0M5.000S" id="ad-pod-1-period-3">
    ...
  </Period>
  ...
</MPD>

مثال على ملف MPD تم تركيبه

يمكنك عرض هذا الإشعار كردّك على طلب بيان البث الأولي.

<?xml version="1.0" encoding="UTF-8"?>
<MPD xmlns="urn:mpeg:dash:schema:mpd:2011" minBufferTime="PT1.500000S" type="static" mediaPresentationDuration="PT0H10M15.000S" profiles="urn:mpeg:dash:profile:isoff-on-demand:2011">
  <ProgramInformation moreInformationURL="http://.../info">
    <Title>Example Stream</Title>
  </ProgramInformation>
  <Period duration="PT0H0M15.000S" id="content-period-1">
    ...
  </Period>
  <Period duration="PT0H0M5.000S" id="ad-pod-1-period-1">
    ...
  </Period>
  <Period duration="PT0H0M5.000S" id="ad-pod-1-period-2">
    ...
  </Period>
  <Period duration="PT0H0M5.000S" id="ad-pod-1-period-3">
    ...
  </Period>
  <Period duration="PT0H0M15.000S" id="content-period-2">
    ...
  </Period>
  <Period duration="PT0H0M15.000S" id="content-period-3">
    ...
  </Period>
  ...
</MPD>

مراجع إضافية

• تشغيل الإعلانات المتسلسلة باستخدام حزمة تطوير البرامج لإعلانات الوسائط التفاعلية:
  • Android
  • HTML5
  • iOS
  • tvOS
• تشغيل البث من خلال ميزة DAI API