本頁面由 Cloud Translation API 翻譯而成。

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

本開發人員指南說明如何使用 Cast SDK，將 Google Cast 支援新增至 Web Sender 應用程式。

術語

行動裝置或瀏覽器是控製播放的「傳送者」；Google Cast 裝置是「接收端」，可在螢幕上顯示播放內容。

Web Sender SDK 包含兩個部分：Framework API (cast.framework) 和 Base API (chrome.cast)。一般來說，您會在較簡單且高階的架構 API 上進行呼叫，接著再由較低層級的 Base API 處理。

「傳送者架構」是指 Framework API、模組和相關聯的資源，可提供較低層級的功能包裝函式。傳送者應用程式或 Google Cast Chrome 應用程式是指在傳送端裝置的 Chrome 瀏覽器中執行的網頁 (HTML/JavaScript) 應用程式。網頁接收端應用程式是指在 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 是單例模式物件，提供目前投放狀態的相關資訊，並觸發投放狀態和投放工作階段狀態變更的事件。
CastSession 物件用於管理工作階段。這個物件可提供狀態資訊並觸發事件，例如變更裝置音量、靜音狀態和應用程式中繼資料。
「投放」按鈕元素是簡單的 HTML 自訂元素，可以擴充 HTML 按鈕。如果提供的「投放」按鈕不足，可以使用「投放」狀態實作「投放」按鈕。
RemotePlayerController 提供資料繫結，可簡化遠端播放器的實作方式。

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

投放按鈕

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

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

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

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

您可以視需要為元素套用其他樣式設定，例如大小或位置。請使用 --connected-color 屬性選擇已連線 Web 接收器狀態的顏色，並使用 --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 物件設定 applicationID。setOptions(options)

如果您使用的是不須註冊的預設媒體接收器，請使用 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) 將媒體載入已連線的投放裝置。首先，使用 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 可讓應用程式完全控制載入的媒體，包括「播放」、「暫停」、「停止」和「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 SDK 介紹投放工作階段的概念，其建立方式結合了連線至裝置、啟動 (或加入) 網路接收器應用程式、連線至該應用程式，以及初始化媒體控制管道的步驟。如要進一步瞭解投放工作階段和網路接收器的生命週期，請參閱網路接收器應用程式生命週期指南。

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

如要監控工作階段狀態，請將事件監聽器新增至 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.framework.SessionState.SESSION_RESUMED 事件時呼叫 CastSession#getCastDevice()。

詳情請參閱在網路接收器上進行串流傳輸。

設定

新增進階功能