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

بررسی اجمالی

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

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

Web Receiver SDK از درج آگهی سمت سرویس گیرنده (CSAI) و درج آگهی درج شده توسط سرور (SSAI) پشتیبانی می کند. تبلیغات بسته شده توسط مشتری را می توان به صورت دستی توسط برنامه تنظیم کرد یا از فایل های قالب VAST و VMAP استخراج کرد. تبلیغات دوخته شده توسط سرور باید به صورت دستی قبل از بارگیری محتوا به عنوان تبلیغات جاسازی شده یا به صورت پویا در حین پخش محتوا به عنوان تبلیغات گسترده تعبیه شده مشخص شوند. پیاده سازی برای هر یک از این انواع تبلیغات به تفصیل در زیر توضیح داده شده است.

دوخت دستی مشتری

وقفه آگهی دستی بسته به مشتری نوعی از استراحت است که توسط مشتری به هم متصل می شود و به صورت دستی توسط برنامه با استفاده از API های SDK مشخص می شود. این نوع تبلیغ در جریان محتوای اصلی تعبیه نشده است. BreakClip باید contentId ارائه دهد که یک URL است که به محتوای آگهی اشاره می کند، contentType که قالب محتوای آگهی را توصیف می کند، و title .

توجه: در برخی موارد لازم است اطلاعات فرمت محتوای آگهی اضافی در ویژگی hlsSegmentFormat برای تبلیغات HLS پخش شده توسط MPL ارائه شود. مشابه راهنمای پشتیبانی از قالب بخش محتوای اصلی، این ویژگی قالب محتوی مورد انتظار برای بخش های تبلیغاتی زیرین را به پخش کننده منتقل می کند.

Break باید isEmbedded و expanded را روی مقدار پیش فرض false تنظیم کرده باشد. position می توان روی یک وقفه تبلیغاتی قبل از پخش ، اواسط فیلم یا پس از پخش تنظیم کرد (به بخش موقعیت یابی استراحت بیشتر مراجعه کنید). هنگام آماده سازی تبلیغ برای پخش، Web Receiver 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.

وسیع

Web Receiver SDK از افزودن تبلیغات استاندارد IAB VAST (الگوی ارائه آگهی ویدیویی) پشتیبانی می کند. در صورت ارائه، الگوی 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 یک عدد صحیح است که برای هر کلیپ شکست VAST جدید ایجاد شده با شروع از 0 1 افزایش می یابد. سپس تبلیغ ایجاد شده به آرایه BreakClip اضافه می شود. سپس هر id کلیپ شکست VAST در Break فعلی با id کلیپ شکست تولید شده مربوطه جایگزین می‌شود. قطعات زیر تغییرات پیام های MEDIA_STATUS مربوط به تبلیغات را قبل و بعد از ورود به چنین وقفه ای نشان می دهد.

توجه: آرایه های BreakClip و Break در BreakManager به روز شده و قابل دسترسی هستند. این اطلاعات در 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

Web Receiver SDK از استاندارد IAB VMAP (فهرست پخش چند آگهی ویدیویی) پشتیبانی می کند. هنگامی که یک VMAP ارائه می‌شود، Web Receiver SDK پاسخ VMAP را تجزیه می‌کند و برای هر ورودی <AdBreak> در پاسخ، اشیاء Break متصل به مشتری ایجاد می‌کند. همچنین BreakClips مناسب را با یک شی vastAdsRequest برای هر ورودی <AdSource> ارائه شده در VMAP ایجاد می کند. برای فعال کردن VMAP برای درج تبلیغات در محتوای شما، برنامه باید یک شی VastAdsRequest ایجاد کند و آن را به ویژگی vmapAdsRequest از MediaInformation در LoadRequestData اختصاص دهد. این تبلیغات باید به صورت استاتیک درج شوند (در قسمت درج آگهی به ادامه مطلب مراجعه کنید). در زیر قطعه ای وجود دارد که ایجاد یک درخواست VMAP را نشان می دهد.

