调试 Cast 接收器应用

1. 概览

Google Cast 徽标

在此 Codelab 中，您将学习如何将 Cast 调试日志记录器添加到现有的自定义 Web 接收器应用。

什么是 Google Cast？

借助 Google Cast SDK，您的应用可以在支持 Google Cast 的设备上播放内容并控制播放。它会根据 Google Cast 设计核对清单为您提供必需的界面组件。

Google Cast 设计核对清单用于在所有支持的平台上实现简单、可预测的 Cast 用户体验。

构建目标

完成此 Codelab 后，您将获得一个与 Cast 调试日志记录器集成的自定义 Web 接收器。

如需了解详情，请参阅 Cast 调试日志记录器指南。

学习内容

  • 如何设置环境以进行 Web 接收器开发。
  • 如何将调试日志记录器集成到 Cast 接收器中。

所需条件

体验

  • 您应拥有投放经验并了解 Cast Web 接收器的工作原理。
  • 您需要具备 Web 开发经验。
  • 您还需要有观看电视的经验 :)

您打算如何使用本教程？

仅阅读教程内容 阅读并完成练习

您如何评价自己在构建 Web 应用方面的经验水平？

新手水平 中等水平 熟练水平

您如何评价自己在观看电视方面的经验水平？

新手 中等 熟练

2. 获取示例代码

您可以将所有示例代码下载到您的计算机…

然后解压下载的 zip 文件。

3. 在本地部署接收器

为了能将 Web 接收器与 Cast 设备搭配使用，需要将接收器托管在 Cast 设备可以访问的某个位置。如果您已有一台支持 https 的服务器可供使用，请跳过以下说明并记下其网址，因为下一部分需要用到该网址。

如果您没有可用的服务器，可以使用 Firebase Hosting 或 ngrok。

运行服务器

设置好所需的服务后，前往 app-start 并启动服务器。

记下托管接收器的网址。您将在下一部分中使用它。

4. 在 Cast Developer Console 中注册应用

您必须注册应用，才能在 Chromecast 设备上运行此 Codelab 中构建的自定义网络接收器。注册应用后，您会收到一个应用 ID，发送器应用必须使用此 ID 来执行 API 调用，以实现启动接收器应用等目的。

Cast Developer Console 的图片，其中突出显示了“添加新应用”按钮

点击“Add new application”

“新建接收器应用”屏幕的图片，其中突出显示了“自定义接收器”选项

选择“Custom Receiver”，这是我们正在构建的内容。

正在填写“新建自定义接收器”对话框中的“接收器应用网址”字段的图片

输入新接收器的详细信息，请务必使用上一部分中的网址。记下分配给新接收器的应用 ID。

您还必须注册 Google Cast 设备，以便该设备可在您发布接收器应用前对其进行访问。接收器应用发布后，便可供所有 Google Cast 设备使用。在此 Codelab 中，建议使用未发布的接收器应用。

Google Cast SDK 开发者控制台的图片，其中突出显示了“添加新设备”按钮

点击“Add new Device”

“Add Cast Receiver Device”（添加投屏接收器设备）对话框的图片

输入 Cast 设备背面印刷的序列号，并为其指定一个描述性名称。在访问 Google Cast SDK Developer Console 时将屏幕投射到 Chrome 中，也可以找到此序列号

接收器和设备需要 5-15 分钟才能准备好进行测试。等待 5-15 分钟后，您必须重新启动 Cast 设备。

5. 运行示例应用

Google Chrome 徽标

在等待新 Web 接收器做好测试准备期间，我们来看看完成后的示例 Web 接收器应用外观是怎样的。我们要构建的接收器能够使用自适应比特率流式传输来播放媒体内容。

  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) 工具的“加载媒体”标签页的图片

  1. 将请求类型单选按钮更改为 LOAD。
  2. 点击 SEND REQUEST 按钮播放示例视频。
  3. 视频即会在支持 Google Cast 的设备上开始播放，向您展示使用默认接收器时的基本接收器功能。

6. 准备起始项目

我们需要在您下载的入门级应用中添加 Google Cast 支持。下面是一些我们会在此 Codelab 中使用的 Google Cast 术语：

  • 发送设备应用是指在移动设备或笔记本电脑上运行的应用；
  • 接收器应用是指在 Google Cast 或 Android TV 设备上运行的应用。

现在，您可以使用自己喜爱的文本编辑器基于起始项目构建应用了：

  1. 从下载的示例代码中选择 文件夹图标app-start 目录。
  2. 打开 js/receiver.js 和 index.html

请注意，在执行此 Codelab 的过程中，http-server 应该会应用您所做的更改。如果没有，请尝试停止并重启 http-server。

应用设计

接收设备应用初始化 Cast 会话，并一直待机，直到接收程序收到 LOAD 请求（例如播放某项媒体的命令）。

该应用包含一个主视图（在 index.html 中定义）和一个名为 js/receiver.js 的 JavaScript 文件，该文件中包含接收器正常运行所需的全部逻辑。

index.html

此 HTML 文件包含接收器应用的所有界面。

receiver.js

此脚本会管理接收器应用的所有逻辑。

常见问题解答

7. 与 CastDebugLogger API 集成

Cast 接收器 SDK 为开发者提供了另一种选择：他们可以使用 CastDebugLogger API 轻松调试接收器应用。

如需了解详情，请参阅 Cast 调试日志记录器指南。

初始化

在接收器应用的 <head> 标记中，紧跟 Web Receiver 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 Web 接收器 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 工具：

建立新的投屏连接：

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

用于恢复会话的命令与控制 (CaC) 工具的“Cast Connect & Logger Controls”（投放连接和日志记录器控件）标签页的图片

  1. 在 CaC 工具中输入会话 ID，然后点击 RESUME 按钮。
  2. Cast 按钮应已连接，并开始在该工具上显示日志消息。

可尝试的操作

接下来，我们将使用 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) 工具的“加载媒体”标签页的图片

  1. 将请求类型单选按钮更改为 LOAD。
  2. 点击 SEND REQUEST 按钮播放示例视频。

命令与控制 (CaC) 工具的“Cast Connect & Logger Controls”（Cast Connect 和 Logger 控件）标签页的图片，底部窗格中填充了日志消息

  1. 示例视频现在应该正在你的设备上播放。您应该会看到，前面步骤中的日志开始显示在该工具底部的“Log Messages”（日志消息）标签页中。

请尝试探索以下功能，以便调查日志和控制接收器：

  • 点击 MEDIA INFO 或 MEDIA STATUS 标签页可查看媒体信息和媒体状态。
  • 点击 SHOW OVERLAY 按钮可在接收器上查看调试叠加层。
  • 使用 CLEAR CACHE AND STOP 按钮重新加载接收器应用，然后重新投放。

10. 恭喜

现在，您已经知道如何使用最新的 Cast 接收器 SDK 将 Cast 调试日志记录器添加到支持 Cast 的 Web 接收器应用。

如需了解详情，请参阅 Cast Debug Logger 和命令与控制 (CaC) 工具开发者指南。