فواصل الإعلانات

نظرة عامة

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

أنواع الإعلانات

توفِّر حزمة تطوير البرامج (SDK) لمستلِم الويب ميزة إدراج الإعلانات من جهة العميل (CSAI) وإدراج الإعلان المدمج من جهة الخادم (SSAI). يمكن ضبط الإعلانات المدمجة من قِبل عميل يدويًا عن طريق التطبيق أو استخراجها من ملفات نماذج VAST وVMAP. يجب تحديد الإعلانات المدمجة بواسطة الخادم يدويًا قبل تحميل المحتوى كإعلانات مضمّنة أو ديناميكيًا أثناء تشغيل المحتوى كإعلانات موسَّعة مضمّنة. وفي ما يلي شرح تفصيلي لعمليات تنفيذ كل نوع من أنواع الإعلانات هذه.

تجميع يدوي للعملاء

الفاصل الإعلاني اليدوي المدمج على جهاز العميل هو نوع من الفواصل الإعلانية يتم دمجها معًا من قِبل العميل، ويتم تحديده يدويًا عن طريق التطبيق باستخدام واجهات برمجة تطبيقات حزمة تطوير البرامج (SDK). هذا النوع من الإعلانات غير مُضمّن في بث المحتوى الرئيسي. يجب أن توفّر السمة BreakClip contentId وهي عنوان URL يشير إلى محتوى الإعلان، وcontentType الذي يصف تنسيق محتوى الإعلان، و title.

يجب أن تحتوي السمة Break على isEmbedded وexpanded على القيمة التلقائية false. يمكن ضبط position على فاصل إعلاني ما قبل التشغيل أو أثناء التشغيل أو ما بعد التشغيل (يمكنك الاطّلاع على مزيد من المعلومات في قسم تحديد موضع الفواصل الإعلانية). أثناء تحضير الإعلان للتشغيل، تنشئ حزمة تطوير البرامج (SDK) لجهاز استقبال الويب مثيل مشغّل آخر لتحميل محتوى الإعلان وتشغيله. تتطلب هذه الفواصل stitched timeline ويجب إضافتها بشكل ثابت (اطّلِع على مزيد من المعلومات في قسم إدراج الإعلان). يوضِّح النموذج التالي تنفيذًا أساسيًا لإعلان تمّ إنشاؤه يدويًا من خلال العميل:

// Create the BreakClip.
let clipClient = new cast.framework.messages.BreakClip('bc_client');
clipClient.title = 'The Ad Title to be displayed during playback';
clipClient.contentId = 'https://example.com/ad.m3u8';
clipClient.contentType = 'application/vnd.apple.mpegurl';

// Optional: Used when HLS ad container formats differ from the main content's.
clipClient.hlsSegmentFormat = cast.framework.messages.HlsSegmentFormat.FMP4;

// Create the Break using the BreakClip id above.
let breakPostrollClient = new cast.framework.messages.Break(
    'break_postroll_client', ['bc_client'], -1);
breakPostrollClient.isEmbedded = false; // Optional: default is false.
breakPostrollClient.expanded = false; // Optional: default is false.

VAST

تتيح حزمة تطوير البرامج (SDK) لمستلِم الويب إضافة إعلانات VAST (VAST) العادية الصادرة عن مكتب IAB. وعند توفير ذلك، يتم تحليل نموذج XML لإنشاء مقطع فاصل لاحق مُدمج من العميل عند إدخال الفاصل.

لإنشاء إعلان نموذج عرض إعلانات الفيديو (VAST)، يجب على تطبيق المُستلِم إنشاء VastAdsRequest وتحديده في السمة BreakClip vastAdsRequest. يجب أن يحتوي الكائن VastAdsRequest على السمة adsResponse (تمثيل سلسلة لنموذج XML نفسه) أو adTagUrl (عنوان URL الذي تتم استضافة نموذج XML فيه). إذا تم تحديد عنوان URL، ستعالج حزمة تطوير البرامج (SDK) عملية جلب النموذج. يتّبع Break التغليف اصطلاحات الإعلانات المدمجة من قِبل العميل. يمكن إضافة هذه الإعلانات إلى جانب إعلانات يدوية تم تركيبها بواسطة العميل في الفاصل نفسه أو في فواصل منفصلة للجزء نفسه من المحتوى. يوضح النموذج التالي التنفيذ الأساسي لإعلان نموذج عرض إعلانات الفيديو (VAST):

