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

סקירה כללית

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

VAST

ה-Web Receiver SDK תומך בהוספת מודעות VAST (מודעות וידאו להצגת מודעות וידאו) רגילות של IAB. כשמקבלים את ההפסקה, תבנית ה-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 שמכיל VAST BreakClip, ה-Web Receiver יאחזר באופן אופציונלי את התבנית ואז ינתח אותה. במהלך הניתוח, ה-SDK ייצור BreakClip חדש ויאכלס אותו בערכים שחולצו מהתבנית, כמו contentId, contentType, title, duration, whenSkippable ו-clickThroughUrl. הערך id בקליפ ההפסקה שנוצר מוגדר ל-GENERATED:N. הערך N הוא מספר שלם שנוסף ב-1 לכל קליפ חדש של VAST שנוצר מ-0. לאחר מכן המודעה שנוצרה מתווספת למערך 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 תומך בתקן VMAP (פלייליסטים של מודעות וידאו מרובות בסרטונים) של IAB. כשמסופק VMAP, ה-Web Receiver SDK מנתח את תגובת VMAP ויוצר client-stitched Break אובייקטים עבור כל <AdBreak> ערכים בתגובה. היא גם תיצור את הערך 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 חיוביים בדיוק. מידע נוסף בנושא זמין בקטע מיקום הפסקה. כשהמודעה מופעלת, ה-Web Receiver 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 צריך להיות מוגדר כ-true וגם expanded ל-true.isEmbedded אפשר להגדיר את המודעה position כהפסקה למודעות לפני סרטון או באמצע סרטון. בהפסקות למודעות אחרי סרטון יש תמיכה בערכי position חיוביים. מידע נוסף בנושא זמין בקטע מיקום הפסקה. כשהמודעה מופעלת, ה-Web Receiver 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 שבהמשך מוצגים סוגי תוכן עם סוגי מודעות מגוונים וערכי ציר הזמן שלהם. התוכן מוגדר באמצעות הפסקה לפני סרטון שמכילה שני קליפים של הפסקות, והפסקות mid-roll וpost-roll שמכילות קליפ להפסקה אחת. זמן שעון הקיר מאז תחילת ההפעלה של התוכן, זמן המדיה של התוכן העיקרי וזמן ההפסקה המופעל כרגע בהפסקה, מיושרים מתחת לכל אחת מהדמויות.

איור 1: ציר הזמן מייצג תוכן מסוים ואת 3 ההפסקות למודעות שתפרו על ידי הלקוח.

איור 2: ציר הזמן מייצג תוכן מסוים ואת 3 ההפסקות למודעות שמוטמעות על ידי השרת.

איור 3: ציר הזמן מייצג תוכן מסוים ו-3 הפסקות למודעות שהוטמעו בו על ידי הצמדת השרת.

מיקום שבר

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

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

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

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

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

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

אירועים

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

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

סוגי האירועים מפורטים בטבלה 2 לצד תיאור מפורט של זמני ההפעלה.

איור 4: מחזור החיים של אירועי שבירה.

טבלה 2: אירועי הפסקה והתיאורים שלהם.

אירוע הפסקה	התיאור
BREAK_STARTED	מופעל כשזמן המדיה הנוכחי של התוכן הראשי שווה ל-position של ההפסקה שלא נצפתה.
BREAK_CLIP_LOADING	מופעל רק כאשר קליפ ההפסקה של ציר הזמן מחובר מתחיל להיטען.
BREAK_CLIP_STARTED	מופעל כשקליפ ההפסקה מתחיל לפעול.
BREAK_CLIP_ENDED	מופעל כשקליפ ההפסקה מסתיים. השדה endedReason יאוכלס בנסיבות הבאות: קליפ מנותק של ציר זמן שהושמע במלואו. קליפ מחובר של הפסקה בציר הזמן מועבר לקליפ אחר להפסקה. המערכת תדלג על כל קליפ של ההפסקה. קטע ההפסקה האחרון הופעל במלואו בהפסקה מוטמעת של מודעה בסוף סרטון. אירעה שגיאה.
BREAK_ENDED	מופעל כשקליפ ההפסקה האחרון בהפסקה מסתיים.

הוספת מודעה

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

הכנסת מודעה סטטית

הזנה סטטית של מודעות מתאפיינת בהוספת מטא-נתונים רלוונטיים של המודעה לפני יצירת הנגן. המידע הזה מסופק ב-MediaInformation ב-LoadRequestData. לדוגמה, אפשר להגדיר זאת בבקשת הטעינה המקורית של שולח מחובר, או שאפשר להוסיף אותה באמצעות האפליקציה Web Receiver על ידי יירוט הבקשה 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 וקוראים ל-API של addBreak. לשם כך נדרשים שני פרמטרים לכל הפחות: Break מוטמע, ומערך BreakClip. כלול מאפיין שלישי אופציונלי כדי לאלץ שליחה של השינויים לשולחים מחוברים באמצעות שידור MediaStatus כאשר מוגדר לערך true. כשמוסיפים הפסקות וקטעים, המזהים התואמים חייבים להיות ייחודיים. אפשר להוסיף את המודעות האלה רק אחרי שהנגן נוצר. ה-Web Receiver 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, על ידי בדיקת המאפיין isWatched על ידי ה-SDK מתבצעת הערכה אם המשתמש כבר ראה אותו. כשיוצרים הפסקות, ערך ברירת המחדל שמוגדר להפסקה בנכס הזה הוא false. אם המאפיין הוא true, לא יופעל ההפסקה כשמזינים אותה והתוכן הראשי ימשיך לפעול. אם המאפיין הוא false, ההפסקה תופעל בזמן ההזנה.

