שילוב Cast SDK באפליקציית Web Sender

במדריך הזה למפתחים מוסבר איך להוסיף תמיכה ב-Google Cast לאפליקציית Web Sender באמצעות Cast SDK.

הסברים על המונחים

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

‫Web Sender SDK מורכב משני חלקים: Framework API‏ (cast.framework) ו-Base API‏ (chrome.cast). בדרך כלל, מבצעים קריאות ל-Framework API הפשוט יותר ברמה גבוהה, ואז הן מעובדות על ידי Base API ברמה נמוכה.

מסגרת השולח מתייחסת ל-Framework API, למודול ולמשאבים המשויכים שמספקים עטיפה סביב פונקציונליות ברמה נמוכה יותר. אפליקציית השולח או אפליקציית Google Cast ל-Chrome מתייחסות לאפליקציית אינטרנט (HTML/JavaScript) שפועלת בדפדפן Chrome במכשיר השולח. אפליקציית Web Receiver היא אפליקציית HTML/JavaScript שפועלת ב-Chromecast או במכשיר Google Cast.

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

טעינת הספרייה

כדי להטמיע את התכונות של Google Cast באפליקציה, צריך לדעת את המיקום של Google Cast Web Sender SDK, כמו שמוצג בהמשך. מוסיפים את פרמטר השאילתה של כתובת ה-URL‏ loadCastFramework כדי לטעון גם את Web Sender Framework API. כל הדפים באפליקציה צריכים להתייחס לספרייה באופן הבא:

<script src="https://www.gstatic.com/cv/js/sender/v1/cast_sender.js?loadCastFramework=1"></script>

Framework

‫Web Sender SDK משתמש במרחב השמות cast.framework.*. מרחב השמות מייצג את הדברים הבאים:

• שיטות או פונקציות שמפעילות פעולות ב-API
• רכיבי event listener לפונקציות של listener ב-API

המסגרת מורכבת מהרכיבים העיקריים הבאים:

• ‫CastContext הוא אובייקט יחיד שמספק מידע על מצב Cast הנוכחי, ומפעיל אירועים לשינויים במצב Cast ובמצב של סשן Cast.
• האובייקט CastSession מנהל את הסשן – הוא מספק מידע על המצב ומפעיל אירועים, כמו שינויים בעוצמת הקול במכשיר, במצב ההשתקה ובמטא-נתונים של האפליקציה.
• רכיב הכפתור להפעלת Cast, שהוא רכיב HTML מותאם אישית פשוט שמרחיב את כפתור ה-HTML. אם הכפתור להפעלת Cast שמופיע לא מספיק, אפשר להשתמש במצב Cast כדי להטמיע הכפתור להפעלת Cast.
• ‫RemotePlayerController מספק את קשירת הנתונים כדי לפשט את ההטמעה של הנגן המרוחק.

תיאור מלא של מרחב השמות זמין במאמר Google Cast Web Sender API Reference.

כפתור הפעלת Cast

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

<google-cast-launcher></google-cast-launcher>

אפשרות אחרת היא ליצור את הלחצן באופן פרוגרמטי:

document.createElement("google-cast-launcher");

אפשר להחיל על הרכיב סגנון נוסף, כמו גודל או מיקום, לפי הצורך. משתמשים במאפיין --connected-color כדי לבחור את הצבע של מצב Web Receiver כשהוא מחובר, ובמאפיין --disconnected-color כדי לבחור את הצבע של מצב Web Receiver כשהוא מנותק.

אתחול

אחרי טעינת ה-API של המסגרת, האפליקציה תפעיל את ה-handler‏ window.__onGCastApiAvailable. צריך לוודא שהאפליקציה מגדירה את ה-handler הזה ב-window לפני טעינת ספריית השולח.

בתוך הגורם המטפל הזה, מאתחלים את האינטראקציה עם Cast על ידי הפעלת השיטה setOptions(options) של CastContext.

לדוגמה:

<script>
window['__onGCastApiAvailable'] = function(isAvailable) {
  if (isAvailable) {
    initializeCastApi();
  }
};
</script>

לאחר מכן, מאתחלים את ה-API באופן הבא:

initializeCastApi = function() {
  cast.framework.CastContext.getInstance().setOptions({
    receiverApplicationId: applicationId,
    autoJoinPolicy: chrome.cast.AutoJoinPolicy.ORIGIN_SCOPED
  });
};

קודם האפליקציה מאחזרת את מופע הסינגלטון של האובייקט CastContext שסופק על ידי המסגרת. לאחר מכן, המערכת משתמשת ב-setOptions(options) באמצעות אובייקט CastOptions כדי להגדיר את applicationID.

אם אתם משתמשים ב-Default Media Receiver, שלא דורש הרשמה, אתם משתמשים בקבוע שהוגדר מראש על ידי Web Sender SDK, כמו שמוצג בהמשך, במקום ב-applicationID:

cast.framework.CastContext.getInstance().setOptions({
  receiverApplicationId: chrome.cast.media.DEFAULT_MEDIA_RECEIVER_APP_ID
});

פקד מדיה

אחרי שמאתחלים את CastContext, האפליקציה יכולה לאחזר את CastSession הנוכחי בכל שלב באמצעות getCurrentSession().

var castSession = cast.framework.CastContext.getInstance().getCurrentSession();

אפשר להשתמש ב-CastSession כדי לטעון מדיה למכשיר Cast המחובר באמצעות loadMedia(loadRequest). קודם כול, תיצור MediaInfo באמצעות contentId ו-contentType וכל מידע אחר שקשור לתוכן. לאחר מכן יוצרים ממנו LoadRequest ומגדירים את כל המידע הרלוונטי לבקשה. לבסוף, מתקשרים אל loadMedia(loadRequest) בCastSession.

