הוספת תכונות מתקדמות לאפליקציית Web Sender

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

‫Web Sender SDK מספק תמיכה בהפסקות פרסום ובמודעות נלוות בתוך סטרימינג של מדיה.

במאמר סקירה כללית על הפסקות לפרסומות ב-Web Receiver מוסבר איך הפסקות לפרסומות פועלות.

אפשר לציין הפסקות גם בצד השולח וגם בצד המקבל, אבל מומלץ לציין אותן ב-Web Receiver וב-Android TV Receiver כדי לשמור על התנהגות עקבית בפלטפורמות השונות.

באינטרנט, מציינים הפסקות למודעות בפקודת טעינה באמצעות BreakClip ו-Break:

let breakClip1 = new BreakClip('bc0');
breakClip1.title = 'Clip title'
breakClip1.posterUrl = 'https://www.some.url';
breakClip1.duration = 60;
breakClip.whenSKippable = 5;

let breakClip2 = ...
let breakClip3 = ...

let break1 = new Break('b0', ['bc0', 'bc1', 'bc2'], 10);

let mediaInfo = new chrome.cast.media.MediaInfo(<contentId>, '<contentType');
...
mediaInfo.breakClips = [breakClip1, breakClip2, breakClip3];
mediaInfo.breaks = [break1];

let request = new chrome.cast.media.LoadRequest(mediaInfo);

cast.framework.CastContext.getInstance().getCurrentSession().loadMedia(request)

שימוש בממשקי ה-API של מסלולי ההפצה

הטראק יכול להיות אובייקט טקסט (כתוביות) או אובייקט של זרם אודיו או וידאו. ממשקי ה-API של Tracks מאפשרים לכם לעבוד עם האובייקטים האלה באפליקציה.

אובייקט Track מייצג רצועה ב-SDK. כך מגדירים רצועת שמע ומקצים לה מזהה ייחודי:

var englishSubtitle = new chrome.cast.media.Track(1, // track ID
  chrome.cast.media.TrackType.TEXT);
englishSubtitle.trackContentId = 'https://some-url/caption_en.vtt';
englishSubtitle.trackContentType = 'text/vtt';
englishSubtitle.subtype = chrome.cast.media.TextTrackType.SUBTITLES;
englishSubtitle.name = 'English Subtitles';
englishSubtitle.language = 'en-US';
englishSubtitle.customData = null;

var frenchSubtitle = new chrome.cast.media.Track(2, // track ID
  chrome.cast.media.TrackType.TEXT);
frenchSubtitle.trackContentId = 'https://some-url/caption_fr.vtt';
frenchSubtitle.trackContentType = 'text/vtt';
frenchSubtitle.subtype = chrome.cast.media.TextTrackType.SUBTITLES;
frenchSubtitle.name = 'French Subtitles';
frenchSubtitle.language = 'fr';
frenchSubtitle.customData = null;

var frenchAudio = new chrome.cast.media.Track(3, // track ID
  chrome.cast.media.TrackType.AUDIO);
frenchAudio.trackContentId = 'trk0001';
frenchAudio.trackContentType = 'audio/mp3';
frenchAudio.subtype = null;
frenchAudio.name = 'French Audio';
frenchAudio.language = 'fr';
frenchAudio.customData = null;

יכול להיות שפריט מדיה יכלול כמה טראקים. לדוגמה, יכול להיות שהוא יכלול כמה כתוביות (כל אחת בשפה אחרת) או כמה זרמי אודיו חלופיים (בשפות שונות).

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

var tracks = [englishSubtitle, frenchSubtitle, frenchAudio];
var mediaInfo = new chrome.cast.media.MediaInfo(mediaURL);
mediaInfo.contentType = 'video/mp4';
mediaInfo.metadata = new chrome.cast.media.GenericMediaMetadata();
mediaInfo.customData = null;
mediaInfo.streamType = chrome.cast.media.StreamType.BUFFERED;
mediaInfo.textTrackStyle = new chrome.cast.media.TextTrackStyle();
mediaInfo.duration = null;
mediaInfo.tracks = tracks;

