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

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

نظرة عامة

توفر حزمة SDK لمستقبل الويب دعمًا أصليًا للفواصل الإعلانية والإعلانات المصاحبة ضمن بث وسائط معين. ويوفّر هذا الإجراء طريقتَين لدمج الفواصل الإعلانية على جهاز الاستقبال: الدمج من جهة العميل والخادم باستخدام الفواصل والمقاطع الفاصلة.

قبل بدء التطوير على الفواصل الإعلانية، يجب أن تكون ملمًا بإعداد جهاز استقبال الويب المخصص. وتضمن واجهة برمجة تطبيقات الفواصل الإعلانية في Cast SDK توفير تجربة متسقة للمستخدمين على جميع الأجهزة التي تعمل بتكنولوجيا Google Cast عندما تكون الإعلانات جزءًا من عملية التشغيل.

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

يعرض هذا الرسم البياني فاصلين إعلانيين، يحتوي كل منهما على إعلانين:

الأحداث

يصف الجدول التالي الأحداث التي يتم تشغيلها عند مواجهة فواصل أثناء التشغيل.

استراحة الحدث الوصف
BREAK_STARTتم الإرسال يتم الإطلاق عندما يبدأ تحميل مقطع الفاصل الأول في الفاصل. الحدث هو cast.framework.events.BreaksEvent.
BREAK_ENDED يتم الإطلاق عند انتهاء آخر فاصل في الفاصل. الحدث هو cast.framework.events.BreaksEvent.
ملاحظة: يتم تنشيط هذا الحدث حتى إذا تخطى المستخدم مقطع الفاصل الأخير في الفاصل لإنهاء الفاصل.
BREAK_CLIP_LOADING يتم الإطلاق عند بدء تحميل مقطع فاصل. الحدث هو cast.framework.events.BreaksEvent.
BREAK_CLIP_STARTED يتم الإطلاق عند بدء مقطع فاصل. الحدث هو cast.framework.events.BreaksEvent.
BREAK_CLIP_ENDED يتم الإطلاق عند انتهاء مقطع فاصل. الحدث هو cast.framework.events.BreaksEvent.
ملاحظة: يتم تنشيط هذا الحدث حتى إذا تخطّى المستخدم مقطعًا مقطوعًا. يُرجى التحقق من السمة endedReason لـ BreaksEvent. لمعرفة الوقت الذي تمّت فيه مشاهدة مقطع الاستراحة، يُرجى الاطّلاع على getBreakClipCurrentTimeSec وgetBreakClipDurationSec في PlayerManager.

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

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

توفر SDK لمتلقي الويب طريقتين لدمج الفواصل الإعلانية في جهاز الاستقبال: الدمج من جهة العميل والدمج من جانب الخادم.

تركيب الإعلانات من جهة العميل

بالنسبة إلى دمج الإعلانات من جهة العميل، والتي يُشار إليها أيضًا على أنها غير مضمّنة، يجب تحديد معلومات الإعلان الضرورية باستخدام كائنات Break وBreakClip عند تحميل الوسائط. المقتطف التالي هو مثال لوظيفة إضافة فواصل إعلانية قبل التشغيل وأثناء التشغيل وبعد التشغيل، حيث تشير المراجع إلى third_party وطرقها إلى أمثلة لوظائف مساعدة قد يحتاج إليها مطوّر البرامج في تطبيقه. ويوضّح المقتطف أيضًا كيف يمكن تنشيط أحداث التتبُّع عندما يشاهد المستخدم مقطع استراحة حتى النهاية من خلال الاستماع إلى حدث BREAK_CLIP_ENDED والتحقق من قيمة endedReason.

/**
 * @param {!cast.framework.messages.MediaInformation} mediaInformation
 */
function addBreakToMedia(mediaInformation) {
  mediaInformation.breakClips = [
  {
    id: 'bc1',
    title: third_party.getBreakClipTitle('bc1'),
    contentId: third_party.getBreakClipUrl('bc1'),
    contentType: third_party.getBreakClipContentType('bc1'),
    posterUrl: third_party.getBreakClipPosterUrl('bc1')
  },
  {
    id: 'bc2'
    ...
  },
  {
    id: 'bc3'
    ...
  },
  {
    id: 'bc4'
    ...
  }];
  mediaInformation.breaks = [
  {
    id: 'b1',
    breakClipIds: ['bc1', 'bc2'],
    position: 0  //pre-roll position
  },
  {
    id: 'b2',
    breakClipIds: ['bc3'],
    position: 10*60 //ten minutes
  },{
    id: 'b3',
    breakClipIds: ['bc4'],
    position: -1  //post-roll position (-1 is only valid client stitching; for server-side ad stitching, exact position is required)
  }];
}

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

