إدراج الإعلانات باستخدام البيانات الوصفية لتوقيت حزمة الإعلانات

يصف هذا الدليل كيفية إدراج فواصل إعلانية باستخدام طريقة بيانات توقيت مجموعة الإعلانات المتسلسلة الوصفية (ATM) لجلب التوقيت والمدّة الدقيقَين للفواصل الإعلانية، بما في ذلك الإعلانات ما قبل التشغيل.

لإدراج إعلانات ما قبل التشغيل وإدارة العودة إلى المحتوى بعد الفواصل الإعلانية أثناء التشغيل، ننصحك باستدعاء واجهات برمجة التطبيقات التالية:

• Ad pod Timing Metadata (ATM) API: لاستعلام نتائج قرار مجموعة الإعلانات المتسلسلة، بما في ذلك مدّتَي الإعلان واللوحة
• نقطة نهاية مقطع الإعلان: لطلب مقاطع الإعلانات أو اللوحات مع خيار إنهاء مجموعة الإعلانات الحالية

اختياريًا، بالنسبة إلى أحداث البث المباشر المتزامنة الكثيرة، ننصحك باستدعاء Early Ad Break Notification (EABN) API لجدولة قرارات الإعلانات قبل بدء الفاصل الإعلاني.

المتطلبات الأساسية

للبدء، تحتاج إلى إعداد حدث بث مباشر لنوع "إدراج الإعلانات الديناميكي" (DAI) من نوع إعادة توجيه عرض مجموعة الإعلانات. اختَر إحدى الطريقتَين التاليتَين:

• واجهة مستخدم "إدارة الإعلانات": يمكنك إعداد بث مباشر لـ DAI.
• Ad Manager API: استخدِم مكتبة عميل (الخيارات المتاحة) لاستدعاء LiveStreamEventService.createLiveStreamEvents طريقة. اضبط المَعلمة LiveStreamEvent.dynamicAdInsertionType على POD_SERVING_REDIRECT.

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

عندما يختار المستخدم حدث بث مباشر، يرسل تطبيق العميل طلب بث إلى إدارة إعلانات Google. في استجابة البث، يستخرج التطبيق رقم تعريف جلسة Google DAI والبيانات الوصفية لتضمينها في طلب بيان البث.

يمرّر المثال التالي رقم تعريف جلسة Google DAI إلى أداة تعديل البيان:

https://MANIFEST_MANIPULATOR_URL/manifest.m3u8?DAI_stream_ID=SESSION_ID&network_code=NETWORK_CODE&DAI_custom_asset_key=CUSTOM_ASSET_KEY

عند معالجة طلب تشغيل محتوى الفيديو، خزِّن رقم تعريف جلسة Google DAI وCUSTOM_ASSET_KEY من الطلب للتحضير لـ دمج الإعلانات.

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

لاسترداد توقيت مجموعة إعلانات متسلسلة، اتّبِع الخطوات التالية:

1. أنشئ رمز HMAC.
2. استدعِ واجهة برمجة التطبيقات ATM باستخدام رمز HMAC.

طلب بيانات توقيت الإعلانات ما قبل التشغيل الوصفية

تحقَّق من إعدادات الإعلانات ما قبل التشغيل لحدث البث المباشر باستخدام الخيارات التالية:

• الإعلانات ما قبل التشغيل في أحداث البث المباشر لـ DAI (إصدار تجريبي)
• LiveStreamEvent.prerollsettings

لاسترداد نتائج قرار الإعلانات ما قبل التشغيل، أرسِل طلبًا إلى واجهة برمجة التطبيقات ATM.

يرسل المثال التالي طلب ATM للإعلانات ما قبل التشغيل:

curl "https://dai.google.com/linear/pods/v1/adv/network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/pod.json?stream_id=SESSION_ID&ad_break_id=preroll&auth-token=your_signed_HMAC_token"

طلب بيانات توقيت الإعلانات أثناء التشغيل الوصفية

لاسترداد البيانات الوصفية لمجموعة الإعلانات المتسلسلة أثناء التشغيل، اتّبِع الخطوات التالية:

1. حلِّل بيان البث المباشر للعثور على علامات الإعلانات التي تحتوي على التوقيت والمدّة لكل فاصل إعلاني أثناء التشغيل.
2. استدعِ نقطة نهاية واجهة برمجة التطبيقات ATM لطلب المدّة الدقيقة لمجموعة إعلانات متسلسلة والفاصل الإعلاني الاحتياطي. تعرض واجهة برمجة التطبيقات كائن JSON يتضمّن نتائج قرار مجموعة الإعلانات.