var mediaInfo = new chrome.cast.media.MediaInfo(currentMediaURL, contentType);
var request = new chrome.cast.media.LoadRequest(mediaInfo);
castSession.loadMedia(request).then(
  function() { console.log('Load succeed'); },
  function(errorCode) { console.log('Error code: ' + errorCode); });

השיטה loadMedia תחזיר Promise שאפשר להשתמש בו כדי לבצע את כל הפעולות הנדרשות לקבלת תוצאה מוצלחת. אם ה-Promise נדחה, הארגומנט של הפונקציה יהיה chrome.cast.ErrorCode.

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

var player = new cast.framework.RemotePlayer();
var playerController = new cast.framework.RemotePlayerController(player);

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

• הפעלה/הפסקה: playerController.playOrPause();
• STOP: playerController.stop();
• ‫SEEK: playerController.seek();

אפשר להשתמש ב-RemotePlayer וב-RemotePlayerController עם מסגרות של קשירת נתונים, כמו Polymer או Angular, כדי להטמיע נגן מרוחק.

הנה קטע קוד ל-Angular:

<button id="playPauseButton" class="playerButton"
  ng-disabled="!player.canPause"
  ng-click="controller.playOrPause()">
    {{player.isPaused ? 'Play' : 'Pause'}}
</button>
<script>
var player = new cast.framework.RemotePlayer();
var controller = new cast.framework.RemotePlayerController(player);
// Listen to any player update, and trigger angular data binding
update.controller.addEventListener(
  cast.framework.RemotePlayerEventType.ANY_CHANGE,
  function(event) {
    if (!$scope.$$phase) $scope.$apply();
  });
</script>

סטטוס המדיה

במהלך הפעלת מדיה מתרחשים אירועים שונים שאפשר לתעד אותם באמצעות הגדרת מאזינים לאירועים שונים של cast.framework.RemotePlayerEventType באובייקט RemotePlayerController.

כדי לקבל את פרטי סטטוס המדיה, משתמשים באירוע cast.framework.RemotePlayerEventType.MEDIA_INFO_CHANGED שמופעל כשמתבצע שינוי בהפעלה וכשערך CastSession.getMediaSession().media משתנה.

playerController.addEventListener(
  cast.framework.RemotePlayerEventType.MEDIA_INFO_CHANGED, function() {
    // Use the current session to get an up to date media status.
    let session = cast.framework.CastContext.getInstance().getCurrentSession();

    if (!session) {
        return;
    }

    // Contains information about the playing media including currentTime.
    let mediaStatus = session.getMediaSession();
    if (!mediaStatus) {
        return;
    }

    // mediaStatus also contains the mediaInfo containing metadata and other
    // information about the in progress content.
    let mediaInfo = mediaStatus.media;
  });

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

איך פועל ניהול הסשנים

ב-Cast SDK מוצג המושג של סשן Cast, שההגדרה שלו משלבת את השלבים של חיבור למכשיר, הפעלה (או הצטרפות) של אפליקציית Web Receiver, חיבור לאפליקציה הזו ואתחול של ערוץ בקרת מדיה. מידע נוסף על סשנים של Cast ומחזור החיים של Web Receiver זמין במדריך בנושא מחזור החיים של אפליקציית Web Receiver.

הסשנים מנוהלים על ידי המחלקה CastContext, שאפליקצייתכם יכולה לאחזר באמצעות cast.framework.CastContext.getInstance(). סשנים בודדים מיוצגים על ידי מחלקות משנה של המחלקה Session. לדוגמה, ‫CastSession מייצג סשנים עם מכשירי Cast. האפליקציה יכולה לגשת לסשן Cast הפעיל הנוכחי באמצעות CastContext.getCurrentSession().

כדי לעקוב אחרי מצב הסשן, מוסיפים listener ל-CastContext עבור סוג האירוע CastContextEventType.SESSION_STATE_CHANGED.

var context = cast.framework.CastContext.getInstance();
context.addEventListener(
  cast.framework.CastContextEventType.SESSION_STATE_CHANGED,
  function(event) {
    switch (event.sessionState) {
      case cast.framework.SessionState.SESSION_STARTED:
      case cast.framework.SessionState.SESSION_RESUMED:
        break;
      case cast.framework.SessionState.SESSION_ENDED:
        console.log('CastContext: CastSession disconnected');
        // Update locally as necessary
        break;
    }
  })

כדי לטפל בניתוק, למשל כשהמשתמש לוחץ על הלחצן 'הפסקת ההפעלה ב-Cast' בתיבת הדו-שיח של Cast, אפשר להוסיף listener לסוג האירוע RemotePlayerEventType.IS_CONNECTED_CHANGED ב-listener. בודקים אם RemotePlayer מנותק. אם כן, מעדכנים את מצב הנגן המקומי לפי הצורך. לדוגמה:

playerController.addEventListener(
  cast.framework.RemotePlayerEventType.IS_CONNECTED_CHANGED, function() {
    if (!player.isConnected) {
      console.log('RemotePlayerController: Player disconnected');
      // Update local player to disconnected state
    }
  });

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

function stopCasting() {
  var castSession = cast.framework.CastContext.getInstance().getCurrentSession();
  // End the session and pass 'true' to indicate
  // that Web Receiver app should be stopped.
  castSession.endSession(true);
}

העברת שידור

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

כדי לקבל את מכשיר היעד החדש במהלך העברת הזרם, צריך להפעיל את הקריאה CastSession#getCastDevice() כשהאירוע cast.framework.SessionState.SESSION_RESUMED מופעל.

מידע נוסף זמין במאמר בנושא העברת סטרימינג ב-Web Receiver.