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

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

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

術語

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

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

「傳送端架構」是指 Framework API、模組和相關資源，可提供低階功能的包裝函式。「傳送端應用程式」或「Google Cast Chrome 應用程式」是指在傳送端裝置的 Chrome 瀏覽器中執行的網頁 (HTML/JavaScript) 應用程式。Web Receiver 應用程式是指在 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 自訂元素。如果提供的 Cast 按鈕不夠，您可以使用 Cast 狀態來實作 Cast 按鈕。
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) 將媒體載入已連結的 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();
停止：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;
  });

當發生暫停、播放、繼續或搜尋等事件時，應用程式就需要對這些事件採取行動，並在自身與投放裝置上的 Web Receiver 應用程式之間同步處理。詳情請參閱狀態更新。

工作階段管理機制的運作方式

Cast SDK 會介紹 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;
    }
  })

針對斷線情況 (例如使用者在 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
    }
  });

雖然使用者可以透過架構 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 裝置，都可以在串流轉移中擔任來源或目的地。

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

詳情請參閱「在網路接收器上進行串流轉移」。

設定

新增進階功能