迁移到 Web Receiver

本指南介绍了如何将 Cast 接收器 v2 应用迁移到最新版 Web 接收器应用。

全新的 Cast 应用框架 (CAF) SDK（也称为 Web Receiver v3）是 从 Receiver v2 SDK 进行重大升级。Web Receiver SDK 提供了 简单、简化的 SDK，用于开发媒体网络接收器应用。

Web Receiver 提供的 API 与新 CAF 发送器更加一致 API。它完全集成了播放器（MPL 和 Shaka）， Cast 媒体和 Google 助理的实现和支持 语音指令。CAF SDK 还提供了一个可轻松设置样式的默认界面 以及数据绑定服务来简化界面实现

为什么迁移？

将 Receiver v2 应用迁移到 Web Receiver 时，需要处理的 可以消除，这样您就可以专注于写作 特定于应用的业务逻辑。

CAF 无缝集成了 MPL 和 Shaka 播放器，以支持更广泛的 内容类型包括 HTTP Live Streaming（TS 和 CMAF）、MPEG-DASH、Smooth 媒体元素来源属性支持的流式传输和类型（MP3、MP4、 Icecast 等）。如需查看完整列表，请参阅 Google Cast 支持的媒体。 目前，CAF 不支持用户提供的播放器。

迁移到 CAF 将支持通过 Google 助理进行语音控制。 在以下情况下，系统会自动支持任何新的 Google 助理语音指令： 使用 CAF。

除了支持新的媒体指令外，还支持“按语言更改曲目” 和“更改播放速率”-CAF 还改进了队列功能，内置广告 和更好的实时支持服务

有什么变化？

Web Receiver API 会尝试遵循 的 CAF 发送器 Android 和 iOS、 它与 v2 有很大不同。

Web 接收器使用的是新的命名空间 cast.framework 而不是 cast.receiver 命名空间。许多 v2 使用的数据对象在 CAF 中是相同的， 该 cast.framework.messages 命名空间（它们大多位于 cast.receiver.media 下）。

以下 v2 服务已替换为相应的 CAF 服务：

• CastReceiverManager 类已替换为 CastReceiverContext 这是一个单例，用于管理投放会话、发送者、发送自定义 消息和全局系统事件。通过 CastReceiverOptions 可用于提供全局应用选项（例如队列、接收器 版本、播放配置等）。
• MediaManager 类已替换为 PlayerManager 它是 CastReceiverContext 它管理媒体会话、媒体请求、 Google 助理语音指令（v2 中的 CommandAndControlManager）， 和触发媒体事件。玩家配置 （MPL 中的 cast.player.api.Host）由 PlaybackConfig, 可以全局提供，也可以按加载请求提供

PlayerManager 还公开了新的子级管理器类：

• TextTracksManager - 管理媒体文本轨道。
• AudioTracksManager - 管理音轨。
• QueueManager - 管理队列。
• BreakManager - 管理广告。

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)。 Web Receiver 可以针对一个事件使用多个事件监听器（监听器 不会影响事件），并且每条消息都有一个拦截器。拦截器 可以更新或处理请求（返回修改后的请求， 消息或错误消息），它们可以是返回 promise 的异步处理程序。

加载请求拦截器是最常添加 特定于应用的逻辑。对于来自发送者的加载请求，加载 拦截器可以将内容 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 接收器应用： 在媒体状态下公开媒体网址可以提供网址解析器 (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。 Web 接收器应用可以为任何事件设置多个监听器， 也可以为多个事件提供一个监听器。（请参阅 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 接收器界面，该界面会显示播放进度条和 媒体元数据。默认界面是作为自定义元素提供的 (<cast-media-player>) 可使用类似于 CSS 的样式来设置样式

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

如需进行更多自定义，网络接收器应用可以实现自己的界面。通过 Web Receiver 提供 cast.framework.ui.PlayerDataBinder 类来帮助将界面对象绑定到网络接收器播放状态。