توجه: تنظیم دستی تبلیغات Break و BreakClip در ارتباط با تبلیغات VMAP، درخواست تبلیغ VMAP را لغو می کند. در نتیجه، SDK درخواست تبلیغ VMAP را حذف می‌کند و به‌طور پیش‌فرض از تبلیغات تعیین‌شده دستی در MediaInformation استفاده می‌کند.

// 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 باید مقدار isEmbedded را روی true و expanded set را روی true داشته باشد. این 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;

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

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

نوع خط زمانی	شرح
جدول زمانی تعبیه شده	نمایشی از زمان رسانه ای که از تبلیغاتی که در محتوای اصلی جاسازی شده اند پشتیبانی می کند. هنگامی که یک وقفه تبلیغاتی گسترش نیافته وجود دارد، مدت زمان آن از کل مدت زمان محتوا کم می شود. از سوی دیگر، زمانی که یک وقفه تبلیغاتی گسترده وجود دارد، زمان آن به عنوان بخشی از محتوای اصلی در نظر گرفته می شود.
جدول زمانی دوخته شده	نمایشی از زمان رسانه که از تبلیغاتی پشتیبانی می‌کند که از فایل‌های رسانه خارجی تهیه شده‌اند ( برخی‌های تبلیغاتی VAST و VMAP که به صورت دستی به هم متصل شده‌اند). وقتی اضافه می شود، مدت وقفه تبلیغاتی بخشی از مدت زمان محتوای اصلی نیست.

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

شکل 1: جدول زمانی که برخی از محتوا و 3 وقفه تبلیغاتی آن را نشان می دهد.

شکل 2: جدول زمانی که برخی از محتواها و 3 وقفه تبلیغاتی تعبیه شده در سرور را نشان می دهد.

شکل 3: جدول زمانی که برخی از محتواها و 3 وقفه تبلیغاتی توسعه یافته تعبیه شده با سرور را نشان می دهد.

شکستن موقعیت

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

موقعیت شکست	شرح
پیش رول	یک استراحت تبلیغاتی که قبل از محتوای اصلی پخش می شود. این را با تنظیم breakPosition روی 0 نشان می دهند
اواسط رول	یک استراحت تبلیغاتی که در میان محتوای پخش می شود. این با تنظیم breakPosition روی زمانی مشخص می شود که در آن شروع استراحت بزرگتر از شروع محتوای اصلی باشد و زمان پایان استراحت کمتر از زمان پایان محتوای اصلی باشد.
پس از رول	یک استراحت تبلیغاتی که بعد از محتوای اصلی پخش می شود. این را با تنظیم breakPosition روی -1 برای خطوط زمانی دوخته شده نشان می دهند. برای جدول‌های زمانی تعبیه‌شده، breakPosition باید روی مدت زمان محتوای اصلی که از مدت زمان استراحت کم می‌شود، تنظیم شود. برای محتوای زنده پشتیبانی نمی شود.

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

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

جدول 1: ماتریس قابلیت همکاری تبلیغات

پشتیبانی از ویژگی ها	آگهی دستی دوخته شده توسط مشتری	وسیع	VMAP	تبلیغ تعبیه شده	تبلیغ گسترده تعبیه شده
سازگار با	وسیع	دوخت دستی مشتری	N/A	تعبیه شده گسترش یافته است	تعبیه شده است
جدول زمانی	دوخته شده	دوخته شده	دوخته شده	تعبیه شده است	تعبیه شده است
درج آگهی	ایستا	ایستا	ایستا	ایستا	ایستا، پویا
حذف آگهی
تبلیغ قبل از پخش
تبلیغ میان فیلم
آگهی پس از پخش
رد شدن از آگهی
رهگیر جستجوی شکستن
شکستن گیره بار رهگیر

مناسبت ها

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

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

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

شکل 4 : چرخه حیات رویدادهای شکست.

