خرابی های تبلیغاتی

نمای کلی

Web Receiver SDK دارای پشتیبانی بومی برای وقفه های تبلیغاتی و تبلیغات همراه در یک جریان رسانه ای معین است. APIهایی را برای تنظیم موقعیت آگهی، منبع آگهی و رفتار وقفه های تبلیغاتی و کلیپ های شکست مرتبط با آنها ارائه می دهد. در این راهنما، Break به بازه‌ای برای پخش شامل یک یا چند آگهی یا بامپر اشاره دارد و هر آگهی یا بامپر به عنوان BreakClip نامیده می‌شود. این وقفه‌ها به رسانه‌ای که در حال بارگیری یا پخش هستند مرتبط هستند.

انواع تبلیغات

Web Receiver 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;

انواع جدول زمانی بازیکن

هنگام ایجاد یک نمونه پخش کننده، Web Receiver SDK نوع خط زمانی را برای پشتیبانی از پخش تبلیغات در حین پخش محتوا انتخاب می کند. هر خط زمانی خاصی را قادر می‌سازد تا انواع وقفه‌های تبلیغاتی اضافه شود. نوع خط زمانی توسط انواع تبلیغات موجود در طول زمان بارگذاری در MediaInformation LoadRequestData تعیین می شود. اگر وقفه‌های تبلیغاتی تعبیه‌شده وجود داشته باشد، خط زمانی embedded انتخاب می‌شود. اگر وقفه های تبلیغاتی دوخته شده توسط مشتری وجود داشته باشد، جدول زمانی stitched انتخاب می شود. در صورتی که هیچ تبلیغاتی وجود نداشته باشد، SDK به طور پیش‌فرض از جدول زمانی embedded استفاده می‌کند. پس از انتخاب جدول زمانی، نمی توان آن را برای آیتم رسانه فعلی تغییر داد. جدول زیر شرح مفصلی از هر جدول زمانی ارائه می دهد.

شکل های 1 تا 3 در زیر برخی از محتواها را با انواع مختلف تبلیغات و مقادیر جدول زمانی مربوطه آنها نشان می دهد. محتوا با یک شکست قبل از پخش شامل دو کلیپ استراحت و وقفه های میان فیلم و پس از پخش حاوی یک کلیپ استراحت پیکربندی شده است. زمان ساعت دیواری از زمان شروع پخش محتوا، زمان رسانه محتوای اصلی، و زمان پخش کلیپ استراحت در حال حاضر در زیر هر شکل تراز شده است.

شکستن موقعیت

Web Receiver SDK به توسعه دهندگان این امکان را می دهد تا با تنظیم ویژگی position Break ، محل وقفه های تبلیغاتی را مشخص کنند. این مقدار مربوط به زمان رسانه محتوای اصلی است و می‌توان از آن برای ایجاد وقفه‌های تبلیغاتی pre-roll ، mid-roll و post-roll استفاده کرد. این موارد به شرح زیر تعریف می شوند:

ماتریس قابلیت همکاری

به عنوان یک نقطه مرجع سریع، جدول 1 یک نمای کلی از انواع تبلیغات و سازگاری آنها با ویژگی های مرتبط با تبلیغات را نشان می دهد.

رویدادها

هنگامی که رویدادهای شکست کلید رخ می دهد، SDK بازیگران رویدادهایی از نوع BreaksEvent را ارسال می کند. یک برنامه گیرنده می تواند با استفاده از PlayerManager addEventListener API مشترک آنها شود.

از این رویدادها می توان برای تجزیه و تحلیل و ردیابی پخش آگهی استفاده کرد. وقتی از تبلیغات VMAP (فهرست پخش چند آگهی ویدیویی) و VAST (الگوی ارائه آگهی ویدیویی) استفاده می شود، هر رویداد ردیابی استاندارد ارائه شده در پاسخ ها به طور خودکار توسط SDK ارسال می شود.

انواع رویداد در جدول 2 همراه با شرح مفصلی در مورد زمان شلیک آنها ذکر شده است.

درج آگهی

Cast SDK برنامه‌ها را قادر می‌سازد تا تبلیغات را در لحظات مختلف یک جلسه پخش، درج و حذف کنند. دو نوع درج آگهی استاتیک و پویا هستند. درج آگهی ایستا مستلزم آن است که تبلیغات در LoadRequestData قبل از ایجاد پخش کننده مشخص شود. درج آگهی پویا از BreakManager addBreak API برای درج شکست در محتوای بارگیری شده از قبل استفاده می کند. هر نوع روش درج با انواع خاصی از تبلیغات سازگار است. یک نمای کلی سازگاری در ماتریس قابلیت همکاری ارائه شده است.

درج آگهی ایستا