// Create the VastAdsRequest.
let vastTemplate = new cast.framework.messages.VastAdsRequest();
vastTemplate.adTagUrl = 'https://example.com/ads.xml'

// Create the BreakClip.
let clipVast = new cast.framework.messages.BreakClip('bc_vast');
clipVast.vastAdsRequest = vastTemplate;

// Create the Break using the BreakClip id above.
let breakPostrollVast = new cast.framework.messages.Break(
    'break_postroll_vast', ['bc_vast'], -1);
breakPostrollVast.isEmbedded = false; // Optional: default is false.
breakPostrollVast.expanded = false; // Optional: default is false.

عند إدخال Break يحتوي على BreakClip VAST، ستجلب حزمة تطوير البرامج (SDK) لجهاز استقبال الويب النموذج اختياريًا، ثم تحلله. أثناء التحليل، ستنشئ حزمة SDK عنصر BreakClip جديدًا وتعبئته بالقيم المستخرَجة من النموذج، مثل contentId وcontentType وtitle وduration وwhenSkippable وclickThroughUrl. تمّ ضبط id لمقطع الفواصل الذي تم إنشاؤه على GENERATED:N حيث يكون N عددًا صحيحًا يزيد بمقدار 1 لكل مقطع فاصل إعلاني جديد على VAST يتم إنشاؤه بدءًا من 0. تتم بعد ذلك إضافة الإعلان الذي تم إنشاؤه إلى مصفوفة BreakClip. يتم بعد ذلك استبدال كل مقطع من فواصل VAST id في Break الحالي بالمقطع id المقابل له الذي تم إنشاؤه. توضّح المقتطفات أدناه التغييرات في رسائل MEDIA_STATUS التي تتعلّق بالإعلانات قبل إدخال هذا الفاصل وبعده.

معلومات عن Break وBreakClip قبل إدخال فاصل إعلاني باستخدام إعلانات نموذج عرض إعلانات فيديو (VAST).

"breaks": [
  {
    "id": "break_postroll_vast",
    "breakClipIds": [
      "bc_vast"
    ],
    "position": 0,
    "isWatched": false
  }
],
"breakClips": [
  {
    "id": "bc_vast"
  }
]

معلومات Break وBreakClip بعد إدخال فاصل إعلاني باستخدام إعلانات نموذج عرض إعلانات فيديو (VAST).

"breaks": [
  {
    "id": "break_postroll_vast",
    "breakClipIds": [
      "GENERATED:0"
    ],
    "position": 0,
    "isWatched": true
  }
],
"breakClips": [
  {
    "id": "bc_vast"
  },
  {
    "id": "GENERATED:0",
    "contentId": "https://example.com/break-clip-1.mpd",
    "contentType": "application/dash+xml",
    "title": "Ad Title Extracted from Template",
    "duration": 10,
    "whenSkippable": 5,
    "clickThroughUrl": "https://example.com/ad-target"
  }
]

VMAP

تتوافق حزمة تطوير البرامج (SDK) لأجهزة استقبال الويب مع معيار VMAP (قوائم تشغيل الفيديو المتعددة) الصادر عن مكتب IAB. عند توفير VMAP، ستحلل حزمة تطوير البرامج (SDK) لاستقبال الويب استجابة VMAP وتنشئ كائنات Break مدمجة بواسطة العميل لأي إدخالات <AdBreak> في الرد. وستنشئ أيضًا الدالة BreakClips المناسبة باستخدام كائن vastAdsRequest لكل إدخال <AdSource> متوفر في VMAP. لتفعيل VMAP من أجل إدراج إعلانات في المحتوى الخاص بك، يجب أن ينشئ التطبيق عنصر VastAdsRequest وتخصيصه للسمة vmapAdsRequest في MediaInformation في LoadRequestData. يجب إدراج هذه الإعلانات بشكل ثابت (اطّلِع على مزيد من المعلومات في القسم إدراج الإعلان). يوجد أدناه مقتطف يوضح إنشاء طلب VMAP.