جدول 2: رویدادهای شکست و توصیف آنها.

رویداد شکست	شرح
BREAK_STARTED	زمانی فعال می شود که زمان رسانه فعلی محتوای اصلی برابر با position یک استراحت تماشا نشده باشد.
BREAK_CLIP_LOADING	فقط زمانی فعال می شود که یک کلیپ شکسته خط زمانی بخیه شده شروع به بارگیری کند.
BREAK_CLIP_STARTED	هنگامی که یک کلیپ استراحت شروع به پخش می کند فعال می شود.
BREAK_CLIP_ENDED	هنگامی که یک کلیپ استراحت به پایان می رسد، پخش می شود. endedReason برای شرایط زیر پر می شود: یک کلیپ شکسته خط زمانی دوخته شده به طور کامل پخش شد. یک کلیپ شکسته خط زمانی دوخته شده به کلیپ استراحت دیگری تبدیل می شود. هر کلیپ استراحتی نادیده گرفته می شود. آخرین کلیپ استراحت به طور کامل در یک استراحت تعبیه شده پس از پخش پخش شد. خطایی رخ داد.
BREAK_ENDED	هنگامی که آخرین کلیپ استراحت در یک استراحت به پایان می رسد پخش می شود.

درج آگهی

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 باشد، پس از وارد کردن، استراحت پخش می شود.

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

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

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

توجه: برنامه‌های گیرنده می‌توانند برای نظارت بر تغییرات MediaStatus در رویدادهای PlayerManager MEDIA_STATUS مشترک شوند.

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

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

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

توجه: در صورت انجام عملیات جستجو پس از اتمام استراحت، اطمینان حاصل کنید که playerState شی MediaStatus به PLAYING قبل از انجام عملیات جستجو تغییر کرده است.

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

رهگیر جستجوی استراحت به برنامه اجازه می دهد تا رفتار جستجو در وقفه های تبلیغاتی را کنترل کند. این تابع زمانی فعال می شود که یک عملیات جستجو درخواست می شود که به دنبال یک یا چند وقفه به جلو یا عقب است. هنگام فراخوانی، BreakSeekData به عنوان پارامتر به تابع callback ارسال می شود. شی BreakSeekData شامل آرایه ای از اشیاء Break است که ویژگی position آنها به عددی بین زمان پخش فعلی تعریف شده به عنوان seekFrom و زمان جستجوی مقصد seekTo تنظیم شده است.

این رهگیر اجازه می دهد تا اشیاء Break در شکست های مربوطه اصلاح شوند. زمانی که رهگیر جستجوی شکست باید با بازگرداندن یک شی BreakSeekData اصلاح شده انتخابی، مشخص کند که کدام وقفه های تبلیغاتی پخش شوند. بازیکن به بازی تمام استراحت های موجود در مقدار برگشتی ادامه می دهد. اگر مقدار null یا چیزی از رهگیر جستجوی شکست برگردانده نشود، شکست از بین می رود.

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

نمونه زیر را برای اجرای ساده رهگیر که رفتار پیش‌فرض برای تماشای تمام وقفه‌های تبلیغاتی جستجو شده به استثنای وقفه‌های قبلاً تماشا شده را لغو می‌کند، ببینید.

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.

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

توجه: برنامه‌های فرستنده وب علاوه بر پیاده‌سازی قطعه بالا، باید request logic اضافه کنند تا به کاربر اجازه رد شدن از تبلیغ را بدهد. این مورد در پلتفرم‌های فرستنده تلفن همراه مورد نیاز نیست زیرا عملکرد توسط SDK ارائه می‌شود.

رد شدن از تبلیغات به صورت برنامه ای

همچنین می‌توان از تبلیغات به‌طور خودکار و بدون هیچ گونه تعامل کاربر صرف‌نظر کرد.

برای رد شدن از یک استراحت کامل از پخش، یک برنامه باید ویژگی 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;
});