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

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

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

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

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

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

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

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

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

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

דרישות CORS

עבור סטרימינג דינמי של מדיה, נדרש נוכחות של כותרות CORS ב-Google Cast, אבל גם לשידורי מדיה פשוטים בפורמט 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