// Create the VastAdsRequest.
let vastTemplate = new cast.framework.messages.VastAdsRequest();
vastTemplate.adTagUrl = 'https://example.com/vmap.xml'

// Add it to the MediaInformation of the LoadRequest.
loadRequestData.media.vmapAdsRequest = vastTemplate;

مضمَّن

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

يجب أن توفر السمة BreakClip duration لمحتوى الإعلان، بالإضافة إلى title. يجب ضبط السمة Break على isEmbedded على true و expanded على false. يمكن ضبط position كفاصل إعلاني ما قبل التشغيل أو إعلان أثناء التشغيل. يمكن استخدام الفواصل الإعلانية ما بعد التشغيل بقيم position دقيقة إيجابية. يمكنك الاطّلاع على مزيد من المعلومات حول هذا الموضوع في القسم موضع الفواصل. وعند بدء تشغيل الإعلان، ستواصل "حزمة تطوير البرامج (SDK) لاستقبال الويب" تشغيل البث أثناء تضمين شرائح الإعلانات فيه. لا توجد آلية تحميل إضافية لهذا النوع من الإعلانات. يتم عرض البيانات الوصفية ذات الصلة للإعلان ذات الصلة عندما يكون رأس التشغيل ضمن النطاق الزمني للفاصل. تتطلب هذه الفواصل embedded timeline ويجب إضافتها بشكل ثابت (اطّلِع على مزيد من المعلومات في قسم إدراج الإعلان). يُظهر النموذج أدناه تنفيذًا أساسيًا لإعلان embedded.

// Create the BreakClip.
let clipEmbedded = new cast.framework.messages.BreakClip('bc_embedded');
clipEmbedded.title = 'The Ad Title to be displayed during playback';
clipEmbedded.duration = 15;

// Create the Break using the BreakClip id above.
let breakPrerollEmbedded = new cast.framework.messages.Break(
    'break_preroll_embedded', ['bc_embedded'], 0);
breakPrerollEmbedded.isEmbedded = true;
breakPrerollEmbedded.expanded = false; // Optional: default is false.

تم توسيع المضمنة

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

يجب أن توفر السمة BreakClip duration لمحتوى الإعلان، بالإضافة إلى title. يجب ضبط Break على true وexpanded على true.isEmbedded يمكن ضبط position كفاصل إعلاني ما قبل التشغيل أو إعلان أثناء التشغيل. يمكن استخدام الفواصل الإعلانية ما بعد التشغيل بقيم position موجبة. يمكنك الاطّلاع على مزيد من المعلومات حول هذا الموضوع في القسم موضع الفواصل. وعند بدء تشغيل الإعلان، ستواصل "حزمة تطوير البرامج (SDK) لاستقبال الويب" تشغيل البث أثناء تضمين شرائح الإعلانات فيه. لا توجد آلية تحميل إضافية لهذا النوع من الإعلانات. يتم عرض البيانات الوصفية ذات الصلة للإعلان ذات الصلة عندما يكون رأس التشغيل ضمن النطاق الزمني للفاصل. تتطلّب هذه الفواصل embedded timeline ويمكن إضافتها إما بشكل ثابت أو ديناميكي (يمكنك الاطّلاع على مزيد من المعلومات في قسم إدراج الإعلان). يوضِّح النموذج التالي تنفيذًا أساسيًا لإعلان embedded expanded:

// Create the BreakClip.
let clipEmbeddedExpanded =
    new cast.framework.messages.BreakClip('bc_embedded_expanded');
clipEmbeddedExpanded.title = 'The Ad Title to be displayed during playback';
clipEmbeddedExpanded.duration = 15;

// Create the Break using the BreakClip id above.
let breakPrerollEmbeddedExpanded = new cast.framework.messages.Break(
    'break_preroll_embedded_expanded', ['bc_embedded_expanded'], 0);