אפשר להגדיר את הטראקים הפעילים בבקשת המדיה activeTrackIds.

אפשר גם להפעיל טראק אחד או יותר ששויכו לפריט המדיה אחרי שהמדיה נטענת, באמצעות קריאה ל-EditTracksInfoRequest(opt_activeTrackIds, opt_textTrackStyle) והעברת המזהים של הטראקים שרוצים להפעיל ב-opt_activeTrackIds. הערה: שני הפרמטרים הם אופציונליים, ואתם יכולים לבחור אם להגדיר אותם, ואם כן, אילו מהם – רצועות פעילות או סגנונות. לדוגמה, כך מפעילים כתוביות בצרפתית (2) ואודיו בצרפתית (3):

var activeTrackIds = [2, 3];
var tracksInfoRequest = new chrome.cast.media.EditTracksInfoRequest(activeTrackIds);
media.editTracksInfo(tracksInfoRequest, successCallback, errorCallback);

כדי להסיר את כל טראקים של האודיו או הסרטון מהמדיה הנוכחית, פשוט מגדירים את mediaInfo.tracks=null (מערך ריק) וטוענים מחדש את המדיה.

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

• מעדכנים את var activeTrackIds = [2, 3]; (שמוצג למעלה) כך שיכלול רק את [3], טראק האודיו.
• מגדירים את mediaInfo.tracks=null. שימו לב שלא צריך לטעון מחדש את המדיה כדי להשבית את הכתוביות (track.hidden). שליחת מערך activeTracksId שלא מכיל trackId שהופעל בעבר משביתה את רצועת הטקסט.

עיצוב של טראקים של טקסט

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

var textTrackStyle = new chrome.cast.media.TextTrackStyle();
var tracksInfoRequest = new chrome.cast.media.EditTracksInfoRequest(textTrackStyle);
media.editTracksInfo(tracksInfoRequest, successCallback, errorCallback);

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

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

אפשר להגדיר סגנון לרכיבים הבאים של כתוביות:

• צבע החזית (הטקסט) והאטימות
• צבע ושקיפות הרקע
• סוג קצה
• צבע הקצה
• הגדלת הגופן
• משפחת גופנים
• סגנון הגופן

לדוגמה, כדי להגדיר את צבע הטקסט לאדום עם אטימות של 75%, משתמשים בהגדרה הבאה:

var textTrackStyle = new chrome.cast.media.TextTrackStyle();
textTrackStyle.foregroundColor = '#80FF0000';

בקרת עוצמת הקול

אפשר להשתמש ב-RemotePlayer וב-RemotePlayerController כדי להגדיר את עוצמת הקול של המקלט.

function changeVolume(newVolume) {
  player.volumeLevel = newVolume;
  playerController.setVolumeLevel();
  // Update sender UI to reflect change
}

אפליקציית השולח צריכה לפעול בהתאם להנחיות הבאות לגבי שליטה בעוצמת הקול:

• האפליקציה של השולח צריכה להסתנכרן עם המקלט כדי שממשק המשתמש של השולח תמיד ידווח על עוצמת הקול לפי המקלט. משתמשים בפונקציות הקריאה החוזרת (callback) ‏RemotePlayerEventType.VOLUME_LEVEL_CHANGED ו-RemotePlayerEventType.IS_MUTED_CHANGED כדי לשמור על עוצמת הקול אצל השולח. מידע נוסף זמין במאמר בנושא עדכוני סטטוס.
• אפליקציות שולחות לא יכולות להגדיר את עוצמת הקול לרמה ספציפית ומוגדרת מראש, או להגדיר את עוצמת הקול לעוצמת הצלצול או המדיה של המכשיר השולח כשהאפליקציה נטענת במכשיר המקבל.

אפשר לעיין באמצעי הבקרה על נפח השליחה ברשימת הבדיקה של העיצוב.

שליחת הודעות מדיה לנמען

