建立自訂網路接收器

1. 總覽

Google Cast 標誌

本程式碼研究室將說明如何建立自訂網路接收器應用程式，以便在支援 Cast 功能的裝置上播放內容。

什麼是 Google Cast？

Google Cast 可讓使用者將行動裝置的內容投放到電視上。接著，使用者可以將行動裝置或電腦版 Chrome 瀏覽器當做遙控器，以便在電視上播放媒體。

Google Cast SDK 可讓您應用程式控制支援 Google Cast 的裝置 (例如電視或音響系統)。Cast SDK 會根據 Google Cast 設計檢查清單提供必要的 UI 元件。

我們制訂了 Google Cast 設計檢查清單，以期在所有支援的平台上提供簡單且可預測的 Cast 使用者體驗。請按這裡瞭解詳情。

我們要建構哪些項目？

完成本程式碼研究室後，您將擁有 HTML5 應用程式，可做為您專屬的自訂接收器，在支援 Cast 的裝置上顯示影片內容。

課程內容

  • 如何設定接收方開發。
  • 以 Cast 應用程式架構為基礎的支援 Google Cast 接收器基本概念。
  • 如何接收投放影片。
  • 如何整合偵錯記錄器。
  • 如何最佳化智慧螢幕的接收器。

軟硬體需求

功能

  • 您必須具備先前的網站開發知識。
  • 此外，您還必須具備觀看電視節目的相關知識 :)

您會如何使用這個教學課程？

僅詳讀 唸出並完成練習

根據您建構網頁應用程式的經驗，您會給予什麼評價？

11 月 中級 專業

根據您看電視的經驗，您會給予什麼評價？

11 月 中級 專業

2. 取得範例程式碼

您可以將所有程式碼範例下載到電腦上...

並將下載的 ZIP 檔案解壓縮

3. 在本機部署接收器

如要將網路接收器搭配投放裝置使用，您必須將裝置代管在可安裝投放裝置的位置。如果您已有支援 https 的伺服器，請略過下列操作說明，並記下網址 (下一節將會用到)。

如果沒有可以使用的伺服器，可以使用 Firebase 託管或 ngrok。

執行伺服器

設定您選擇的服務後，請前往 app-start 並啟動伺服器。

請記下代管接收器的網址。您會在下一節中用到。

4. 在 Cast 開發人員控制台中註冊應用程式

您必須註冊應用程式，才能在 Chromecast 裝置上執行自訂接收器 (如本程式碼研究室所述)。註冊應用程式之後，您會收到傳送應用程式 ID，傳送者應用程式必須使用這個 ID 執行 API 呼叫 (例如啟動接收器應用程式)。

Google Cast SDK 開發人員控制台的圖片，其中醒目顯示「新增應用程式」按鈕

按一下「新增應用程式」

「新接收端應用程式」畫面的圖片，醒目顯示的是「自訂接收端」選項

選取「自訂接收端」，這就是我們正在建構的項目。

「新增自訂接收器」畫面的圖片，顯示有人正在「接收端應用程式網址」欄位輸入網址

輸入新接收者的詳細資料，請務必使用您當初提交的網址

。記下指派給全新接收者的應用程式 ID。

您也必須註冊 Google Cast 裝置，以便在發布前存取接收端應用程式。發布接收端應用程式後，即可供所有 Google Cast 裝置使用。基於本程式碼研究室的目的，建議您選用未發布的接收端應用程式。

Google Cast SDK 開發人員控制台的圖片，其中醒目顯示「新增裝置」按鈕

按一下「新增裝置」

「新增投放接收端裝置」對話方塊的圖片

輸入印在投放裝置背面的序號，並為序號取個描述性名稱。存取 Google Cast SDK 開發人員控制台時，您也可以在 Chrome 中投放螢幕來找到序號

接收器和裝置可能需要 5 到 15 分鐘才能完成測試，等待 5 到 15 分鐘後，您必須重新啟動投放裝置。

5. 執行範例應用程式

Google Chrome 標誌

在等待新的接收方應用程式準備測試期間，我們來看看已完成的接收器應用程式範例看起來會是什麼樣子。我們您要建構的接收器可以使用可自動調整位元率串流播放媒體 (我們將使用經過編碼的範例內容，透過 HTTP (DASH) 進行動態自動調整串流處理)。

