שילוב 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 מופיע תיאור מלא של מרחב השמות.

כפתור הפעלת Cast

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

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

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

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

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