הערה: בהפסקות למודעות בציר זמן מוטמע, ה-SDK יחפש את משך ההפסקה של משתמש שצפה בו כדי להמשיך להפעיל את התוכן הראשי.

כשמחפשים הפסקות קודמות, הטמעת ברירת המחדל מקבלת את כל הפריטים של Break שהposition שלהם נמצא בין הערכים seekFrom ו-seekTo. מתוך רשימת ההפסקות הזו, ה-SDK יפעיל את Break שהערך position שלו הכי קרוב לערך seekTo ושהמאפיין isWatched שלו מוגדר כ-false. המאפיין isWatched של ההפסקה הזו יוגדר כ-true והנגן יתחיל להפעיל את קטעי ההפסקה. אחרי צפייה בהפסקה, התוכן הראשי יחזור לפעול מהמיקום seekTo. אם לא קיימת הפסקה כזו, לא תופעל הפסקה והתוכן הראשי ימשיך לפעול במיקום seekTo.

במהלך הפעלה בהפסקה, ה-SDK ישדר את העדכונים הרלוונטיים לאפליקציות שולח מחוברות ב-MediaStatus. האפליקציות האלה ישתמשו בשידורים כדי לעדכן את ממשק המשתמש שלהן עבור מודעות על ידי קריאת המאפיין breakStatus. המאפיין הזה מוגדר רק במהלך הפעלה של הפסקות.

הערה: אפליקציות של המקבל יכולות להירשם לאירועי PlayerManager MEDIA_STATUS כדי לעקוב אחר השינויים בMediaStatus.

האפליקציות של המקבל יכולות גם לשלוח שאילתות ישירות לגבי מידע שקשור למיקום של המיקום הנוכחי ביחס לזמן הנוכחי של BreakClip שמוצג באמצעות קריאה ל-PlayerManager getBreakClipCurrentTimeSec. באופן דומה, אפליקציות יכולות להריץ שאילתה לגבי משך הזמן של ה-BreakClip הנוכחי באמצעות קריאה ל-getBreakClipDurationSec.

התנהגות הפסקות מותאמת אישית

אפשר לשנות את התנהגות ברירת המחדל של הפסקות והפסקות באמצעות השיטות setBreakClipLoadInterceptor ו-setBreakSeekInterceptor שמוצעות ב-BreakManager.

הערה: אם אתם מבצעים פעולת הרצה לאחר השלמת ההפסקה, ודאו שמצב הנגן של האובייקט MediaStatus השתנה ל-PLAYING לפני ביצוע פעולת ההרצה.

יירוט הדילוג

הכלי ליירוט ההפסקות מאפשר לאפליקציה לשלוט בהתנהגות של דילוג על הפסקות למודעות. הפונקציה מופעלת כשנשלחת בקשה לפעולת הרצה שמדלגת קדימה או אחורה במעבר אחד או יותר. כשהיא מופעלת, הפרמטר BreakSeekData מועבר כפרמטר לפונקציית הקריאה החוזרת. האובייקט BreakSeekData מכיל מערך של אובייקטים Break שהמאפיין position שלהם מוגדר למספר בין זמן ההפעלה הנוכחי שמוגדר כ-seekFrom לזמן היעד ההרצה seekTo.

הגורם המיירט הזה מאפשר לשנות את Break האובייקטים בהפסקות המתאימות. כשהוא מיושם, הכלי ליירוט של חיפוש ההפסקות חייב לציין אילו הפסקות למודעות יופעלו על ידי החזרת אובייקט BreakSeekData שהשתנה (אופציונלי). הנגן ימשיך להפעיל את כל ההפסקות שכלולות בערך המוחזר. אם המערכת מדלגת על ההפסקה אם הערך הוא null או שלא מוחזר שום דבר ממיירט הדילוג.

הערה: הגדרת מיירט הדילוג של ההפסקה מבטלת את התנהגות ברירת המחדל. כולל תכונות כמו דילוג על הפסקות שכבר צפיתם בהן. כדי להתאים אישית את התנהגות הדילוג על ההפסקות ולא להפעיל הפסקות שנצפו, האפליקציה צריכה לציין את הלוגיקה הזו במיירט הדילוג על ידי בדיקת המאפיין isWatched של 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 המקורי כפרמטר של פונקציית הקריאה החוזרת. לאחר מכן האפליקציה יכולה לשנות את 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;
});

דילוג על מודעה

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

אפשר להגדיר את המידע הזה בבקשת הטעינה המקורית של השולח או באפליקציה של המקבל. כשדילגתם על כך, קטע ההפסקה הנוכחי בהפסקה למודעה בציר זמן מחובר יפסיק להפעיל את קטע ההפסקה הנוכחי. הנגן יטען את קליפ ההפסקה הבא, אם הוא קיים, או יטען את התוכן הראשי. כשדילגתם על קטעי הפסקה, בקטע הפסקה למודעה בציר זמן מוטמע, הקטע יופנה לסוף קליפ ההפסקה וימשיך בהפעלת השידור באותה נקודה.

הערה: בנוסף להטמעה של קטע הקוד שלמעלה, לאפליקציות של Web Sender נדרש להוסיף 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 או לא מחזירים ערך בפונקציית הקריאה החוזרת, המערכת תדלג על קטע הקוד בהפסקה הזו.

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

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

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