在瀏覽器中開啟「Command and Control (CaC)」工具。

指令和控制 (CaC) 工具的「Cast Connect & Logger Controls」分頁圖片

  1. 您應該會看到我們的 CaC 工具。
  2. 使用預設的「CC1AD845」範例接收端 ID，然後點選「設定應用程式 ID」按鈕。
  3. 按一下左上方的「投放」按鈕，然後選取你的 Google Cast 裝置。

「指令與控制」(CaC) 工具的「Cast Connect & Logger Controls」分頁圖片，顯示已連線至接收端應用程式

  1. 前往頂端的「Load Media」分頁。

指令和控制 (CaC) 工具的「Load Media」分頁圖片

  1. 按一下「依內容載入」按鈕，即可播放範例影片。
  2. 影片會開始在您的 Google Cast 裝置上播放，示範使用預設接收器的基本接收器功能。

6. 準備 start 專案

我們需要在你下載的啟動應用程式中新增 Google Cast 支援。以下是本程式碼研究室會使用的 Google Cast 相關術語：

  • 寄件者應用程式是在行動裝置或筆記型電腦上執行
  • 接收端應用程式是在 Google Cast 裝置上執行。

您現在可以使用自己慣用的文字編輯器，在範例專案的基礎上進行建構：

  1. 從下載的程式碼範例中選取 「資料夾」圖示app-start 目錄。
  2. 開啟 js/receiver.js 和 index.html

請注意，逐步完成本程式碼研究室時，http-server 應擷取您做的變更。如果發現沒有出現，請嘗試終止並重新啟動 http-server。

應用程式設計

接收端應用程式會初始化 Cast 工作階段，並會待在傳送端發出 LOAD 要求 (也就是播放媒體片段的指令) 之前。

應用程式包含一個主要檢視畫面 (在 index.html 中定義)，以及一個名為 js/receiver.js 的 JavaScript 檔案，內含讓接收器工作的所有邏輯。

index.html

這個 HTML 檔案將包含接收器應用程式的使用者介面。目前還沒有內容，我們會在整個程式碼研究室中新增。

receiver.js

這個指令碼會管理接收端應用程式的所有邏輯。目前這是空白檔案，但我們要在下一節使用幾行程式碼，將其變成可正常運作的 Cast 接收器。

7. 基本 Cast 接收器

基本的 Cast 接收器會在啟動時初始化投放工作階段。有必要告知所有連接接收端的應用程式連結傳送者。此外，新版 SDK 已預先設定為可即時處理可自動調整的位元率串流媒體 (使用 DASH、HLS 和流暢串流)，以及立即可用的一般 MP4 檔案。我們來試試看。

初始化

將下列程式碼新增至標頭中的 index.html：

<head>
  ...

  <script src="//www.gstatic.com/cast/sdk/libs/caf_receiver/v3/cast_receiver_framework.js"></script>
</head>

在 <footer> 載入 receiver.js, 之前將下列程式碼新增至 index.html <body>，讓接收端 SDK 有空間來開啟預設接收器 UI，以剛剛新增的指令碼傳送。

<cast-media-player></cast-media-player>

現在，我們需要在 js/receiver.js 中初始化 SDK，包含：

  • 取得 CastReceiverContext 的參照，也就是整個接收端 SDK 的主要進入點
  • 儲存 PlayerManager 的參照、物件處理播放，並提供您自訂邏輯加入的所有掛鉤
  • 透過呼叫 CastReceiverContext 上的 start() 來初始化 SDK

請將以下內容新增至 js/receiver.js。

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

context.start();

8. 投放「基本」影片內容

為達成本程式碼研究室的目的，請使用 CaC Tool 試用全新的接收器。

透過網路瀏覽器指向指令和控制 (CaC) 工具。

指令和控制 (CaC) 工具的「Cast Connect & Logger Controls」分頁圖片

務必以您自己的應用程式 ID 取代您之前在欄位中登錄的應用程式 ID，然後按一下 [Set App ID]。這會指示工具在啟動投放工作階段時使用接收器。

