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

1. 總覽

Google Cast 標誌

本程式碼研究室將說明如何將 Cast 偵錯記錄器新增至現有的自訂 Web Receiver 應用程式。

什麼是 Google Cast？

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

Google Cast 設計檢查清單可讓 Cast 使用者體驗在所有支援平台上都簡單易懂。

我們要建構什麼內容？

完成這個程式碼研究室後，您就會擁有與 Cast 偵錯記錄器整合的自訂網頁接收器。

詳情請參閱 Cast Debug Logger 指南。

課程內容

  • 如何設定 Web Receiver 開發環境。
  • 如何將 Debug Logger 整合至 Cast Receiver。

軟硬體需求

體驗

  • 你必須具有投放功能，並瞭解 Cast Web 接收器的運作方式。
  • 您必須具備網路開發相關知識。
  • 你也需要具備觀看電視的相關知識 :)

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

只閱讀 閱讀並完成練習

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

新手 中級 熟練

請評分你觀看電視的體驗。

新手 中級 熟練

2. 取得程式碼範例

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

並解壓縮下載的 ZIP 檔案。

3. 在本機部署接收器

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

如果你沒有可用伺服器，可改用 Firebase 代管或 ngrok。

執行伺服器

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

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

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

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

Cast 開發人員控制台的圖片，特別框出「新增應用程式」按鈕

按一下「新增應用程式」

「新增接收端應用程式」畫面的圖片，以方框特別標出「自訂接收端」選項

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

「New Custom Receiver」對話方塊中「Receiver Application URL」欄位填入內容的圖片

輸入新收件者的詳細資料，請務必使用上一個部分的網址。記下新接收器的應用程式 ID。

您也必須註冊 Google Cast 裝置，讓裝置在您發布接收器應用程式前，先存取該應用程式。發布接收器應用程式後，所有 Google Cast 裝置都會提供這項應用程式。就本程式碼研究室而言，建議您使用尚未發布的接收器應用程式。

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

按一下「新增裝置」

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

輸入 Cast 裝置背面所印的序號，並為裝置取個說明性的名稱。你也可以在 Chrome 中投放螢幕畫面，然後存取 Google Cast SDK 開發人員控制台，藉此查看序號。

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

5. 執行範例應用程式

Google Chrome 標誌

等待新版 Web Receiver 處於測試狀態的期間，現在就來看看已完成的 Web Receiver 應用程式的樣子。我們要建立的接收器將能透過自動調整位元率串流播放媒體。

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

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

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

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

  1. 前往頂端的 LOAD MEDIA 分頁。

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

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

6. 準備 start 專案

我們需要在你下載的啟動應用程式中新增 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 檔案包含接收端應用程式的所有使用者介面。

receiver.js

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

常見問題

7. 與 CastDebugLogger API 整合

Cast Receiver SDK 提供另一個選項，可讓開發人員使用 CastDebugLogger API 輕鬆對接收器應用程式進行偵錯。

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

初始化

在 index.html 中，在 Web 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 例項，並在 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 重疊圖層。

播放影片的圖片，影格左上角以紅色背景顯示「偵錯模式」訊息

記錄播放器事件

使用 CastDebugLogger 時，您可以輕鬆記錄由 Cast Web Receiver 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 Debug Logger 會在接收端提供偵錯疊加畫面，顯示自訂記錄訊息。使用 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 工具：

開始新的投放連線：

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

加入現有的投放工作階段：

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

您也可以使用下列方法，從已連結的網頁傳送端取得工作階段 ID：

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

圖片：Command and Control (CaC) 工具的「Cast Connect & Logger Controls」分頁，可用於繼續工作階段

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

建議做法

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

  1. 開啟 CAC 工具。

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

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

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

  1. 前往頂端的 LOAD MEDIA 分頁。

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

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

圖片：指揮與控制 (CaC) 工具的「Cast Connect & Logger Controls」分頁，底部窗格顯示大量記錄訊息

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

請嘗試下列功能來調查記錄及控制接收端：

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

10. 恭喜

您現在已瞭解如何使用最新的 Cast Receiver SDK，將 Cast 偵錯記錄器新增至支援 Cast 的 Web Receiver 應用程式。

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