對 Cast 接收器應用程式進行偵錯

1. 總覽

Google Cast 標誌

本程式碼研究室將說明如何將 Cast Debug Logger 新增至現有的自訂網頁接收器應用程式。

什麼是 Google Cast？

Google Cast SDK 可讓應用程式在支援 Google Cast 的裝置上播放內容及控制播放作業。並根據 Google Cast 設計檢查清單提供必要的 UI 元件。

我們提供 Google Cast 設計檢查清單，確保所有支援的平台都能提供簡單易懂的 Cast 使用者體驗。

我們要建構什麼內容？

完成本程式碼研究室後，您將擁有與 Cast Debug Logger 整合的自訂網頁接收器。

詳情請參閱 Cast 偵錯記錄器指南。

課程內容

  • 如何設定 Web Receiver 開發環境。
  • 如何將偵錯記錄器整合至 Cast 接收器。

軟硬體需求

體驗

  • 您應具備先前的 Cast 經驗，並瞭解 Cast 網頁接收器運作方式。
  • 須具備先前的網頁開發知識。
  • 你還需要具備觀看電視的相關知識 :)

您會如何使用本教學課程？

僅閱讀 閱讀並完成練習

您對建構網頁應用程式的體驗滿意嗎？

新手 中級 熟練

你對觀看電視的體驗滿意嗎？

新手 中級 熟練

2. 取得程式碼範例

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

並解壓縮下載的 ZIP 檔案。

3. 在本機部署接收器

如要透過 Cast 裝置使用網頁接收器，必須將接收器代管在 Cast 裝置可存取的位置。如果您已有支援 HTTPS 的伺服器，請略過下列操作說明，並記下網址，因為您會在下一節用到。

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

執行伺服器

設定好所選服務後，請前往 app-start 並啟動伺服器。

請記下代管接收器的網址。您會在下一節中使用這項資訊。

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

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

圖片：Cast 開發人員控制台，並以方框特別標出「Add New Application」(新增應用程式) 按鈕。

按一下「新增應用程式」

「New Receiver Application」(新增接收器應用程式) 畫面圖片，當中標出「Custom Receiver」(自訂接收器) 選項

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

圖片：填寫「New Custom Receiver」(新增自訂接收器) 對話方塊中的「Receiver Application URL」(接收器應用程式網址) 欄位

輸入新接收器的詳細資料，請務必使用上一節中的網址。記下指派給全新接收器的應用程式 ID。

您也必須註冊 Google Cast 裝置，才能在發布接收器應用程式前存取該應用程式。發布接收器應用程式後，所有 Google Cast 裝置都能使用。在本程式碼研究室中，建議使用未發布的接收器應用程式。

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

按一下「新增裝置」

「新增 Cast 接收端裝置」對話方塊圖片

輸入 Cast 裝置背面印製的序號，並為裝置取個清楚易懂的名稱。你也可以在存取 Google Cast SDK 開發人員控制台時，透過 Chrome 投放螢幕畫面來查看序號

接收器和裝置需要 5 到 15 分鐘才能準備好進行測試。等待 5 到 15 分鐘後，請重新啟動 Cast 裝置。

5. 執行範例應用程式

Google Chrome 標誌

在等待新版網頁接收器準備好進行測試的同時，我們先來看看已完成的網頁接收器應用程式範例。我們要建構的接收器能夠使用適應性位元率串流播放媒體。

  1. 在瀏覽器中開啟命令與控制 (CaC) 工具。

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

  1. 使用預設 CC1AD845 接收器 ID，然後點選 SET APP ID 按鈕。
  2. 按一下左上方的「投放」按鈕，然後選取支援 Google Cast 的裝置。

這張圖片顯示「Command and Control (CaC) Tool」的「Cast Connect & Logger Controls」分頁，指出已連線至接收器應用程式

  1. 前往頂端的「LOAD MEDIA」分頁標籤。

指令與控制 (CaC) 工具的「Load Media」(載入媒體) 分頁圖片

  1. 將要求類型單選按鈕變更為 LOAD。
  2. 按一下 SEND REQUEST 按鈕，即可播放範例影片。
  3. 影片會在支援 Google Cast 的裝置上開始播放，顯示使用預設接收器時的基本接收器功能。

6. 準備啟動專案

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

  • 傳送者應用程式在行動裝置或筆電上執行，
  • Google Cast 或 Android TV 裝置上執行接收器應用程式。

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

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

請注意，在您完成本程式碼研究室時，http-server 應會擷取您所做的變更。如果沒有，請嘗試停止並重新啟動 http-server。

應用程式設計

接收器應用程式會初始化 Cast 工作階段，並待命直到收到傳送端傳送的 LOAD 要求 (例如播放媒體的指令)。

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

index.html

這個 HTML 檔案包含接收器應用程式的所有 UI。

receiver.js

這個指令碼會管理接收器應用程式的所有邏輯。

常見問題

7. 整合 CastDebugLogger API

開發人員也可以使用 CastDebugLogger API，輕鬆偵錯接收器應用程式。

詳情請參閱 Cast 偵錯記錄器指南。

初始化

在接收器應用程式的 <head> 標記中，緊接在 Web 接收器 SDK 指令碼後方，加入下列指令碼：index.html