投放媒體

一般來說，如要在投放裝置上播放媒體，必須滿足以下條件：

  1. 傳送者從 Cast SDK 建立 MediaInfo JSON 物件，用來模擬媒體項目。
  2. 傳送者會連線至投放裝置，以啟動接收端應用程式。
  3. 接收端透過 LOAD 要求載入 MediaInfo 物件，以便播放內容。
  4. 接收器會監控及追蹤媒體狀態。
  5. 傳送者會將播放指令傳送至接收端，以便根據使用者與傳送端應用程式的互動來控製播放。

在第一次基本嘗試中，我們會MediaInfo填入可播放的素材資源網址 (儲存在 MediaInfo.contentUrl)。

真實寄件者會使用 MediaInfo.contentId 中的應用程式專屬媒體 ID。接收端會使用 contentId 做為 ID，進行適當的後端 API 呼叫，藉此解析實際資產網址，並將其設為 MediaInfo.contentUrl.。接收器也會處理 DRM 授權取得或插入廣告插播相關資訊等工作。

我們將擴大接收方的功能，在下一節中如下所示。現在請按一下「投放」圖示並選取你的裝置，開啟接收器。

「指令與控制」(CaC) 工具的「Cast Connect & Logger Controls」分頁圖片，顯示已連線至接收端應用程式

前往「Load Media」分頁，然後按一下「Load by Content」按鈕。接收端應開始播放範例內容。

指令和控制 (CaC) 工具的「Load Media」分頁圖片

因此，接收端 SDK 可以立即處理：

  • 初始化投放工作階段
  • 處理來自包含可播放資產的寄件者傳入的 LOAD 要求
  • 提供可在大螢幕上顯示的基本播放器使用者介面。

在繼續閱讀下一節之前，歡迎先探索 CaC 工具及其程式碼，我們會進一步擴充接收端與簡易範例 API 通訊，以執行來自寄件者的 LOAD 要求。

9. 與外部 API 整合

為因應大多數開發人員在實際應用程式中與 Cast 接收器的互動方式，我們將修改接收端，以便處理透過 API 金鑰參照預定媒體內容的 LOAD 要求，而不是透過可播放的資產網址傳送。

應用程式這麼做的常見原因如下：

  • 寄件者可能不知道內容網址。
  • Cast 應用程式設計為直接在接收器上處理驗證、其他商業邏輯或 API 呼叫。

這項功能主要用於 PlayerManager setMessageInterceptor() 方法。這可讓您依類型攔截傳入訊息，並在訊息送達 SDK 的內部訊息處理常式前加以修改。在本節中，我們會處理 LOAD 要求，其中會執行下列操作：

  • 讀取傳入的 LOAD 要求及其自訂 contentId。
  • 對 API 發出 GET 呼叫，以透過 contentId 查詢可串流資產。
  • 使用串流的網址修改 LOAD 要求。
  • 修改 MediaInformation 物件以設定串流類型參數。
  • 將請求傳遞至 SDK 進行播放；如果我們無法查詢要求的媒體，則會拒絕指令。

我們提供的範例 API 展示了 SDK 的掛鉤，讓您自訂常見的接收器工作，同時仍仰賴大部分現成的體驗。

API 範例

請將瀏覽器指向 https://storage.googleapis.com/cpe-sample-media/content.json，並參閱我們的影片目錄範例。內容包含 png 格式的海報圖片網址，以及 DASH 和 HLS 串流。DASH 和 HLS 串流會指向儲存在片段 mp4 容器中的經過編碼的影片和音訊來源。

