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

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

ה-Web Sender SDK מספק תמיכה בהפסקות למודעות ובמודעות נלוות במקור מדיה נתון.

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

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

באינטרנט, מציינים הפסקות למודעות בפקודת טעינה באמצעות 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 של מסלולים מאפשרים לעבוד עם האובייקטים האלו באפליקציה.

אובייקט 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 קיים, אפשר להחיל אותו על פריט המדיה שמופעל כרגע על ידי קריאה ל-method של editTrackInfo שלו, כך:

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

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

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

ניתן לעצב את רכיבי הסגנון הבאים של רצועת טקסט:

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

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

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

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

דרישות CORS

כדי לבצע סטרימינג של מדיה אדפטיבי, ל-Google Cast נדרשת נוכחות של כותרות CORS, אבל גם קובצי מדיה פשוטים בפורמט mp4 דורשים CORS אם הם כוללים טראקים. אם רוצים להפעיל טראקים לכל מדיה שהיא, צריך להפעיל 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();
  }
});

השלבים הבאים

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

הקודם
שילוב CAST