درج آگهی ایستا با افزودن ابرداده آگهی مربوطه قبل از ایجاد بازیکن مشخص می شود. این اطلاعات در MediaInformation LoadRequestData ارائه شده است. به عنوان مثال، این می تواند در درخواست بارگیری اصلی یک فرستنده متصل تنظیم شود یا می تواند توسط برنامه گیرنده وب با رهگیری درخواست LOAD درج شود. هنگامی که LoadRequestData برای پردازش به Web Receiver 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 API انجام می شود. این حداقل به دو پارامتر نیاز دارد، یک Break توسعه یافته تعبیه شده و یک آرایه از BreakClip . یک ویژگی سوم اختیاری برای ارسال اجباری تغییرات به فرستنده های متصل از طریق پخش MediaStatus در صورت تنظیم روی true گنجانده شده است. هنگام افزودن وقفه ها و کلیپ های شکست، شناسه های مربوطه باید منحصر به فرد باشند. این تبلیغات فقط زمانی می توانند اضافه شوند که پخش کننده ایجاد شود. پس از ایجاد پخش‌کننده، SDK گیرنده وب، رویداد PLAYER_LOADING را فعال می‌کند. نمونه زیر را ببینید که استفاده در یک کنترل کننده رویداد را نشان می دهد که به تغییرات در فراداده 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 یک رفتار پیش‌فرض را برای زمانی که بازیکن وارد و خارج می‌شود، تعریف می‌کند و راهی برای سفارشی‌سازی بیشتر آن با استفاده از برخی از APIهای ارائه شده در BreakManager ارائه می‌کند.

رفتار شکست پیش فرض

هنگامی که یک Break از طریق پخش منظم یا با جستجوی بیش از یک Break وارد می شود، SDK با بررسی ویژگی isWatched ارزیابی می کند که آیا کاربر قبلاً آن را دیده است یا خیر. هنگام ایجاد، مقدار پیش‌فرض یک break برای این ویژگی false است. اگر ویژگی true باشد، پس از وارد شدن، وقفه پخش نمی‌شود و محتوای اصلی به پخش ادامه می‌دهد. اگر ویژگی false باشد، پس از وارد کردن، استراحت پخش می شود.

هنگام جستجوی وقفه های گذشته، پیاده سازی پیش فرض تمام آیتم های Break را که position آنها بین مقادیر seekFrom و seekTo عملیات جستجو قرار دارد، به دست می آورد. از این فهرست شکست‌ها، SDK Break را پخش می‌کند که position آن به مقدار seekTo نزدیک‌تر است و ویژگی isWatched آن روی false تنظیم شده است. سپس ویژگی isWatched آن break روی true تنظیم می شود و پخش کننده شروع به پخش کلیپ های استراحت خود می کند. پس از تماشای استراحت، محتوای اصلی پخش از موقعیت seekTo از سر گرفته می شود. اگر چنین وقفه ای وجود نداشته باشد، هیچ وقفه ای پخش نمی شود و محتوای اصلی در موقعیت seekTo پخش را از سر می گیرد.

در طول پخش موقت، SDK هرگونه به‌روزرسانی مربوطه را برای برنامه‌های فرستنده متصل در MediaStatus پخش می‌کند. این برنامه‌ها از پخش‌ها برای به‌روزرسانی رابط کاربری تبلیغاتی خود با خواندن ویژگی breakStatus استفاده می‌کنند. این ویژگی فقط در هنگام پخش استراحت تعریف می شود.

برنامه‌های گیرنده همچنین می‌توانند مستقیماً اطلاعات مربوط به موقعیت هد پخش را با توجه به زمان فعلی BreakClip که با تماس با PlayerManager getBreakClipCurrentTimeSec نشان داده شده است، استعلام کنند. به طور مشابه، برنامه‌ها می‌توانند مدت زمان BreakClip فعلی را با فراخوانی getBreakClipDurationSec پرس و جو کنند.

رفتار شکست سفارشی

رفتار پیش‌فرض وقفه‌ها و کلیپ‌های شکست را می‌توان با استفاده از متدهای setBreakClipLoadInterceptor و setBreakSeekInterceptor که در BreakManager ارائه شده است، تغییر داد.

شکستن دنبال رهگیر

رهگیر جستجوی استراحت به برنامه اجازه می دهد تا رفتار جستجو در وقفه های تبلیغاتی را کنترل کند. این تابع زمانی فعال می شود که یک عملیات جستجو درخواست می شود که به دنبال یک یا چند وقفه به جلو یا عقب است. هنگام فراخوانی، BreakSeekData به عنوان پارامتر به تابع callback ارسال می شود. شی BreakSeekData شامل آرایه ای از اشیاء Break است که ویژگی position آنها به عددی بین زمان پخش فعلی تعریف شده به عنوان seekFrom و زمان seekTo مقصد 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 را به عنوان پارامتر تابع callback ارسال می کند. سپس برنامه می تواند این BreakClip تغییر داده و آن را برگرداند تا SDK بتواند کلیپ شکستن را با پیکربندی به روز شده واکشی و نمایش دهد. اگر null یا چیزی برگردانده نشد، کلیپ break از روی آن صرفنظر می شود.

نمونه‌ای را در زیر ببینید که 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;
});

رد شدن از تبلیغات

Web Receiver SDK APIهایی را برای پرش از وقفه‌های تبلیغاتی و کلیپ‌های انفرادی در یک استراحت تبلیغاتی فراهم می‌کند. 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 یا عدم برگرداندن یک مقدار در تابع callback، کلیپ در آن شکست حذف می شود.

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

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