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

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

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

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

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

מסגרת השולח מתייחסת ל-framework API, למודול ולממשק המשויך משאבים שמספקים wrapper לפונקציונליות ברמה נמוכה יותר. אפליקציית השולח או אפליקציית Google Cast ל-Chrome: אפליקציית אינטרנט (HTML/JavaScript) פועל בדפדפן Chrome במכשיר שולח. אפליקציה של קבלה מהאינטרנט לאפליקציית 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>

מסגרת

ב-Web Sender SDK נעשה שימוש ב-cast.framework.* מרחב שמות. מרחב השמות מייצג את הערכים הבאים:

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

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

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

כדאי לקרוא את חומר עזר בנושא Google Cast Web Sender API את התיאור המלא של מרחב השמות.

לחצן הפעלת Cast

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

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

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

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

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

אתחול

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

בתוך ה-handler הזה, אפשר לאתחל את האינטראקציה של 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אדמין, שלא מחייב הרשמה, משתמשים ב-SDK קבוע שמוגדר מראש על ידי 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 שיכול לשמש לביצוע כל הפעולות הנדרשות להשגת תוצאה מוצלחת. אם ההבטחה נדחתה, הארגומנט של הפונקציה יהיה 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();
• בקשה: playerController.seek();

הערכים RemotePlayer ו-RemotePlayerController יכולים להיות בשימוש עם frameworks, כגון פולימר או 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;
  });

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

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

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

הסשנים מנוהלים על ידי הכיתה 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;
    }
  })

לניתוק, למשל כשמשתמש לוחץ על 'הפסקת העברה' לחצן מ- בתיבת הדו-שיח 'העברה', אפשר להוסיף האזנה RemotePlayerEventType.IS_CONNECTED_CHANGED סוג האירוע ב-listener שלכם. ב-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 של ה-framework לחצן, השולח עצמו יכול להפסיק את הפעלת ה-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 מתבצעת קריאה לאירוע.

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