breakPrerollEmbeddedExpanded.isEmbedded = true;
breakPrerollEmbeddedExpanded.expanded = true;

أنواع المخطط الزمني للّاعب

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

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

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

المخطط الزمني للإعلانات التي صممها العميل
الشكل 1: المخطط الزمني الذي يمثّل بعض المحتوى والفواصل الإعلانية الثلاث التي تم تركيبها من قِبل العميل.


المخطط الزمني للإعلانات المضمّنة المدمَجة من خلال الخادم
الشكل 2: المخطط الزمني الذي يمثّل بعض المحتوى والفواصل الإعلانية الثلاث المضمّنة في الخادم.


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

تحديد موضع الفاصل

تتيح "حزمة تطوير البرامج (SDK) لأجهزة استقبال الويب" لمطوّري البرامج تحديد مكان الفواصل الإعلانية من خلال ضبط السمة position في Break. تتوافق هذه القيمة مع وقت تشغيل الوسائط للمحتوى الرئيسي ويمكن استخدامها لإنشاء فواصل إعلانية pre-roll وmid-roll وpost-roll. يتم تعريفها على النحو التالي:

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

مصفوفة إمكانية التشغيل التفاعلي

وكنقطة مرجعية سريعة، يعرض الجدول 1 نظرة عامة على أنواع الإعلانات ومدى توافقها مع الميزات المرتبطة بالإعلانات.

الجدول 1: مصفوفة إمكانية التشغيل التفاعلي للإعلانات
دعم الميزات إعلان تم تركيبه يدويًا بواسطة العميل VAST VMAP إعلان مضمّن إعلان موسّع مضمَّن
متوافقة مع VAST تجميع يدوي للعملاء لا ينطبق تم توسيع المضمنة مضمَّن
المخطط الزمني مخيَّط مخيَّط مخيَّط مضمَّن مضمَّن
إدراج إعلان ثابت ثابت ثابت ثابت ثابت، ديناميكي
إزالة الإعلان
إعلان ما قبل التشغيل
إعلان أثناء التشغيل
إعلان ما بعد التشغيل
تخطّي الإعلان
أداة اعتراض محاولة التصويب
اعتراض تحميل مقطع فواصل

فعاليات

عند وقوع أحداث الفواصل الرئيسية، ستعمل حزمة تطوير البرامج (SDK) على إرسال الأحداث من النوع BreaksEvent. يمكن لتطبيق الاستقبال الاشتراك فيها باستخدام واجهة برمجة التطبيقات PlayerManager addEventListener.

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

يتم إدراج أنواع الأحداث في الجدول 2 مع وصف تفصيلي عن وقت تنشيطها.

مراحل نشاط أحداث الإيقاف
الشكل 4: مراحل نشاط أحداث الفواصل الإعلانية.
الجدول 2: أحداث الفواصل الإعلانية وأوصافها
حدث استراحة الوصف
BREAK_STARTED يتم تنشيطها عندما يساوي وقت الوسائط الحالي للمحتوى الرئيسي position من الفاصل الإعلاني الذي لم تتم مشاهدته.
BREAK_CLIP_LOADING يتم تنشيطها فقط عند بدء تحميل مقطع فواصل إعلانية في مخطط زمني مجمّع.
BREAK_CLIP_STARTED يتم إطلاقه عندما يبدأ تشغيل مقطع فاصل.
BREAK_CLIP_ENDED يتم تنشيطها عند انتهاء مقطع استراحة. ستتم تعبئة endedReason للحالات التالية:
  • مقطع يتم تشغيله بالكامل بمخطط زمني مُدمَج.
  • ينتقل مقطع فاصل المخطط الزمني المدمَج إلى مقطع فاصل آخر.
  • يتم تخطّي أي مقطع فواصل إعلانية.
  • يتم تشغيل آخر مقطع للفاصل الإعلاني بالكامل في فواصل مضمّنة بعد التشغيل.
  • حدث خطأ.
BREAK_ENDED يتم تنشيطه عند انتهاء آخر مقطع استراحة في الفاصل.

إدراج إعلان