אפשר לשלוח את Media Messages מהשולח לנמען. לדוגמה, כדי לשלוח הודעת SKIP_AD לנמען:

// Get a handle to the skip button element
const skipButton = document.getElementById('skip');
skipButton.addEventListener("click", function() {
  if (castSession) {
    const media = castSession.getMediaSession();
    castSession.sendMessage('urn:x-cast:com.google.cast.media', {
      type: 'SKIP_AD',
      requestId: 1,
      mediaSessionId: media.mediaSessionId
    });
  }
});

עדכוני סטטוס

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

לכן, באפליקציה צריך לרשום את כל מאזיני ההתראות הנדרשים ב-RemotePlayerController. אם הערך של TextTrackStyle במדיה הנוכחית משתנה, כל השולחים המחוברים יקבלו על כך הודעה, והמאפיינים התואמים של סשן המדיה הנוכחי, כמו activeTrackIds ו-textTrackStyle בשדה MediaInfo, יישלחו לשולחים בקריאות חוזרות (callback). במקרה כזה, ה-SDK של המקלט לא בודק אם הסגנון החדש שונה מהסגנון הקודם, ומודיע על כך לכל השולחים המחוברים.

מחוון התקדמות

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

דרישות CORS

לסטרימינג של מדיה אדפטיבית, נדרשות כותרות CORS ב-Google Cast, אבל גם לסטרימינג פשוט של מדיה בפורמט mp4 נדרש CORS אם הוא כולל רכיבי Tracks. אם רוצים להפעיל רצועות לכל מדיה, צריך להפעיל CORS גם לסטרימינג של רצועות וגם לסטרימינג של מדיה. לכן, אם אין לכם כותרות CORS זמינות עבור קובץ מדיה פשוט מסוג mp4 בשרת, ואז אתם מוסיפים רצועת כתוביות פשוטה, לא תוכלו להזרים את המדיה אלא אם תעדכנו את השרת כך שיכלול את כותרות ה-CORS המתאימות.

צריך להשתמש בכותרות הבאות: Content-Type,‏ Accept-Encoding ו-Range. שימו לב ששתי הכותרות האחרונות, Accept-Encoding ו-Range, הן כותרות נוספות שאולי לא הייתם צריכים בעבר.

אי אפשר להשתמש בתווים הכלליים לחיפוש "*" בכותרת Access-Control-Allow-Origin. אם בדף יש תוכן מדיה מוגן, צריך להשתמש בדומיין במקום בתו כללי.

המשך של סשן בלי לטעון מחדש את דף האינטרנט

כדי להמשיך שיחה קיימת ב-CastSession, משתמשים ב-requestSessionById(sessionId) עם sessionId של השיחה שאליה מנסים להצטרף.

אפשר למצוא את sessionId בCastSession הפעיל באמצעות getSessionId() אחרי שמתקשרים אל loadMedia().

הגישה המומלצת היא:

1. מתקשרים למספר loadMedia() כדי להתחיל את הסשן
2. אחסון sessionId באופן מקומי
3. אם צריך, מצטרפים מחדש לסשן באמצעות requestSessionById(sessionId)

let sessionId;

function rejoinCastSession() {
  chrome.cast.requestSessionById(sessionId);

  // Add any business logic to load new content or only resume the session
}

document.getElementById('play-button').addEventListener(("click"), function() {
  if (sessionId == null) {
    let castSession = cast.framework.CastContext.getInstance().getCurrentSession();
    if (castSession) {
      let mediaInfo = createMediaInfo();
      let request = new chrome.cast.media.LoadRequest(mediaInfo);
      castSession.loadMedia(request)

      sessionId = CastSession.getSessionId();
    } else {
      console.log("Error: Attempting to play media without a Cast Session");
    }
  } else {
    rejoinCastSession();
  }
});

השלבים הבאים

בזה מסתיים התיאור של התכונות שאפשר להוסיף לאפליקציית השולט באינטרנט. עכשיו אפשר ליצור אפליקציית שולט לפלטפורמה אחרת (Android או iOS), או ליצור אפליקציית מקלט.