playerManager.addEventListener(cast.framework.events.EventType.BREAK_CLIP_ENDED, function(event){
  if(event.endedReason === cast.framework.events.EndedReason.END_OF_STREAM){
    //call your ad tracking code here for break clip watched to completion
  }
});


playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD,
    loadRequestData => {
      addBreakToMedia(loadRequestData.media);
      return loadRequestData;
    });
context.start();

إعلانات VAST

تتوافق حزمة تطوير البرامج (SDK) لمستقبل الويب مع إعلانات VAST القياسية من IAB. لتضمين إعلانات نموذج عرض إعلانات الفيديو في وسائطك، عليك إنشاء كائن vastAdsRequest وإسناده إلى السمة vastAdsRequest في BreakClip. يجب أن يحتوي الكائن vastAdsRequest على الخاصية adsResponse أو السمة adTagUrl المحددة.

/**
 * @param {!cast.framework.messages.MediaInformation} mediaInformation
 */
function addBreakToMedia(mediaInformation) {
  mediaInformation.breakClips = [
  {
    id: 'bc1',
    vastAdsRequest:{
      adTagUrl: 'https://castsample.com/vast?rand=' + Math.floor(Math.random()* 10000)
    }
  }];
}

تُرسِل حزمة تطوير البرامج (SDK) الخاصة بمستقبل الويب طلبًا إلى adTagUrl المحدّد وتحلّل استجابة XML لإنشاء كائن BreakClip. في ما يلي مثال على عنصر BreakClip تم إنشاؤه بواسطة SDK.

{
  "id": "GENERATED:0",
  "contentId": "https://file.mp4",
  "contentType": "video/mp4",
  "title": "Preroll",
  "duration": 10,
  "clickThroughUrl": "https://click"
}

إعلانات VMAP

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

/**
 * @param {!cast.framework.messages.MediaInformation} mediaInformation
 */
function addBreakToMedia(mediaInformation) {
  mediaInformation.vmapAdsRequest = {
    adTagUrl: 'https://castsample.com/vmap?rand=' + Math.floor(Math.random()* 10000)
  };
}

تركيب الإعلانات من جهة الخادم

بالنسبة إلى الدمج من جهة الخادم، الذي يُشار إليه أيضًا بالإعلانات المضمنة، فمن المتوقع أن يقدم الخادم بثًا واحدًا يحتوي على كلٍّ من الوسائط الأساسية والإعلانات. في هذه الحالة، من المتوقّع أن يقدّم مطوّر البرامج duration وcontentType من BreakClip. تم حذف contentUrl. بالإضافة إلى ذلك، يجب ضبط isEmbedded على "صحيح".

/**
 * @param {!cast.framework.messages.MediaInformation} mediaInformation
 */
function addBreakToMedia(mediaInformation) {
  mediaInformation.breakClips = [
  {
    id: 'bc1',
    title: third_party.getBreakClipTitle('bc1'),
    posterUrl: third_party.getBreakClipPosterUrl('bc1'),
    duration: third_party.getBreakClipDuration('bc1')
  },
  {
    id: 'bc2'
    ...
  },
  {
    id: 'bc3'
    ...
  },
  {
    id: 'bc4'
    ...
  }];
  mediaInformation.breaks = [
  {
    id: 'b1',
    breakClipIds: ['bc1', 'bc2'],
    position: 0,
    isEmbedded: true
  },
  {
    id: 'b2',
    breakClipIds: ['bc3', 'bc4'],
    position: 10*60,
    isEmbedded: true
  }];
}

const context = cast.framework.CastReceiverContext.getInstance();
const playerManager = context.getPlayerManager();
playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD,
    loadRequestData => {
      addBreakToMedia(loadRequestData.media);
      return loadRequestData;
    });
context.start();

سلوك الفواصل

سلوك الفاصل التلقائي

  1. وبعد بدء الاستراحة، سيتم وضع علامة isWatched عليها. وإذا نجح المستخدم في التمرير إلى نقطة تسبق الفاصل الإعلاني، يبدأ تشغيل المحتوى كالمعتاد، وسيتم تخطي الفاصل الزمني لاحقًا على أنه قد تمت مشاهدته سابقًا.
  2. إذا اجتاز المستخدم فترة استراحة بدون مشاهدة الفاصل الزمني، سيتم تشغيل آخر استراحة لم يتم تشغيلها بين الموضعَين seekFrom وseekTo قبل بدء تشغيل المحتوى.

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

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