تتيح حزمة تطوير البرامج (SDK) للإرسال للتطبيقات إمكانية إدراج الإعلانات وإزالتها في أوقات مختلفة من جلسة البث. نوعا إدراج الإعلان هما ثابت وديناميكي. تتطلب ميزة إدراج الإعلان الثابت أن يتم تحديد الإعلانات في LoadRequestData قبل إنشاء المشغّل. تستفيد ميزة إدراج الإعلان الديناميكي من واجهة برمجة التطبيقات BreakManager addBreak لإدراج فواصل في المحتوى الذي سبق تحميله. يتوافق كل نوع من أنواع طرق الإدراج مع أنواع إعلانات معيّنة. يتم توفير نظرة عامة على التوافق في مصفوفة إمكانية التشغيل التفاعلي.

إدراج إعلانات ثابتة

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

const context = cast.framework.CastReceiverContext.getInstance();
const playerManager = context.getPlayerManager();

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD, loadRequestData => {

  // Create the BreakClip.
  let clipClient = new cast.framework.messages.BreakClip('bc_client');
  clipClient.title = 'The Ad Title to be displayed during playback';
  clipClient.contentId = 'https://example.com/ad.mp4';
  clipClient.contentType = 'video/mp4';

  // Create the Break using the BreakClip id above.
  let breakPostrollClient = new cast.framework.messages.Break(
      'break_postroll_client', ['bc_client'], -1);

  // Set the ad information in the load request data.
  let media = loadRequestData.media;
  media.breakClips = [clipClient];
  media.breaks = [breakPostrollClient];

  return loadRequestData;
});

إدراج إعلان ديناميكي

تتسم ميزة الإدراج الديناميكي للإعلان عن طريق ضبط فاصل إعلاني أثناء تشغيل المحتوى. ويتم ذلك من خلال الحصول على مثيل من BreakManager واستدعاء واجهة برمجة التطبيقات addBreak. يتطلب هذا الإجراء مَعلمتَين على الأقل، هما سمة موسّعة مضمَّنة Break ومصفوفة من مصفوفة BreakClip. تم تضمين خاصية ثالثة اختيارية لفرض إرسال التغييرات إلى المرسِلين المتصلين من خلال بث MediaStatus عند الضبط على true. عند إضافة فواصل وفواصل للمقاطع، يجب أن تكون أرقام التعريف المطابقة فريدة. لا يمكن إضافة هذه الإعلانات إلا بعد إنشاء المشغّل. تعمل حزمة تطوير البرامج (SDK) لأداة استقبال الويب على تنشيط حدث PLAYER_LOADING بعد إنشاء المشغّل. اطّلِع على النموذج أدناه الذي يعرض الاستخدام في معالِج أحداث يستجيب للتغييرات في البيانات الوصفية لرقم التعريف 3 لمصدر البيانات وينشئ عنصرَي Break وBreakClip لإدراجه في المخطط الزمني.

const context = cast.framework.CastReceiverContext.getInstance();
const playerManager = context.getPlayerManager();
const breakManager = playerManager.getBreakManager();

playerManager.addEventListener(cast.framework.events.EventType.ID3, (event) => {

  // Create the BreakClip.
  let clipEmbeddedExpanded = parseBreakClipFromData(event.segmentData);
  let breakEmbeddedExpanded = parseExpandedBreakFromData(event.segmentData);

  // Add the break and break clip.
  breakManager.addBreak(breakEmbeddedExpanded, [clipEmbeddedExpanded]);
});

إزالة الإعلان الديناميكي

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

const context = cast.framework.CastReceiverContext.getInstance();
const playerManager = context.getPlayerManager();
const breakManager = playerManager.getBreakManager();

breakManager.removeBreakById('break_midroll_embedded_expanded');

سلوك الفواصل الإعلانية

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

السلوك التلقائي للفاصل الإعلاني

عند إدخال Break من خلال التشغيل العادي أو البحث عن Break، ستقيّم حزمة SDK ما إذا كان المستخدم قد اطّلع عليها من قبل أم لا، وذلك من خلال التحقّق من السمة isWatched. عند إنشاء الفاصل، تكون القيمة التلقائية للفاصل الإعلاني لهذا الموقع هي false. إذا كانت السمة true، لن يتم تشغيل الفاصل عند إدخاله وسيستمر تشغيل المحتوى الرئيسي. إذا كانت السمة false، سيتم تشغيل الفاصل عند إدخاله.