<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 執行個體，並在 READY 事件監聽器中啟用記錄器：

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 的疊加層。

圖片：影片正在播放，畫面左上角以紅色背景顯示「DEBUG MODE」訊息

記錄播放器事件

使用 CastDebugLogger 即可輕鬆記錄 Cast 網頁接收器 SDK 觸發的播放器事件，並使用不同的記錄器層級記錄事件資料。loggerLevelByEvents 設定會採用 cast.framework.events.EventType 和 cast.framework.events.category，指定要記錄的事件。

在 READY 事件監聽器下方新增下列項目，以便在觸發播放器 CORE 事件或廣播 mediaStatus 變更時記錄：

...

// 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);

關於每個記錄方法，第一個參數都應該是自訂標記，第二個參數則是記錄訊息。任何感覺有用的字串都可以設成標記。

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

playerManager.setMessageInterceptor(cast.framework.messages.MessageType.LOAD,
      loadRequestData => {
    // Listed in order from highest to lowest priority.
    castDebugLogger.error(LOG_TAG, 'Test error log');

    castDebugLogger.warn(LOG_TAG, 'Test warn log');

    castDebugLogger.info(LOG_TAG, 'Intercepting LOAD request', loadRequestData);

    castDebugLogger.debug(LOG_TAG, 'Test debug log');

    return loadRequestData;
  }
);

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

loggerLevelByTags 設定為選用項目。如果沒有為記錄器層級設定自訂標記，所有記錄訊息都會顯示在偵錯重疊畫面中。

在 loggerLevelByEvents 呼叫下方新增下列程式碼：

...

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

...

8. 使用偵錯重疊畫面

Cast 偵錯記錄器會在接收器上提供偵錯疊加層，顯示自訂記錄訊息。使用 showDebugLogs 切換偵錯重疊畫面，並使用 clearDebugLogs 清除重疊畫面上的記錄訊息。

在 READY 事件監聽器中新增下列內容，即可在接收器上預覽偵錯重疊畫面：

// 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);

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

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

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

9. 使用指揮與控制 (CaC) 工具

總覽

指令與控制 (CaC) 工具會擷取記錄檔，並控制偵錯疊加層。

你可以透過兩種方式將接收器連線至 CaC 工具：

開始新的 Cast 連線：

  1. 開啟 CaC 工具，設定接收端應用程式 ID，然後按一下「Cast」按鈕，將內容投放到接收端。
  2. 將不同的傳送者應用程式投放到同一部裝置，並使用相同的接收器應用程式 ID。
  3. 從傳送者應用程式載入媒體，工具上就會顯示記錄訊息。

加入現有的 Cast 工作階段：

  1. 使用接收器 SDK 或傳送器 SDK 取得執行中的 Cast 工作階段 ID。在接收端，於 Chrome 遠端偵錯工具控制台中輸入下列內容，即可取得工作階段 ID：
cast.framework.CastReceiverContext.getInstance().getApplicationData().sessionId;

或者，您也可以從已連線的網頁傳送器取得工作階段 ID，方法如下：

cast.framework.CastContext.getInstance().getCurrentSession().getSessionId();

「Cast Connect & Logger Controls」(Cast Connect 和記錄器控制項) 分頁的圖片，顯示如何使用 Command and Control (CaC) 工具繼續工作階段

  1. 在 CaC 工具中輸入工作階段 ID，然後按一下 RESUME 按鈕。
  2. 「投放」按鈕應已連線，並開始在工具上顯示記錄訊息。

建議做法

接著，我們將使用 CaC 工具查看範例接收器的記錄。

  1. 開啟 CaC 工具。

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

  1. 輸入範例應用程式的接收器應用程式 ID，然後按一下 SET APP ID 按鈕。
  2. 按一下左上方的「投放」按鈕，然後選取支援 Google Cast 的裝置，開啟接收器。

這張圖片顯示「Command and Control (CaC) Tool」的「Cast Connect & Logger Controls」分頁，指出已連線至接收器應用程式

  1. 前往頂端的「LOAD MEDIA」分頁標籤。

指令與控制 (CaC) 工具的「Load Media」(載入媒體) 分頁圖片

  1. 將要求類型單選按鈕變更為 LOAD。
  2. 按一下 SEND REQUEST 按鈕，即可播放範例影片。

「Command and Control (CaC) Tool」的「Cast Connect & Logger Controls」分頁圖片，底部窗格填滿記錄訊息

  1. 裝置現在應該會播放範例影片。您應該會開始在工具底部的「記錄訊息」分頁中，看到先前步驟中的記錄。

您可以嘗試使用下列功能來調查記錄及控制接收器：

  • 按一下「MEDIA INFO」或「MEDIA STATUS」分頁標籤，即可查看媒體資訊和媒體狀態。
  • 按一下 SHOW OVERLAY 按鈕，即可在接收器上查看偵錯疊加層。
  • 使用 CLEAR CACHE AND STOP 按鈕重新載入接收器應用程式，然後再次投放。

10. 恭喜

您現在已瞭解如何使用最新版 Cast Receiver SDK，在支援 Cast 的 Web Receiver 應用程式中加入 Cast Debug Logger。

詳情請參閱「Cast 偵錯記錄器」和「指令與控制 (CaC) 工具」開發人員指南。