{
  "bbb": {
    "author": "The Blender Project",
    "description": "Grumpy Bunny is grumpy",
    "poster": "https://[...]/[...]/BigBuckBunny/images/screenshot1.png",
    "stream": {
      "dash": "https://[...]/[...]/BigBuckBunny/BigBuckBunny_master.mpd",
      "hls": "https://[...]/[...]/BigBuckBunny/BigBuckBunny_master.m3u8",
    "title": "Big Buck Bunny"
  },
  "fbb_ad": {
    "author": "Google Inc.",
    "description": "Introducing Chromecast. The easiest way to enjoy [...]",
    "poster": "https://[...]/[...]/ForBiggerBlazes/images/screenshot8.png",
    "stream": {
      "dash": "https://[...]/[...]/ForBiggerBlazes/ForBiggerBlazes.mpd",
      "hls": "https://[...]/[...]/ForBiggerBlazes/ForBiggerBlazes.m3u8",
    "title": "For Bigger Blazes"
  },

  [...]

}

在下一個步驟中，我們會使用 LOAD 要求呼叫接收端後，將每個項目的鍵 (例如 bbb, fbb_ad) 對應至串流的網址。

攔截 LOAD 請求

在這個步驟中，我們會使用函式向代管 JSON 檔案發出 XHR 要求，藉此建立載入攔截器。取得 JSON 檔案後，我們會剖析內容並設定中繼資料。在以下各節中，我們將自訂 MediaInformation 參數以指定內容類型。

將下列程式碼新增至 js/receiver.js 檔案，緊接在呼叫 context.start() 之前。

function makeRequest (method, url) {
  return new Promise(function (resolve, reject) {
    let xhr = new XMLHttpRequest();
    xhr.open(method, url);
    xhr.onload = function () {
      if (this.status >= 200 && this.status < 300) {
        resolve(JSON.parse(xhr.response));
      } else {
        reject({
          status: this.status,
          statusText: xhr.statusText
        });
      }
    };
    xhr.onerror = function () {
      reject({
        status: this.status,
        statusText: xhr.statusText
      });
    };
    xhr.send();
  });
}

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD,
    request => {
      return new Promise((resolve, reject) => {
        // Fetch content repository by requested contentId
        makeRequest('GET', 'https://storage.googleapis.com/cpe-sample-media/content.json').then(function (data) {
          let item = data[request.media.contentId];
          if(!item) {
            // Content could not be found in repository
            reject();
          } else {
            // Add metadata
            let metadata = new
               cast.framework.messages.GenericMediaMetadata();
            metadata.title = item.title;
            metadata.subtitle = item.author;

            request.media.metadata = metadata;

            // Resolve request
            resolve(request);
          }
        });
      });
    });

下一節將說明如何為 DASH 內容設定載入要求的 media 屬性。

使用 Sample API DASH 內容

我們已備妥負載攔截器，接下來要為接收端指定內容類型。這項資訊會向接收端提供主要播放清單網址和串流 MIME 類型。將下列程式碼新增至 LOAD 攔截器 Promise() 中的 js/receiver.js 檔案：

...
playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD,
    request => {
      return new Promise((resolve, reject) => {
          ...
          } else {
            // Adjusting request to make requested content playable
            request.media.contentUrl = item.stream.dash;
            request.media.contentType = 'application/dash+xml';
            ...
          }
        });
      });
    });

完成這個步驟後，您就可以繼續進行測試，嘗試使用 DASH 內容載入。如要測試 HTTP 即時串流內容的載入，請執行下一個步驟。

使用 Sample API HLS 內容

範例 API 包括 HLS 內容和 DASH。除了像上個步驟一樣設定 contentType，載入要求還需要一些其他屬性，才能使用範例 API 的 HLS 網址。將接收端設為播放 HLS 串流時，預設容器類型應為傳輸串流 (TS)。因此，如果只修改 contentUrl 屬性，接收端會嘗試以 TS 格式開啟範例 MP4 串流。在載入要求中，應使用額外屬性修改 MediaInformation 物件，讓接收器知道內容的類型是 MP4，而非 TS。將下列程式碼新增至載入攔截器中的 js/receiver.js 檔案，以修改 contentUrl 和 contentType 屬性。此外，請新增 HlsSegmentFormat 和 HlsVideoSegmentFormat 屬性。

...
playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD,
    request => {
      return new Promise((resolve, reject) => {
          ...
          } else {
            // Adjusting request to make requested content playable
            request.media.contentUrl = item.stream.hls;
            request.media.contentType = 'application/x-mpegurl';
            request.media.hlsSegmentFormat = cast.framework.messages.HlsSegmentFormat.FMP4;
            request.media.hlsVideoSegmentFormat = cast.framework.messages.HlsVideoSegmentFormat.FMP4;
            ...
          }
        });
      });
    });