عند البحث عن الفواصل السابقة، تحصل طريقة التنفيذ التلقائية على جميع عناصر Break التي تقع position بين قيمتَي seekFrom وseekTo لعملية البحث. من قائمة الفواصل الإعلانية هذه، ستشغِّل حزمة تطوير البرامج (SDK) Break التي يكون position الخاص بها هو الأقرب إلى قيمة seekTo والتي تم ضبط سمة isWatched الخاصة بها على false. بعد ذلك، سيتم ضبط سمة isWatched الخاصة بهذا الفاصل على true ويبدأ المشغّل تشغيل مقاطع الفواصل. بعد مشاهدة الفاصل، سيُستأنف تشغيل المحتوى الرئيسي من الموضع seekTo. في حال عدم توفُّر فاصل من هذا النوع، لن يتم تشغيل أي فاصل إعلاني وسيتم استئناف تشغيل المحتوى الرئيسي في الموضع seekTo.

أثناء تشغيل الفواصل الإعلانية، ستبث حزمة تطوير البرامج (SDK) أي تحديثات ذات صلة لتطبيقات المُرسِلين المتصلين في MediaStatus. ستستخدم هذه التطبيقات عمليات البث لتحديث واجهة المستخدم الخاصة بها لعرض الإعلانات من خلال قراءة الخاصية breakStatus. ويتم تحديد هذه الخاصية أثناء تشغيل الفواصل الإعلانية فقط.

يمكن لتطبيقات الاستقبال أيضًا طلب معلومات مباشرةً عن موضع رأس التشغيل في ما يتعلق بالوقت الحالي لـ BreakClip الذي يظهر من خلال طلب PlayerManager getBreakClipCurrentTimeSec. وبالمثل، يمكن للتطبيقات الاستعلام عن مدة BreakClip الحالية من خلال طلب الزحف إلى getBreakClipDurationSec.

سلوك الفواصل المخصّصة

يمكن تعديل السلوك التلقائي للفواصل والمقاطع باستخدام طريقتَي setBreakClipLoadInterceptor وsetBreakSeekInterceptor الواردتَين في BreakManager.

أداة اعتراض محاولة التصويب

يسمح عنصر اعتراض محاولة الفاصل للتطبيق بالتحكّم في سلوك البحث عن الفواصل الإعلانية. يتم تشغيل الدالة عندما يتم طلب عملية بحث تتقدم للأمام أو للخلف عبر فاصل واحد أو أكثر. عند استدعاء الدالة، يتم تمرير BreakSeekData كمَعلمة إلى دالة رد الاتصال. يحتوي الكائن BreakSeekData على مصفوفة من الكائنات Break التي تم ضبط السمة position فيها على عدد يتراوح بين وقت التشغيل الحالي المحدّد على النحو التالي: seekFrom ووقت الوجهة:seekTo.

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

يمكنك الاطّلاع على النموذج أدناه لتنفيذ عملية بسيطة لاعتراض البيانات، ما يؤدي إلى إلغاء السلوك التلقائي لمشاهدة جميع الفواصل الإعلانية التي تتم المطالبة بها باستثناء الفواصل التي سبق أن تمت مشاهدتها.

const context = cast.framework.CastReceiverContext.getInstance();
const playerManager = context.getPlayerManager();
const breakManager = playerManager.getBreakManager();

breakManager.setBreakSeekInterceptor((breakSeekData) => {

  // Filter the breaks array by removing watched breaks.
  const unwatchedBreaks =
      breakSeekData.breaks.filter(adBreak => !adBreak.isWatched);
  breakSeekData.breaks = unwatchedBreaks;

  return breakSeekData;
});

أداة اعتراض تحميل المقاطع

وباستخدام اعتراض تحميل مقطع الفاصل، يمكن تعديل عنصر BreakClip قبل بدء تشغيله.