مجموعة فاصل تحميل تحميل العنصر

يتم استدعاء setBreakClipLoadInterceptor قبل التوقف. يتم استدعاء هذه الوظيفة مرة واحدة لكل فاصل مقطع. يمرِّر هذا الكائن BreakClip إلى دالة رد الاتصال.

على سبيل المثال، إذا كان هناك فاصل إعلاني ما قبل التشغيل، يتم طلب setBreakClipLoadInterceptor لإعلان ما قبل التشغيل عند بدء التشغيل. مباشرة بعد انتهاء تشغيل إعلان ما قبل التشغيل، يتم استدعاء setBreakClipLoadInterceptor للفاصل الزمني التالي.

إذا تمت إعادة القيمة "فارغة" أو لم يتم عرض أي قيمة في دالة رد الاتصال على setBreakClipLoadInterceptor، يتم تخطّي مقطع الفاصل. ويتم استدعاء جميع أدوات الاعتراض فور الفاصل.

وباستخدام setBreakClipLoadInterceptor، يمكن تعديل الكائن BreakClip قبل بدء تشغيله.

مجموعةBreakSeekInterceptor

يتم تشغيل setBreakSeekInterceptor بعد عملية بحث وتمرير كائن BreakSeekData إلى دالة رد الاتصال. يحتوي الكائن BreakSeekData على صفيف من الفواصل التي يتم تحديد مواضعها بين وقت رأس التشغيل الحالي ووقت وجهة البحث (على سبيل المثال seekFrom و seekTo). وبعد إجراء عملية البحث للأمام، يكون السلوك التلقائي هو تشغيل الفاصل الأخير الذي لم يتم تشغيله قبل وقت seekTo. وبعد انتهاء الاستراحة، يتم استئناف تشغيل المحتوى من الموضع seekTo.

يسمح أداة الاعتراض هذه بتعديل عناصر BreakClip في الفواصل الإعلانية ذات الصلة.

وإذا أردت تخصيص السلوك، يمكنك تنفيذ الإجراء setBreakSeekInterceptorلإلغاء default behavior. إذا تم تنفيذ السمة setBreakSeekInterceptor، عليك تحديد الفواصل الإعلانية بوضوح لتشغيلها.

  • إذا تم عرض قيمة خالية أو لم يتم عرض أي قيمة من setBreakSeekInterceptor، سيتم تخطي الفاصل.
  • في حال عرض الكائن نفسه الذي تم تمريره إلى دالة رد الاتصال، يتم إلغاء default behavior ويتم تشغيل جميع الفواصل. بالإضافة إلى ذلك، إذا نجح المستخدم في التمرير إلى نقطة سابقة، فسيرى الفواصل حتى لو سبق له مشاهدة تلك الفواصل. إذا لم يتم تطبيق setBreakSeekInterceptor، فسيتم تخطي الفواصل التي تمت مشاهدتها من قبل.

جعل مقاطع الاستراحة قابلة للتخطي

ولجعل المقطع الذي يتضمن فاصلاً قابلاً للتخطي، حدِّد عدد الثواني التي يجب انتظارها قبل أن يصبح المقطع القابل للتخطي قابلاً للتخطي في الكائن BreakClip.

/**
 * @param {!cast.framework.messages.MediaInformation} mediaInformation
 */
function addBreakToMedia(media) {
  media.breakClips = [
  {
    id: 'bc1',
    ...
    whenSkippable: 10 //to allow user to skip break clip from sender after 10 seconds
  }];
}

تخطي الإعلانات تلقائيًا

يمكن تخطي الإعلانات تلقائيًا بدون أي تفاعل من جانب المستخدم. هناك طريقتان لتخطي الإعلانات:

  1. يؤدي ضبط سمة isWatched في الفاصل على "صحيح" إلى تخطي الفاصل تلقائيًا.
    playerManager.addEventListener(cast.framework.events.category.CORE, function(event){
      if(event.type === cast.framework.events.EventType.PLAYER_LOADING){
        let breaks = playerManager.getBreaks();
        for(let i in breaks){
          breaks[i].isWatched = true;
        }
      }
    });
  2. يمكن تخطّي BreakClip عن طريق عرض قيمة فارغة في طلب استدعاء setBreakClipLoadInterceptor.
    playerManager.getBreakManager().setBreakClipLoadInterceptor(breakClip => {
      return null;
    });