將 Cast SDK 整合至 Web Sender 應用程式

本開發人員指南說明如何使用 Cast SDK，在網頁傳送端應用程式中加入 Google Cast 支援。

術語

行動裝置或瀏覽器是「傳送端」，負責控制播放；Google Cast 裝置是「接收端」，負責在螢幕上顯示內容以供播放。

Web Sender SDK 包含兩個部分：Framework API (cast.framework) 和 Base API (chrome.cast)。一般來說，您會呼叫較簡單、較高階的 Framework API，然後由較低階的 Base API 處理。

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

傳送端架構採用非同步回呼設計，可通知傳送端應用程式事件，並在 Cast 應用程式生命週期的各種狀態之間轉換。

載入程式庫

如要讓應用程式導入 Google Cast 功能，必須知道 Google Cast Web Sender SDK 的位置，如下所示。新增 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 叫用作業的方法或函式
  • API 中事件監聽器函式的事件監聽器

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

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

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

投放按鈕

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

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

或者，您也可以透過程式輔助方式建立按鈕：

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

您可以視需要為元素套用任何其他樣式，例如大小或位置。使用 --connected-color 屬性選擇已連線網路接收器狀態的顏色，並使用 --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 物件單例模式執行個體。接著，使用 CastOptions 物件，透過 setOptions(options) 設定 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 可讓應用程式完整控制載入媒體的播放、暫停、停止和跳轉功能。

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

媒體狀態

媒體播放期間會發生各種事件，您可以為 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 接收端應用程式之間同步處理。詳情請參閱「狀態更新」。

工作階段管理功能的運作方式

Cast SDK 導入 Cast 工作階段的概念，建立工作階段時，會結合連線至裝置、啟動 (或加入) Web 接收端應用程式、連線至該應用程式，以及初始化媒體控制管道等步驟。如要進一步瞭解 Cast 工作階段和 Web 接收端生命週期，請參閱 Web 接收端應用程式生命週期指南。

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

如要監控工作階段狀態，請在 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 對話方塊中點選「停止投放」按鈕)，您可以在事件監聽器中為 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 接收端上變更串流裝置」。

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