يرسل المثال التالي طلب ATM للإعلانات أثناء التشغيل:

curl "https://dai.google.com/linear/pods/v1/adv/network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/pod.json?stream_id=SESSION_ID&ad_break_id=AD_BREAK_ID&pd=AD_BREAK_DURATION&auth-token=your_signed_HMAC_token"

إذا نجح الطلب، ستظهر لك نتيجة مشابهة لكائن JSON التالي:

{
  "status": "final",
  "ads": [
    {
      "duration_ms": 5046,
      "variants": {
        "devrel1428000": {
          "segment_extension": "ts",
          "segment_durations": {
            "timescale": 1000,
            "values": [
              5045
            ]
          }
        },
        "devrel1928000": {
          "segment_extension": "ts",
          "segment_durations": {
            "timescale": 1000,
            "values": [
              5045
            ]
          }
        }
      }
    }
  ],
  "slate": {
    "duration_ms": 0,
    "variants": {
      "devrel1428000": {
        "segment_extension": "ts",
        "segment_durations": {
          "timescale": 1000,
          "values": [
            5005,
            ...
            5046
          ]
        }
      },
      "devrel1928000": {
        "segment_extension": "ts",
        "segment_durations": {
          "timescale": 1000,
          "values": [
            5005,
            ...
            5046
          ]
        }
      }
    }
  }
}

دمج الإعلانات في بيان المحتوى

توضّح لك الأقسام التالية كيفية تعديل بيان البث المباشر وإضافة مقاطع الإعلانات.

تحديد مقاطع الفاصل الإعلاني وإدراج الانقطاعات

أثناء معالجة كل بيان مختلف، حدِّد علامتَي EXT-X-CUE-IN وEXT-X-CUE-OUT في البث، ما يشير إلى بداية الفاصل الإعلاني ونهايته.

استبدِل علامتَي EXT-X-CUE-IN وEXT-X-CUE-OUT بعناصر EXT-X-DISCONTINUITY ليتمكّن مشغّل الفيديو على جهاز العميل من التبديل بين المحتوى والإعلانات.

يستبدل بيان المثال التالي علامتَي EXT-X-CUE-IN وEXT-X-CUE-OUT:

#EXTM3U
#EXT-X-VERSION:6
#EXT-X-TARGETDURATION:6
#EXT-X-MEDIA-SEQUENCE:0

#EXTINF:5.000,
contentorigin.com/1.ts
#EXTINF:5.000,
contentorigin.com/2.ts
#EXT-X-CUE-OUT:15.000
#EXTINF:5.000,
contentorigin.com/3.ts
#EXTINF:5.000,
contentorigin.com/4.ts
#EXTINF:5.000,
contentorigin.com/5.ts
#EXT-X-CUE-IN
#EXTINF:5.000,
contentorigin.com/6.ts
#EXTINF:5.000,
contentorigin.com/7.mp4
#EXTINF:5.000,
contentorigin.com/8.mp4

يعرض المثال التالي بيانًا تم استبداله:

#EXTM3U
#EXT-X-VERSION:6
#EXT-X-TARGETDURATION:6
#EXT-X-MEDIA-SEQUENCE:0

#EXTINF:5.000,
contentorigin.com/1.ts
#EXTINF:5.000,
contentorigin.com/2.ts
#EXTINF:5.000,
#EXT-X-DISCONTINUITY
{... Insert ad segments here ...}
#EXT-X-DISCONTINUITY
#EXTINF:5.000,
contentorigin.com/6.mp4
#EXTINF:5.000,
contentorigin.com/7.mp4
#EXTINF:5.000,
contentorigin.com/8.mp4

إنّ مقاطع إعلانات Google DAI غير مشفّرة. إذا كان المحتوى مشفّرًا، أزِل التشفير عن طريق إدراج العنصر EXT-X-KEY:METHOD=NONE قبل أول مقطع إعلاني لكل فاصل إعلاني. في نهاية الفاصل الإعلاني، أعِد إضافة التشفير عن طريق إدراج EXT-X-KEY مناسب.

تتبَّع وقت بدء الفاصل الإعلاني القادم ومدّته ورقمه التسلسلي.

إنشاء عناوين URL لمقاطع الإعلانات