يتم استدعاء أداة اعتراض تحميل مقاطع الفاصل فقط عند استخدام فواصل المخطّط الزمني المُدمجة ويمكن ضبطها باستخدام setBreakClipLoadInterceptor. قبل إدخال Break، يتم استدعاء أداة الاعتراض مرة واحدة لكل فرد BreakClip تم تحديده في ذلك الفاصل. تمرِّر حزمة تطوير البرامج (SDK) عنصر BreakClip الأصلي كمَعلمة لدالة استدعاء الدالة. يمكن للتطبيق بعد ذلك تعديل BreakClip هذا وإعادة إرساله كي تتمكن حزمة تطوير البرامج (SDK) من جلب مقطع الفاصل وعرضه مع الإعدادات المعدّلة. إذا تم إرجاع null أو لم يتم عرض أي محتوى، يتم تخطي مقطع الفاصل.

يمكنك الاطّلاع أدناه على مثال يعدِّل contentUrl لمقاطع الفواصل باستخدام دالة تستدعي getUrlFromClipId حيث يتم تعيين id من BreakClip إلى عنوان URL.

const context = cast.framework.CastReceiverContext.getInstance();
const playerManager = context.getPlayerManager();
const breakManager = playerManager.getBreakManager();

breakManager.setBreakClipLoadInterceptor(
    (breakClip, breakClipLoadInterceptorContext) => {

  // Obtains the URL of a break clip id from a function call.
  breakClip.contentUrl = getUrlFromClipId(breakClip.id);

  return breakClip;
});

تخطي الإعلان

توفّر حزمة تطوير البرامج (SDK) لأداة استقبال الويب واجهات برمجة تطبيقات لتخطّي الفواصل الإعلانية ومقاطع الفواصل الإعلانية الفردية داخل الفاصل الإعلاني. تسمح حزمة SDK للمستخدمين اختياريًا بتخطي مقاطع الفواصل من خلال التفاعل مع تطبيقات المرسل أو أجهزة العرض الذكية.

مقاطع الفواصل القابلة للتخطي التي يجريها المستخدم

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

// Create the BreakClip.
let clip = new cast.framework.messages.BreakClip('bc');
clip.title = 'The Ad Title to be displayed during playback';
clip.whenSkippable = 10; // Users can skip the clip after 10 seconds of playback.

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

تخطّي الإعلانات آليًا

ويمكن أيضًا تخطّي الإعلانات تلقائيًا بدون أي تفاعل من المستخدم.

لتخطي فاصل زمني كامل عن التشغيل، يجب أن يضبط التطبيق السمة isWatched في Break على true. يمكن إجراء ذلك في أي وقت أثناء تسلسل التحميل أو تشغيل المحتوى. ويقيّم المشغّل السمة isWatched عندما يتم تحديد position لفاصل استراحة في الوقت الحالي للمحتوى الرئيسي. عند هذه المرحلة، سيحدد اللاعب ما إذا كان يجب إدخال فاصل إعلاني أم لا. يمكنك الاطّلاع أدناه على النموذج الذي يعرض كل الفواصل ويعدّل القيمة أثناء تحميل المشغّل.

const context = cast.framework.CastReceiverContext.getInstance();
const playerManager = context.getPlayerManager();
const breakManager = playerManager.getBreakManager();

playerManager.addEventListener(cast.framework.events.EventType.PLAYER_LOADING,
    (event) => {

  // Obtain the breaks and iterate through each item to skip all ad breaks.
  let breaks = breakManager.getBreaks();
  breaks.forEach((brk) => {
    brk.isWatched = true;
  });
});

لتخطّي مقطع فاصل معيّن آليًا، يجب استخدام أداة اعتراض تحميل مقاطع الفواصل. من خلال عرض null أو عدم عرض قيمة في دالة رد الاتصال، سيتم تخطي المقطع في ذلك الفاصل.

const context = cast.framework.CastReceiverContext.getInstance();
const playerManager = context.getPlayerManager();
const breakManager = playerManager.getBreakManager();

breakManager.setBreakClipLoadInterceptor(
      (breakClip, breakClipLoadInterceptorContext) => {
  return null;
});