遷移至 Web Receiver

本指南說明如何將 Cast Receiver v2 應用程式遷移至最新的 Web Receiver 應用程式。

新的 Cast Application Framework (CAF) SDK 又稱為 Web Receiver v3，是 Receiver v2 SDK 的主要升級項目。Web Receiver SDK 提供簡單好用的 SDK，可用於開發媒體 Web Receiver 應用程式。

Web Receiver 提供的 API 與新的 CAF 傳送者 API 更加一致。這個程式庫可完整整合播放器 (MPL 和 Shaka)，以及完整導入並支援 Cast 媒體和 Google 助理語音指令。CAF SDK 也提供預設 CSS，可讓您輕鬆使用 CSS 設定樣式，並使用資料繫結服務簡化 UI 實作作業。

為何要遷移？

將 Receiver v2 應用程式遷移至 Web Receiver 後，您就可以省去許多與玩家互動的程式碼，讓您專心編寫應用程式專用的商業邏輯。

CAF 可完美整合 MPL 和 Shaka 播放器，以支援更多內容類型，包括 HTTP 即時串流 (TS 和 CMAF)、MPEG-DASH、流暢串流以及媒體元素來源屬性支援的類型 (MP3、MP4、Icecast 等)。如需完整清單，請參閱支援 Google Cast 的媒體。 目前 CAF 不支援使用者提供的播放器。

遷移至 CAF 將新增支援 Google 助理的語音控制功能。使用 CAF 時，系統會自動支援所有新的 Google 助理語音指令。

除了支援新的媒體指令 (例如「依語言變更播放軌」和「變更播放速率」) 之外，CAF 還提供更好的佇列功能、內建廣告支援，以及更完善的即時支援。

有何不同之處呢？

Web Receiver API 嘗試遵循 CAF 寄件者為 Android 和 iOS 導入的慣例，而和第 2 版完全不同。

網路接收器針對所有公開的 API 使用新的命名空間 cast.framework，而不是 cast.receiver 命名空間。v2 使用的許多資料物件在 CAF 中都相同，且會在 cast.framework.messages 命名空間下公開 (主要位於 cast.receiver.media 下)。

下列第 2 版服務將由對應的 CAF 服務取代：

  • CastReceiverManager 類別會由 CastReceiverContext 取代，後者管理管理投放工作階段、傳送者、傳送自訂訊息和全域系統事件。CastReceiverOptions 可用來為內容提供全域應用程式選項 (例如佇列、接收器版本、播放設定等)。
  • MediaManager 類別由 PlayerManager 取代，其為 CastReceiverContext 單例模式的屬性，可管理媒體工作階段、媒體要求、Google 助理語音要求 (在 v2 中為 CommandAndControlManager)，以及觸發媒體事件。玩家設定 (MPL 中的 cast.player.api.Host) 是由 PlaybackConfig 提供，可由全域或每個載入要求提供。

PlayerManager 也會公開新的副管理員類別：

const context = cast.framework.CastReceiverContext.getInstance();
const playerManager = context.getPlayerManager();

// Set global options.
const options = new cast.framework.CastReceiverOptions();
options.versionCode = DEVELOPERS_APP_VERSION;

context.start(options);

接收器業務邏輯

接收器 v2 公開事件處理常式 (例如 CastReceiverManager.onReady 或 MediaManager.onLoad) 以新增商業邏輯。在 CAF 中，事件處理常式會由事件監聽器 (CastReceiverContext.addEventListener) 和訊息攔截器 (PlayerManager.setMessageInterceptor) 取代。網路接收器可對一個事件有多個事件監聽器 (事件監聽器不會影響事件)，而且每則訊息會有一個攔截器。攔截器可以更新或處理要求 (傳回修改的要求、成功訊息或錯誤訊息)，也可以是傳回承諾的非同步處理常式。

載入要求攔截器是新增應用程式專屬邏輯最常見的位置。如果是來自寄件者的載入要求，載入攔截器可以將內容 ID 轉換為內容網址。如果沒有為預載或預快取提供明確攔截器，也會對預先載入和預先快取要求呼叫載入攔截器。

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD,
    request => {
      // Resolve entity to content id
      if (request.media.entity && !request.media.contentId) {
        return getMediaByEntity(request.media.entity).then(
            media => {
              request.media.contentId = media.url;
              return request;
            });
      }
      return request;
    });

v2 自訂媒體狀態處理常式也會替換為媒體狀態訊息的訊息攔截器。不想在媒體狀態中公開媒體網址的 Web Receiver 應用程式可以提供網址解析器 (PlayerManager.setMediaUrlResolver)，以便為載入要求提供媒體網址。且 CAF 會在內部使用該網址，而不會在媒體狀態中提供。

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.MEDIA_STATUS,
    status => {
      // Disable seek.
      status.supportedMediaCommands &=
          ~cast.framework.messages.Command.SEEK
      return status;
    });

事件

Web Receiver 提供來自 CastReceiverContext 和 PlayerManager 的一系列事件。網頁接收器應用程式可以對任何事件建立多個事件監聽器，也可以為多個事件提供一個事件監聽器。(如為某些事件群組，請參閱 cast.framework.events.category)。

這些事件涵蓋任何使用者要求、播放進度、玩家處理，以及任何低階媒體元素事件 (CAF 不會公開媒體元素本身)。

Web Receiver 應用程式可新增事件監聽器 (例如載入完成時新增文字軌定義) 或用於數據分析。

// Log all media commands
playerManager.addEventListener(
    cast.framework.events.category.REQUEST,
    event => logEvent(event.type));

自訂訊息匯流排

CAF 不會在 API 中公開訊息匯流排，而是提供 CastReceiverContext.addCustomMessageListener，為特定命名空間新增訊息監聽器 (每個命名空間僅一個訊息)，以及 CastReceiverContext.sendCustomMessage 在命名空間上傳送訊息。在啟動 Web Receiver 之前 (即呼叫 CastReceiverContext.start 之前)，必須先宣告所有命名空間。 如要宣告命名空間，可以在其中加入訊息監聽器，或在 CastReceiverOptions.customNamespaces 中提供做為起始選項。

const options = new cast.framework.CastReceiverOptions();
options.customNamespaces = {
    CUSTOM_NS: cast.framework.system.MessageType.JSON
};
context.start(options);

context.sendCustomMessage(CUSTOM_NS, {
  type: 'status'
  message: 'Playing'
});

預設使用者介面

CAF 提供預設的 Web Receiver UI，會視需要顯示播放進度列和媒體中繼資料。預設 UI 是以自訂元素 (<cast-media-player>) 的形式提供，其可以使用 CSS 式樣式設定樣式。

<style>
   cast-media-player { --splash-image: url("splash.png"); }
</style>
<cast-media-player></cast-media-player>

如要進一步自訂，Web Receiver 應用程式可以實作專屬的 UI。網路接收器提供 cast.framework.ui.PlayerDataBinder 類別，協助將 UI 物件繫結至 Web 接收器的播放狀態。