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

نظرة عامة

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

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

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

// 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.

// 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.

"breaks": [
  {
    "id": "break_postroll_vast",
    "breakClipIds": [
      "bc_vast"
    ],
    "position": 0,
    "isWatched": false
  }
],
"breakClips": [
  {
    "id": "bc_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"
  }
]

// 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;

// 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.

// 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;

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

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

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

موضع الفاصل

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

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

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

فعاليات

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

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

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

إدراج إعلان

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

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

يتميز إدراج الإعلان الثابت بإضافة البيانات الوصفية ذات الصلة للإعلان قبل إلى إنشاء اللاعبين. يتم توفير هذه المعلومات في MediaInformation من LoadRequestData. على سبيل المثال، يمكن ضبط هذا الإجراء في مرسِل متصل طلب التحميل الأصلي أو إدراجه من خلال تطبيق WebRecipient عن طريق اعتراض طلب "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 (ID3) لمجموعة البث ينشئ العنصرَين 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 حزمة 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;
});