測試看看

再次開啟指令與控制 (CaC) 工具，並將您的應用程式 ID 設為接收方的應用程式 ID。使用「投放」按鈕選取裝置。

前往「Load Media」分頁。這次會刪除「依內容載入」按鈕旁的 [內容網址] 欄位中的文字，這會強制應用程式傳送只含有媒體 contentId 參照的 LOAD 要求。

指令和控制 (CaC) 工具的「Load Media」分頁圖片

假設對接收端所做的修改全都運作正常，攔截器應負責將 MediaInfo 物件塑成可在 SDK 螢幕上播放的內容。

按一下 [依內容載入] 按鈕，查看媒體是否正常播放。如有需要，您可以在 content.json 檔案中將 Content ID 變更為其他 ID。

10. 針對智慧螢幕進行最佳化調整

智慧螢幕是具備觸控功能的裝置，可讓接收器應用程式支援觸控式控制選項。

本節說明如何在智慧螢幕上啟動時顯示最佳化接收器應用程式，以及如何自訂播放器控制項。

存取 UI 控制項

使用 cast.framework.ui.Controls.GetInstance() 可存取智慧螢幕的 UI Controls 物件。請將下列程式碼新增至 context.start() 上方的 js/receiver.js 檔案：

...

// Optimizing for smart displays
const touchControls = cast.framework.ui.Controls.getInstance();

context.start();

如果您未使用 <cast-media-player> 元素，則必須在 CastReceiverOptions 中設定 touchScreenOptimizedApp。在本程式碼研究室中，我們將使用 <cast-media-player> 元素。

context.start({ touchScreenOptimizedApp: true });

系統會根據 MetadataType 和 MediaStatus.supportedMediaCommands 將預設控制按鈕指派給每個版位。

影片控制選項

如果是 MetadataType.MOVIE、MetadataType.TV_SHOW 和 MetadataType.GENERIC，智慧螢幕的 UI Controls 物件將如以下範例所示。

影片上方重疊顯示 UI 控制項。

  1. --playback-logo-image
  2. MediaMetadata.subtitle
  3. MediaMetadata.title
  4. MediaStatus.currentTime
  5. MediaInformation.duration
  6. ControlsSlot.SLOT_SECONDARY_1：ControlsButton.QUEUE_PREV
  7. ControlsSlot.SLOT_PRIMARY_1：ControlsButton.SEEK_BACKWARD_30
  8. PLAY/PAUSE
  9. ControlsSlot.SLOT_PRIMARY_2：ControlsButton.SEEK_FORWARD_30
  10. ControlsSlot.SLOT_SECONDARY_2：ControlsButton.QUEUE_NEXT

音訊控制

如果是 MetadataType.MUSIC_TRACK，智慧螢幕的 UI Controls 物件將如下所示：

圖片上方疊加了 UI 控制項正在播放的音樂

  1. --playback-logo-image
  2. MusicTrackMediaMetadata.albumName
  3. MusicTrackMediaMetadata.title
  4. MusicTrackMediaMetadata.albumArtist
  5. MusicTrackMediaMetadata.images[0]
  6. MediaStatus.currentTime
  7. MediaInformation.duration
  8. ControlsSlot.SLOT_SECONDARY_1：ControlsButton.NO_BUTTON
  9. ControlsSlot.SLOT_PRIMARY_1：ControlsButton.QUEUE_PREV
  10. PLAY/PAUSE
  11. ControlsSlot.SLOT_PRIMARY_2：ControlsButton.QUEUE_NEXT
  12. ControlsSlot.SLOT_SECONDARY_2：ControlsButton.NO_BUTTON

更新支援的媒體指令

UI Controls 物件也會根據 MediaStatus.supportedMediaCommands 判斷是否要顯示 ControlsButton。

當 supportedMediaCommands 的值等於 ALL_BASIC_MEDIA 時，預設的控製版面配置如下所示：

媒體播放器控制項圖片：進度列、「播放」按鈕、「快轉」和「倒轉」按鈕已啟用

