הפסקות למודעות

סקירה כללית

ה-SDK של מכשיר ה-Web קבלה כולל תמיכה מותאמת להפסקות למודעות ולמודעות נלוות בזרם מדיה נתון. היא מספקת ממשקי API להגדרת מיקום המודעה, מקור המודעה וההתנהגות של הפסקות למודעות ושל הקליפים מההפסקות למודעות. במדריך הזה 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;

סוגי ציר הזמן של הנגן

כשיוצרים מופע של נגן, ב-WebChromeOS SDK בוחרים סוג ציר זמן תמיכה בהפעלת מודעות במהלך הפעלת תוכן. כל ציר זמן מפעיל מודעות מסוימות שיש להוסיף את סוגי ההפסקות. סוג ציר הזמן נקבע לפי סוגי מודעות שקיימים בזמן הטעינה MediaInformation של LoadRequestData. אם קיימות הפסקות מוטמעות למודעות, ציר הזמן embedded נבחר. אם המיקום תפירה על ידי הלקוח הפסקות למודעות, נבחר ציר הזמן stitched. אם אין מודעות, ברירת המחדל של ה-SDK היא embedded בציר הזמן. אחרי שבוחרים את ציר הזמן, אי אפשר לשנות אותו כרגע קובץ מדיה. הטבלה הבאה מספקת תיאור מפורט של כל ציר זמן.

איורים 1 עד 3 שבהמשך ממחישים תוכן מסוים עם סוגי מודעות שונים בערכי ציר הזמן המתאימים. התוכן מוגדר עם הפסקה לפני הסרטון (pre-roll) שכולל שני קליפים של הפסקות למודעות, והפסקות באמצע הסרטון (mid-roll) ובסוף הסרטון (post-roll) קליפ בהפסקה אחת. הזמן שחלף מהקליק להמרה מאז תחילת הפעלת התוכן, שעת המדיה של התוכן העיקרי והזמן הנוכחי של ההפסקה קליפ ההפסקה להפעלה מיושר מתחת לכל דמות.

מיקום ההפסקות

ה-SDK של ה-Web Acceptr מאפשר למפתחים לציין איפה למקם את ההפסקות למודעות על ידי הגדרה של position של Break. הערך הזה תואם לזמן המדיה של התוכן הראשי ואפשר להשתמש בו כדי ליצור הפסקות למודעות pre-roll, mid-roll ו-post-roll. הערכים האלה מוגדרים כך:

מטריצה של יכולת פעולה הדדית

לעיון מהיר, טבלה 1 מציגה סקירה כללית של סוגי המודעות, את התאימות שלהם לתכונות שקשורות למודעות.

אירועים

כשמתרחשים אירועי תקלה מרכזיים, ה-SDK להפעלת Cast ישלח אירועים מסוג BreaksEvent אפליקציה המקבלת יכולה להירשם אליהם באמצעות PlayerManager addEventListener API.

ניתן להשתמש באירועים האלה לניתוח נתונים ולמעקב אחר הפעלת מודעות. מתי VMAP (פלייליסט של מספר מודעות בווידאו) ומודעות VAST (תבנית לפרסום מודעות וידאו) הן כל אירועי מעקב רגילים שמסופקים בתשובות באופן אוטומטי נשלח על ידי ה-SDK.

סוגי האירועים מפורטים בטבלה 2 יחד עם תיאור מפורט לגבי כשהם מופעלים.

הוספת מודעה

ה-SDK של Cast מאפשר לאפליקציות להוסיף ולהסיר מודעות ברגעים שונים של סשן של הפעלת Cast. יש שני סוגים של הוספת מודעות הם סטטיים ודינמיים. כדי להוסיף מודעה סטטית יש לציין מודעות בקטע LoadRequestData לפני יצירת הנגן. הוספה של מודעה דינמית מתבססת על BreakManager addBreak ממשק API להוספת הפסקות לתוכן שכבר נטען. כל סוג של הזנה תואמת לסוגי מודעות מסוימים. תאימות נמצאת במטריצה של יכולת הפעולה ההדדית.

הוספת מודעה סטטית

התכונה 'הכנסת מודעה סטטית' מתאפיינת בהוספת המטא-נתונים הרלוונטיים של המודעה לפני ועד ליצירת שחקן. המידע הזה מפורט MediaInformation של LoadRequestData. לדוגמה, אפשר להגדיר את זה בשדה של שולח מחובר ניתן להוסיף את בקשת הטעינה המקורית באמצעות אפליקציית Web הפריקה, מיירט את הבקשה LOAD. לאחר שה-LoadRequestData מוחזר אל ה-SDK של ה-WebReceiver 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 האירוע לאחר שהנגן נוצר. הדוגמה הבאה מציגה את השימוש ב- גורם handler של אירועים שמגיב לשינויים במטא-נתונים של 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 לנכס. כשיוצרים את ההפסקה, ערך ברירת המחדל של ההפסקה בנכס הזה הוא 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 של מקלט האינטרנט מספק ממשקי 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 או לא מחזיר ערך בפונקציית קריאה חוזרת, את הקליפ המערכת תדלג על ההפסקה הזאת.

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

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