將 Cast SDK 整合至網路寄件者應用程式

透過集合功能整理內容 你可以依據偏好儲存及分類內容。

本開發人員指南說明如何使用 Cast SDK 為網路寄件者應用程式新增 Google Cast 支援。

術語

行動裝置或瀏覽器是用來控製播放功能的「傳送端」，Google Cast 裝置則是「接收端」，也就是在螢幕上顯示內容以供播放。

網路寄件者 SDK 包含兩個部分： Framework API (cast.framework) 和 Base API (chrome.cast)。一般來說，您可以呼叫簡易、較高階的 Framework API，然後由較低層級的 Base API 處理。

「寄件者架構」是指 Framework API、模組和相關資源，可提供較低層級功能的包裝函式。寄件者應用程式或 Google Cast Chrome 應用程式是指在寄件者裝置的 Chrome 瀏覽器中執行的網頁 (HTML/JavaScript) 應用程式。網頁接收器應用程式是指在 Chromecast 或 Google Cast 裝置上運作的 HTML/JavaScript 應用程式。

傳送者架構會使用非同步回呼設計，通知傳送者應用程式事件，並在 Cast 應用程式生命週期的不同狀態之間進行轉換。

載入程式庫

為了讓您的應用程式實作 Google Cast 的功能，必須知道 Google Cast 網路寄件者 SDK 的位置，如下所示。加入 loadCastFramework 網址查詢參數，也可以載入 Web SENDER Framework API。應用程式的所有頁面都必須以下列方式參照程式庫：

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

架構

網路寄件者 SDK 使用 cast.framework.* 命名空間。命名空間代表下列項目：

  • 透過 API 叫用作業的方法或函式
  • API 中監聽器函式的事件監聽器

這個架構包含下列主要元件：

  • CastContext 是單例模式物件，可提供目前投放狀態的相關資訊，並觸發投放狀態和投放工作階段狀態變更。
  • CastSession 物件會管理工作階段，其會提供狀態資訊並觸發事件，例如裝置音量、靜音狀態和應用程式中繼資料的變更。
  • 「投放」按鈕元素是可擴充的 HTML 自訂元素，可以擴充 HTML 按鈕。如果提供的投放按鈕不足，可以使用投放狀態實作投放按鈕。
  • RemotePlayerController 提供資料繫結，以簡化遠端播放器的實作。

如需命名空間的完整說明，請參閱 Google Cast Web SENDER API 參考資料。

投放按鈕

應用程式中的投放按鈕元件完全由架構處理。包括瀏覽權限管理和點擊事件處理。

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

或者，您可以透過程式建立按鈕：

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

您可以視需要將任何其他樣式樣式 (例如大小或位置) 套用至元素。使用 --connected-color 屬性為已連結的 Web Receiver 狀態選擇顏色，並為 --disconnected-color 中斷連線。

初始化

載入架構 API 後，應用程式會呼叫處理常式 window.__onGCastApiAvailable。您應確保應用程式在 載入傳送者程式庫之前，先在 window 上設定此處理常式。

在這個處理常式中，您可以呼叫 CastContext 的 setOptions(options) 方法來初始化 Cast 互動。

例如：

<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。

如果您使用預設媒體接收器，且不需要註冊，請使用 Web SENDER SDK 預先定義的常數，如下所示，而非 applicationID：

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

媒體管理

初始化 CastContext 後，應用程式隨時可以使用 getCurrentSession() 擷取目前的 CastSession。

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

CastSession 可用來使用 loadMedia(loadRequest) 將媒體載入已連結的 Cast 裝置。首先，使用 contentId 和 contentType 以及與內容相關的任何其他資訊，建立 MediaInfo。然後透過此建立 LoadRequest，設定該要求的所有相關資訊。最後，在 CastSession 上呼叫 loadMedia(loadRequest)。

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 的互動 (包括媒體事件回呼和指令) 都會透過 RemotePlayerController 處理。

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

RemotePlayerController 可讓應用程式對載入的媒體完全控制 PLAY、暫停、停止和 SEEK。

  • 播放/暫停：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>

媒體狀態

在媒體播放期間，可透過為 RemotePlayerController 物件上的各種 cast.framework.RemotePlayerEventType 事件設定事件監聽器，藉此擷取多種事件。

如要取得媒體狀態資訊，請使用 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 裝置上的 Web Receiver 應用程式之間進行同步處理。如需詳細資訊，請參閱狀態更新。

工作階段管理的運作方式

Cast SDK 介紹 Cast 工作階段的概念，其概念結合了連接裝置、啟動 (或加入) 網路接收器應用程式、連線至該應用程式，以及初始化媒體控制通道的步驟。如要進一步瞭解 Cast 工作階段和 Web Receiver 生命週期，請參閱 Web Receiver 應用程式生命週期指南。

工作階段是由 CastContext 類別管理，您的應用程式可以透過 cast.framework.CastContext.getInstance() 擷取。個別工作階段以 Session 類別的子類別表示。舉例來說，CastSession 代表投放裝置的工作階段。您的應用程式可透過 CastContext.getCurrentSession() 存取目前執行的 Cast 工作階段。

若要監控工作階段狀態，請將事件監聽器新增至 CastContextEventType.SESSION_STATE_CHANGED 事件類型的 CastContext。

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 事件類型的事件監聽器。在事件監聽器中，檢查 RemotePlayer 是否中斷連線。如果是的話，請視需要更新本機播放器狀態。例如：

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

雖然使用者可以透過架構的投放按鈕直接控制投放終止，但傳送者本身可以使用目前的 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 裝置都可以做為串流傳輸的來源或目的地。

如要在串流傳輸期間取得新的目的地裝置，請在呼叫 cast.framework.SessionState.SESSION_RESUMED 事件時呼叫 CastSession#getCastDevice()。

如需詳細資訊，請參閱透過 Web 接收器接收串流傳輸。

上一頁
設定
下一頁
新增進階功能