當 supportedMediaCommands 的值等於 ALL_BASIC_MEDIA | QUEUE_PREV | QUEUE_NEXT 時，預設的控製版面配置如下所示：

媒體播放器控制項圖片：進度列、「播放」按鈕、「快轉」和「倒轉」按鈕，以及「將上一個項目排入佇列」和「加入待播清單」按鈕已啟用

如果 SupportMediaCommands 的值等於 PAUSE | QUEUE_PREV | QUEUE_NEXT，預設的控製版面配置如下所示：

媒體播放器控制項圖片：進度列、「播放」按鈕、「將上一個項目排入佇列」和「加入待播清單」按鈕已啟用

有文字軌時，系統會一律在 SLOT_1 顯示隱藏式輔助字幕按鈕。

媒體播放器控制項圖片：進度列、「播放」按鈕、「快轉」和「倒轉」按鈕、「將上一個項目排入佇列」和「加入待播清單」按鈕，以及已啟用的「隱藏式輔助字幕」按鈕

如要在啟動接收器結構定義之後動態變更 supportedMediaCommands 的值，您可以呼叫 PlayerManager.setSupportedMediaCommands 來覆寫該值。此外，您可以使用 addSupportedMediaCommands 新增指令，或使用 removeSupportedMediaCommands 移除現有指令。

自訂控制項按鈕

您可以使用 PlayerDataBinder 自訂控制項。將下列程式碼新增至 TouchControls 下方的 js/receiver.js 檔案，以設定控制項的第一個版位：

...

// Optimizing for smart displays
const touchControls = cast.framework.ui.Controls.getInstance();
const playerData = new cast.framework.ui.PlayerData();
const playerDataBinder = new cast.framework.ui.PlayerDataBinder(playerData);

playerDataBinder.addEventListener(
  cast.framework.ui.PlayerDataEventType.MEDIA_CHANGED,
  (e) => {
    if (!e.value) return;

    // Clear default buttons and re-assign
    touchControls.clearDefaultSlotAssignments();
    touchControls.assignButton(
      cast.framework.ui.ControlsSlot.SLOT_PRIMARY_1,
      cast.framework.ui.ControlsButton.SEEK_BACKWARD_30
    );
  });

context.start();

11. 在智慧螢幕上實作媒體瀏覽

媒體瀏覽是 CAF 接收器功能，可讓使用者在觸控裝置上探索其他內容。為實作這一點，您必須使用 PlayerDataBinder 設定 BrowseContent UI。接著，您就可以根據要顯示的內容在當中填入 BrowseItems。

BrowseContent

以下是 BrowseContent UI 及其屬性的範例：

BrowseContent UI 的圖片，其中顯示兩張影片縮圖，以及三分之一的部分

  1. BrowseContent.title
  2. BrowseContent.items

顯示比例

使用 targetAspectRatio property，選取最適合的圖片素材資源顯示比例。CAF 接收器 SDK 支援以下三種長寬比：SQUARE_1_TO_1、PORTRAIT_2_TO_3、LANDSCAPE_16_TO_9。

BrowseItem

使用 BrowseItem 可以顯示每個項目的標題、副標題、長度和圖片：

BrowseContent UI 的圖片，其中顯示兩張影片縮圖，以及三分之一的部分

  1. BrowseItem.image
  2. BrowseItem.duration
  3. BrowseItem.title
  4. BrowseItem.subtitle

設定媒體瀏覽資料

您可以呼叫 setBrowseContent 來提供媒體內容清單，以便瀏覽。在 playerDataBinder 下方的 js/receiver.js 檔案和 MEDIA_CHANGED 事件監聽器中加入下列程式碼，以設定標題為「即將播放」的瀏覽項目。

// Optimizing for smart displays
const touchControls = cast.framework.ui.Controls.getInstance();
const playerData = new cast.framework.ui.PlayerData();
const playerDataBinder = new cast.framework.ui.PlayerDataBinder(playerData);

...

let browseItems = getBrowseItems();