استبدِل مقاطع المحتوى بين علامتَي EXT-X-DISCONTINUITY بعناوين URL لكل مقطع إعلاني. لتحديد عدد مقاطع الإعلانات التي يجب إدراجها، استخدِم ads.segment_durations.values المقدَّمة في استجابة JSON من واجهة برمجة التطبيقات ATM.

لإنهاء مجموعة إعلانات متسلسلة مبكرًا عند رصد علامة EXT-X-CUE-IN، أضِف المَعلمة d= إلى عنوان URL لمقطع الإعلان الأخير. تؤدي هذه المَعلمة إلى تقصير المقطع لتجنُّب التأثير في المخطط الزمني لمشغّل الفيديو على جهاز العميل.

يجمّع المثال التالي عنوان URL لمقطع إعلان ما قبل التشغيل في البيان. يُرجى العِلم أنّ مقاطع الإعلانات تستخدِم رقمًا تسلسليًا يبدأ من الصفر:

https://dai.google.com/linear/pods/v1/adv/network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/ad_break_id/preroll/ad/0/profile/ENCODING_PROFILE/0.ts?stream_id=SESSION_ID

يجمّع المثال التالي عنوان URL لمقطع إعلان أثناء التشغيل في البيان:

https://dai.google.com/linear/pods/v1/adv/network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/ad_break_id/AD_BREAK_ID/ad/0/profile/ENCODING_PROFILE/0.ts?stream_id=SESSION_ID

يدرج المثال التالي مقاطع إعلانات في البيان:

#EXTM3U
#EXT-X-VERSION:6
#EXT-X-TARGETDURATION:6
#EXT-X-MEDIA-SEQUENCE:0

#EXTINF:5.00,
contentorigin.com/1.ts
#EXTINF:5.00,
contentorigin.com/2.ts
#EXT-X-DISCONTINUITY
#EXTINF:5.00,
https://dai.google.com/linear/pods/v1/adv/network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/ad_break_id/AD_BREAK_ID/ad/0/profile/ENCODING_PROFILE/0.ts?stream_id=SESSION_ID
#EXTINF:5.00,
https://dai.google.com/linear/pods/v1/adv/network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/ad_break_id/AD_BREAK_ID/ad/0/profile/ENCODING_PROFILE/1.ts?stream_id=SESSION_ID
#EXTINF:5.00,
https://dai.google.com/linear/pods/v1/adv/network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/ad_break_id/AD_BREAK_ID/ad/0/profile/ENCODING_PROFILE/2.ts?stream_id=SESSION_ID
#EXT-X-DISCONTINUITY
#EXTINF:5.00,
contentorigin.com/6.mp4
#EXTINF:5.00,
contentorigin.com/7.mp4
#EXTINF:5.00,
contentorigin.com/8.mp4

إنشاء مقاطع اللوحات

لسدّ الفجوة بين الإعلان والمحتوى، أدرِج مقاطع اللوحات. استخدِم مصفوفة slates.segment_durations.values من استجابة JSON لواجهة برمجة التطبيقات ATM لتحديد مدّة كل مقطع لوحة. كرِّر تسلسل مدّات المقاطع حسب الحاجة لملء الفاصل الإعلاني بالكامل.

يجمّع المثال التالي مقطع لوحة:

https://dai.google.com/linear/pods/v1/adv/network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/ad_break_id/AD_BREAK_ID/slate/0/profile/ENCODING_PROFILE/0.ts?stream_id=SESSION_ID

يمثّل slate/0 في المثال رقم تكرار اللوحة. راجِع توافق مشغّل الفيديو على جهاز العميل وإمكانية التخزين المؤقت لتحديد ما إذا كنت تريد البدء من 0 وزيادة هذا الرقم لكل تكرار للوحة، أو إبقائه على 0 لجميع التكرارات.

إدارة العودة إلى المحتوى

بعد إدراج جميع المقاطع من مجموعة إعلانات متسلسلة، اختَر إحدى الطريقتَين التاليتَين للانتقال مرة أخرى إلى مجموعة بث المحتوى:

اختياري: جدولة فاصل إعلاني

لتحسين معدل التعبئة، أرسِل إشعار الفاصل الإعلاني المبكر (EABN) مع مدّة مجموعة الإعلانات المتسلسلة ومَعلمات الاستهداف المخصّصة وبيانات إشارة SCTE-35. لمزيد من التفاصيل، يُرجى الاطّلاع على مقالة إرسال إشعارات الفواصل الإعلانية المبكرة.