function getBrowseItems() {
  let browseItems = [];
  makeRequest('GET', 'https://storage.googleapis.com/cpe-sample-media/content.json')
  .then(function (data) {
    for (let key in data) {
      let item = new cast.framework.ui.BrowseItem();
      item.entity = key;
      item.title = data[key].title;
      item.subtitle = data[key].description;
      item.image = new cast.framework.messages.Image(data[key].poster);
      item.imageType = cast.framework.ui.BrowseImageType.MOVIE;
      browseItems.push(item);
    }
  });
  return browseItems;
}

let browseContent = new cast.framework.ui.BrowseContent();
browseContent.title = 'Up Next';
browseContent.items = browseItems;
browseContent.targetAspectRatio = cast.framework.ui.BrowseImageAspectRatio.LANDSCAPE_16_TO_9;

playerDataBinder.addEventListener(
  cast.framework.ui.PlayerDataEventType.MEDIA_CHANGED,
  (e) => {
    if (!e.value) return;

    ....

    // Media browse
    touchControls.setBrowseContent(browseContent);
  });

點按媒體瀏覽項目會觸發 LOAD 攔截器。將下列程式碼新增至 LOAD 攔截器，以便從媒體瀏覽項目將 request.media.contentId 對應至 request.media.entity：

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD,
    request => {
      ...

      // Map contentId to entity
      if (request.media && request.media.entity) {
        request.media.contentId = request.media.entity;
      }

      return new Promise((resolve, reject) => {
            ...
        });
    });

您也可以將 BrowseContent 物件設為 null，以移除媒體瀏覽使用者介面。

12. 偵錯接收端應用程式

Cast Receiver SDK 可讓開發人員使用 CastDebugLogger API 以及搭配的 Command and Control (CaC) 工具來擷取記錄，輕鬆對接收端應用程式進行偵錯。

初始化

如要整合 API，請在 index.html 檔案中新增 CastDebugLogger 來源指令碼。請在 Cast Receiver SDK 宣告後方的 <head> 標記中宣告來源。

<head>
  ...
  <script src="//www.gstatic.com/cast/sdk/libs/caf_receiver/v3/cast_receiver_framework.js"></script>
  <!-- Cast Debug Logger -->
  <script src="//www.gstatic.com/cast/sdk/libs/devtools/debug_layer/caf_receiver_logger.js"></script>
</head>

在檔案頂端的 js/receiver.js 和 playerManager 下方，新增下列程式碼，以擷取 CastDebugLogger 執行個體並啟用記錄器：

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

// Debug Logger
const castDebugLogger = cast.debug.CastDebugLogger.getInstance();
const LOG_TAG = 'MyAPP.LOG';

// Enable debug logger and show a 'DEBUG MODE' overlay at top left corner.
context.addEventListener(cast.framework.system.EventType.READY, () => {
  if (!castDebugLogger.debugOverlayElement_) {
      castDebugLogger.setEnabled(true);
  }
});

啟用偵錯記錄器後，顯示 DEBUG MODE 的重疊就會出現在接收器上。

影片正在播放的圖片顯示「偵錯模式」訊息，且畫面左上角出現紅色背景

記錄播放器事件

使用 CastDebugLogger 即可輕鬆記錄由 CAF 接收器 SDK 觸發的玩家事件，並使用不同的記錄器層級來記錄事件資料。loggerLevelByEvents 設定使用 cast.framework.events.EventType 和 cast.framework.events.category 指定要記錄哪些事件。

在 castDebugLogger 宣告下方加入以下程式碼，以記錄觸發玩家 CORE 事件或廣播 mediaStatus 變更時：

// Debug Logger
const castDebugLogger = cast.debug.CastDebugLogger.getInstance();

// Enable debug logger and show a 'DEBUG MODE' overlay at top left corner.
context.addEventListener(cast.framework.system.EventType.READY, () => {
  if (!castDebugLogger.debugOverlayElement_) {
      castDebugLogger.setEnabled(true);
  }
});

// Set verbosity level for Core events.
castDebugLogger.loggerLevelByEvents = {
  'cast.framework.events.category.CORE': cast.framework.LoggerLevel.INFO,
  'cast.framework.events.EventType.MEDIA_STATUS': cast.framework.LoggerLevel.DEBUG
}

記錄訊息和自訂標記

CastDebugLogger API 可讓您建立記錄訊息，顯示在接收器偵錯疊加層上，這些訊息的顏色不同。系統提供以下記錄方法 (按優先順序由高到低列出)：

  • castDebugLogger.error(custom_tag, message);
  • castDebugLogger.warn(custom_tag, message);
  • castDebugLogger.info(custom_tag, message);
  • castDebugLogger.debug(custom_tag, message);

關於每種記錄方法，第一個參數都是自訂代碼。只要是您認為有意義的識別字串，都可以設為這個值。CastDebugLogger 會使用標記來篩選記錄。以下將詳細說明標記的使用方式。第二個參數是記錄訊息。

如要顯示記錄，請將記錄新增至 LOAD 攔截器。

playerManager.setMessageInterceptor(
  cast.framework.messages.MessageType.LOAD,
  request => {
    castDebugLogger.info(LOG_TAG, 'Intercepting LOAD request');

    // Map contentId to entity
    if (request.media && request.media.entity) {
      request.media.contentId = request.media.entity;
    }

    return new Promise((resolve, reject) => {
      // Fetch content repository by requested contentId
      makeRequest('GET', 'https://storage.googleapis.com/cpe-sample-media/content.json')
        .then(function (data) {
          let item = data[request.media.contentId];
          if(!item) {
            // Content could not be found in repository
            castDebugLogger.error(LOG_TAG, 'Content not found');
            reject();
          } else {
            // Adjusting request to make requested content playable
            request.media.contentUrl = item.stream.dash;
            request.media.contentType = 'application/dash+xml';
            castDebugLogger.warn(LOG_TAG, 'Playable URL:', request.media.contentUrl);

            // Add metadata
            let metadata = new cast.framework.messages.MovieMediaMetadata();
            metadata.metadataType = cast.framework.messages.MetadataType.MOVIE;
            metadata.title = item.title;
            metadata.subtitle = item.author;

            request.media.metadata = metadata;

            // Resolve request
            resolve(request);
          }
      });
    });
  });

您可以針對每個自訂標記在 loggerLevelByTags 中設定記錄層級，藉此控制要在偵錯疊加層中顯示哪些訊息。舉例來說，啟用記錄層級 cast.framework.LoggerLevel.DEBUG 的自訂標記，會顯示所有新增的訊息，並列出錯誤、警告、資訊和偵錯記錄訊息。啟用包含 WARNING 層級的自訂標記時，只會顯示錯誤和警告記錄訊息。

loggerLevelByTags 設定是選用項目。如果未針對記錄器層級設定自訂標記，所有記錄訊息都會顯示在偵錯疊加層上。

在 CORE 事件記錄器下方加入下列程式碼：

// Set verbosity level for Core events.
castDebugLogger.loggerLevelByEvents = {
  'cast.framework.events.category.CORE': cast.framework.LoggerLevel.INFO,
  'cast.framework.events.EventType.MEDIA_STATUS': cast.framework.LoggerLevel.DEBUG
}

// Set verbosity level for custom tags.
castDebugLogger.loggerLevelByTags = {
    [LOG_TAG]: cast.framework.LoggerLevel.DEBUG,
};

偵錯重疊

Cast Debug Logger 提供接收端的偵錯重疊，用來在投放裝置上顯示自訂記錄訊息。使用 showDebugLogs 切換偵錯疊加層，並使用 clearDebugLogs 清除疊加層上的記錄訊息。

加入下列程式碼，即可在接收器上預覽偵錯重疊元素。

context.addEventListener(cast.framework.system.EventType.READY, () => {
  if (!castDebugLogger.debugOverlayElement_) {
      // Enable debug logger and show a 'DEBUG MODE' overlay at top left corner.
      castDebugLogger.setEnabled(true);

      // Show debug overlay
      castDebugLogger.showDebugLogs(true);

      // Clear log messages on debug overlay
      castDebugLogger.clearDebugLogs();
  }
});

顯示偵錯重疊畫面的圖片，影片影格上方半透明背景上的偵錯記錄訊息清單

13. 恭喜

您已瞭解如何使用 Cast Web Receiver SDK 建立自訂網路接收器應用程式。

詳情請參閱 Web Receiver 開發人員指南。