向自定义网络接收器添加核心功能

本页包含适用于自定义 Web 接收器应用功能的代码段和说明。

  1. 一个 cast-media-player 元素，表示随 Web 接收器提供的内置播放器界面。
  2. 为 cast-media-player 元素设置类似 CSS 的样式，以便设置各种界面元素（例如 background-image、splash-image 和 font-family）的样式。
  3. 用于加载 Web 接收器框架的脚本元素。
  4. 用于拦截消息和处理事件的 JavaScript 代码。
  5. 加入自动播放队列。
  6. 用于配置播放的选项。
  7. 用于设置 Web 接收器上下文的选项。
  8. 用于设置 Web 接收器应用支持的命令的选项。
  9. 用于启动 Web 接收器应用的 JavaScript 调用。

应用配置和选项

配置应用

CastReceiverContext 是向开发者公开的最外层类，用于管理底层库的加载并处理 Web Receiver SDK 的初始化。SDK 提供的 API 可让应用开发者通过 CastReceiverOptions 配置 SDK。这些配置在每次应用启动时评估一次，并在对 start 的调用中设置可选参数时传递给 SDK。

以下示例展示了如何替换用于检测发送者连接是否仍处于活跃连接状态的默认行为。当网络接收器在 maxInactivity 秒内无法与发送器通信时，系统会分派 SENDER_DISCONNECTED 事件。以下配置会替换此超时。这在调试问题时很有用，因为在 IDLE 状态下没有任何已连接的发件人时，它可以阻止 Web 接收器应用关闭 Chrome 远程调试程序会话。

const context = cast.framework.CastReceiverContext.getInstance();
const options = new cast.framework.CastReceiverOptions();
options.maxInactivity = 3600; // Development only
context.start(options);

配置播放器

加载内容时，Web Receiver SDK 提供了一种使用 cast.framework.PlaybackConfig 配置播放变量（如 DRM 信息、重试配置和请求处理程序）的方法。这些信息由 PlayerManager 处理，并在创建玩家时进行评估。每次向 Web Receiver SDK 传递新加载内容时，系统都会创建播放器。创建播放器后对 PlaybackConfig 所做的修改将在下一次内容加载时进行评估。SDK 提供了以下用于修改 PlaybackConfig 的方法。

以下示例展示了如何在初始化 CastReceiverContext 时设置 PlaybackConfig。该配置会替换用于获取清单的传出请求。该处理程序指定应使用 Cookie 或授权标头等凭据发出 CORS 访问权限控制请求。

const playbackConfig = new cast.framework.PlaybackConfig();
playbackConfig.manifestRequestHandler = requestInfo => {
  requestInfo.withCredentials = true;
};
context.start({playbackConfig: playbackConfig});

以下示例展示了如何使用 PlayerManager 中提供的 getter 和 setter 来替换 PlaybackConfig。该设置会将播放器配置为在加载 1 个片段后继续播放内容。

const playerManager =
    cast.framework.CastReceiverContext.getInstance().getPlayerManager();
const playbackConfig = (Object.assign(
            new cast.framework.PlaybackConfig(), playerManager.getPlaybackConfig()));
playbackConfig.autoResumeNumberOfSegments = 1;
playerManager.setPlaybackConfig(playbackConfig);

以下示例展示了如何使用媒体播放信息处理程序替换特定加载请求的 PlaybackConfig。该处理程序会调用应用实现的方法 getLicenseUrlForMedia，以从当前项的 contentId 中获取 licenseUrl。

playerManager.setMediaPlaybackInfoHandler((loadRequestData, playbackConfig) => {
  const mediaInformation = loadRequestData.media;
  playbackConfig.licenseUrl = getLicenseUrlForMedia(mediaInformation.contentId);

  return playbackConfig;
});

事件监听器

Web Receiver SDK 可让您的 Web 接收器应用处理播放器事件。事件监听器接受 cast.framework.events.EventType 参数（或这些参数的数组），用于指定应触发监听器的事件。您可以在 cast.framework.events.category 中找到可用于调试的预配置 cast.framework.events.EventType 数组。事件参数提供了有关事件的更多信息。

例如，如果您想知道何时广播 mediaStatus 更改，您可以使用以下逻辑处理事件：

const playerManager =
    cast.framework.CastReceiverContext.getInstance().getPlayerManager();
playerManager.addEventListener(
    cast.framework.events.EventType.MEDIA_STATUS, (event) => {
      // Write your own event handling code, for example
      // using the event.mediaStatus value
});

消息拦截

借助 Web Receiver SDK，您的 Web 接收器应用可以拦截消息并对这些消息执行自定义代码。消息拦截器采用 cast.framework.messages.MessageType 参数来指定应拦截的消息类型。

拦截器应返回修改后的请求或使用修改后的请求值进行解析的 Promise。如果返回 null，系统将阻止调用默认消息处理程序。如需了解详情，请参阅加载媒体。

例如，如果要更改加载请求数据，您可以使用以下逻辑拦截和修改它：

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

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD, loadRequestData => {
      const error = new cast.framework.messages.ErrorData(
                      cast.framework.messages.ErrorType.LOAD_FAILED);
      if (!loadRequestData.media) {
        error.reason = cast.framework.messages.ErrorReason.INVALID_PARAM;
        return error;
      }

      if (!loadRequestData.media.entity) {
        return loadRequestData;
      }

      return thirdparty.fetchAssetAndAuth(loadRequestData.media.entity,
                                          loadRequestData.credentials)
        .then(asset => {
          if (!asset) {
            throw cast.framework.messages.ErrorReason.INVALID_REQUEST;
          }

          loadRequestData.media.contentUrl = asset.url;
          loadRequestData.media.metadata = asset.metadata;
          loadRequestData.media.tracks = asset.tracks;
          return loadRequestData;
        }).catch(reason => {
          error.reason = reason; // cast.framework.messages.ErrorReason
          return error;
        });
    });

context.start();

错误处理

当消息拦截器中发生错误时，您的 Web 接收器应用应返回相应的 cast.framework.messages.ErrorType 和 cast.framework.messages.ErrorReason。

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD, loadRequestData => {
      const error = new cast.framework.messages.ErrorData(
                      cast.framework.messages.ErrorType.LOAD_CANCELLED);
      if (!loadRequestData.media) {
        error.reason = cast.framework.messages.ErrorReason.INVALID_PARAM;
        return error;
      }

      ...

      return fetchAssetAndAuth(loadRequestData.media.entity,
                               loadRequestData.credentials)
        .then(asset => {
          ...
          return loadRequestData;
        }).catch(reason => {
          error.reason = reason; // cast.framework.messages.ErrorReason
          return error;
        });
    });

消息拦截与事件监听器

消息拦截和事件监听器之间的一些主要区别如下：

  • 事件监听器不允许您修改请求数据。
  • 事件监听器最适合用于触发分析或自定义函数。
playerManager.addEventListener(cast.framework.events.category.CORE,
    event => {
        console.log(event);
    });
  • 通过消息拦截，您可以监听、拦截消息，以及修改请求数据本身。
  • 消息拦截最适合用于处理与请求数据相关的自定义逻辑。

加载媒体

MediaInformation 提供了许多用于在 cast.framework.messages.MessageType.LOAD 消息中加载媒体的属性，包括 entity、contentUrl 和 contentId。

  • 在针对发送者和接收者应用的实现中，建议使用 entity 属性。该属性是一个深层链接网址，可以是播放列表或媒体内容。您的应用应解析此网址，并至少填充另外两个字段中中的一个。
  • contentUrl 与播放器将用来加载内容的可播放网址对应。例如，此网址可以指向 DASH 清单。
  • contentId 可以是可播放内容网址（类似于 contentUrl 属性的网址），也可以是要加载的内容或播放列表的唯一标识符。如果将此属性用作标识符，应用应在 contentUrl 中填充可播放网址。

建议使用 entity 存储实际 ID 或键参数，并使用 contentUrl 作为媒体的网址。以下代码段显示了一个示例，其中 entity 出现在 LOAD 请求中，并且检索了可播放的 contentUrl：

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

      if (!loadRequestData.media.entity) {
        // Copy the value from contentId for legacy reasons if needed
        loadRequestData.media.entity = loadRequestData.media.contentId;
      }

      return thirdparty.fetchAssetAndAuth(loadRequestData.media.entity,
                                          loadRequestData.credentials)
        .then(asset => {
          loadRequestData.media.contentUrl = asset.url;
          ...
          return loadRequestData;
        });
    });

设备功能

getDeviceCapabilities 方法可提供连接的 Cast 设备以及与其连接的视频或音频设备的相关设备信息。getDeviceCapabilities 方法可为 Google 助理、蓝牙以及连接的显示屏和音频设备提供支持信息。

此方法会返回一个对象，您可以查询该对象，只需传入其中一个指定的枚举以获取该枚举的设备功能即可。枚举在 cast.framework.system.DeviceCapabilities 中定义。

此示例检查网络接收器设备是否能够分别使用 IS_HDR_SUPPORTED 和 IS_DV_SUPPORTED 键播放 HDR 和杜比视界 (DV) 内容。

const context = cast.framework.CastReceiverContext.getInstance();
context.addEventListener(cast.framework.system.EventType.READY, () => {
  const deviceCapabilities = context.getDeviceCapabilities();
  if (deviceCapabilities &&
      deviceCapabilities[cast.framework.system.DeviceCapabilities.IS_HDR_SUPPORTED]) {
    // Write your own event handling code, for example
    // using the deviceCapabilities[cast.framework.system.DeviceCapabilities.IS_HDR_SUPPORTED] value
  }
  if (deviceCapabilities &&
      deviceCapabilities[cast.framework.system.DeviceCapabilities.IS_DV_SUPPORTED]) {
    // Write your own event handling code, for example
    // using the deviceCapabilities[cast.framework.system.DeviceCapabilities.IS_DV_SUPPORTED] value
  }
});
context.start();

处理用户互动

用户可以通过发送器应用（Web、Android 和 iOS）、内置 Google 助理设备上的语音指令、智能显示屏上的触控功能以及 Android TV 设备上的遥控器与 Web 接收器应用互动。Cast SDK 提供了各种 API，以便网络接收器应用处理这些互动、根据用户操作状态更新应用界面，以及选择性地发送更改以更新任何后端服务。

支持的媒体命令

对于 iOS 和 Android 发送器展开控制器、在触摸设备上运行的接收器和遥控器应用，以及 Android TV 设备上的接收器应用，界面控件状态由 MediaStatus.supportedMediaCommands 驱动。在属性中启用特定的按位 Command 后，与该操作相关的按钮会处于启用状态。如果未设置该值，则该按钮将被停用。您可通过以下方式在 Web Receiver 上更改这些值：

  1. 使用 PlayerManager.setSupportedMediaCommands 设置特定的 Commands
  2. 使用 addSupportedMediaCommands 添加新命令
  3. 使用 removeSupportedMediaCommands 移除现有命令。
playerManager.setSupportedMediaCommands(cast.framework.messages.Command.SEEK |
  cast.framework.messages.Command.PAUSE);

当接收器准备好更新后的 MediaStatus 时，它会将更改包含在 supportedMediaCommands 属性中。当状态广播时，已连接的发送方应用会相应地更新其界面中的按钮。

如需详细了解支持的媒体命令和触摸设备，请参阅 Accessing UI controls 指南。

管理用户操作状态

当用户与界面互动或发送语音指令时，他们可以控制与所播放项相关的内容和属性的播放。SDK 会自动处理控制播放的请求。修改当前播放项的属性的请求（如 LIKE 命令）需要接收方应用处理。SDK 提供了一系列 API 来处理这些类型的请求。如需支持这些请求，必须执行以下操作：

  • 加载媒体项时，可以使用用户的偏好设置来设置 MediaInformation userActionStates。
  • 拦截 USER_ACTION 消息并确定请求的操作。
  • 更新 MediaInformation UserActionState 以更新界面。

以下代码段会拦截 LOAD 请求并填充 LoadRequestData 的 MediaInformation。在这种情况下，用户喜欢正在加载的内容。

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD, (loadRequestData) => {
      const userActionLike = new cast.framework.messages.UserActionState(
          cast.framework.messages.UserAction.LIKE);
      loadRequestData.media.userActionStates = [userActionLike];

      return loadRequestData;
    });

以下代码段会拦截 USER_ACTION 消息，并使用请求的更改来调用后端。然后，它会调用以更新接收器上的 UserActionState。

playerManager.setMessageInterceptor(cast.framework.messages.MessageType.USER_ACTION,
  (userActionRequestData) => {
    // Obtain the media information of the current content to associate the action to.
    let mediaInfo = playerManager.getMediaInformation();

    // If there is no media info return an error and ignore the request.
    if (!mediaInfo) {
        console.error('Not playing media, user action is not supported');
        return new cast.framework.messages.ErrorData(messages.ErrorType.BAD_REQUEST);
    }

    // Reach out to backend services to store user action modifications. See sample below.
    return sendUserAction(userActionRequestData, mediaInfo)

    // Upon response from the backend, update the client's UserActionState.
    .then(backendResponse => updateUserActionStates(backendResponse))

    // If any errors occurred in the backend return them to the cast receiver.
    .catch((error) => {
      console.error(error);
      return error;
    });
});

以下代码段模拟了对后端服务的调用。该函数会检查 UserActionRequestData 以查看用户请求的更改类型，并且仅在后端支持该操作时才进行网络调用。

function sendUserAction(userActionRequestData, mediaInfo) {
  return new Promise((resolve, reject) => {
    switch (userActionRequestData.userAction) {
      // Handle user action changes supported by the backend.
      case cast.framework.messages.UserAction.LIKE:
      case cast.framework.messages.UserAction.DISLIKE:
      case cast.framework.messages.UserAction.FOLLOW:
      case cast.framework.messages.UserAction.UNFOLLOW:
      case cast.framework.messages.UserAction.FLAG:
      case cast.framework.messages.UserAction.SKIP_AD:
        let backendResponse = {userActionRequestData: userActionRequestData, mediaInfo: mediaInfo};
        setTimeout(() => {resolve(backendResponse)}, 1000);
        break;
      // Reject all other user action changes.
      default:
        reject(
          new cast.framework.messages.ErrorData(cast.framework.messages.ErrorType.INVALID_REQUEST));
    }
  });
}

以下代码段接受 UserActionRequestData，并从 MediaInformation 中添加或移除 UserActionState。更新 MediaInformation 的 UserActionState 会更改与请求的操作相关联的按钮的状态。此更改反映在智能显示屏控制界面、遥控器应用和 Android TV 界面中。它还通过传出的 MediaStatus 消息进行广播，以便为 iOS 和 Android 发送器更新展开后控制器的界面。

function updateUserActionStates(backendResponse) {
  // Unwrap the backend response.
  let mediaInfo = backendResponse.mediaInfo;
  let userActionRequestData = backendResponse.userActionRequestData;

  // If the current item playing has changed, don't update the UserActionState for the current item.
  if (playerManager.getMediaInformation().entity !== mediaInfo.entity) {
    return;
  }

  // Check for existing userActionStates in the MediaInformation.
  // If none, initialize a new array to populate states with.
  let userActionStates = mediaInfo.userActionStates || [];

  // Locate the index of the UserActionState that will be updated in the userActionStates array.
  let index = userActionStates.findIndex((currUserActionState) => {
    return currUserActionState.userAction == userActionRequestData.userAction;
  });

  if (userActionRequestData.clear) {
    // Remove the user action state from the array if cleared.
    if (index >= 0) {
      userActionStates.splice(index, 1);
    }
    else {
      console.warn("Could not find UserActionState to remove in MediaInformation");
    }
  } else {
    // Add the UserActionState to the array if enabled.
    userActionStates.push(
      new cast.framework.messages.UserActionState(userActionRequestData.userAction));
  }

  // Update the UserActionState array and set the new MediaInformation
  mediaInfo.userActionStates = userActionStates;
  playerManager.setMediaInformation(mediaInfo, true);
  return;
}

语音指令

适用于内置 Google 助理的设备的 Web 接收器 SDK 目前支持以下媒体命令。这些命令的默认实现可在 cast.framework.PlayerManager 中找到。

命令 说明
Google Play 播放或从暂停状态继续播放。
暂停 暂停当前正在播放的内容。
上一步 跳至媒体队列中的上一个媒体项。
继续 跳至媒体队列中的下一个媒体项。
停止 停止当前正在播放的媒体。
不重复 当队列中的最后一项播放完毕后，禁止重复播放队列中的媒体项。
单曲重复 无限重复播放当前播放的媒体。
全部重复 播放完队列中的最后一项后，重复播放队列中的所有项。
全部重复播放并随机播放 当队列中的最后一项播放完毕后，随机打乱队列，然后重复播放该队列中的所有项。
随机播放 随机播放媒体队列中的媒体项。
字幕开启 / 关闭 为媒体启用 / 停用字幕。启用 / 停用还可以按语言进行选择。
跳转至绝对时间 跳转到指定的绝对时间。
跳转至相对于当前时间的时间 向前或向后跳转指定时间段（相对于当前播放时间）。
再玩一次 重播当前播放的媒体，或者播放上次播放的媒体项（如果当前未播放任何内容）。
设置播放速率 改变媒体播放速率。默认情况下，系统会处理此事件。您可以使用 SET_PLAYBACK_RATE 消息拦截器来替换传入的速率请求。

支持的语音指令媒体指令

若要阻止语音指令在内置 Google 助理的设备上触发媒体命令，您必须先设置您计划支持的受支持的媒体命令。然后，您必须通过启用 CastReceiverOptions.enforceSupportedCommands 属性来强制执行这些命令。Cast SDK 发送器和支持触摸的设备上的界面将发生变化，以体现这些配置。如果未启用该标志，系统会执行传入的语音指令。

例如，如果您允许来自发送器应用和支持触摸的设备的 PAUSE，则还必须配置接收器以反映这些设置。配置后，如果收到的语音命令未包含在受支持命令列表中，则这些命令都将被丢弃。

在下面的示例中，我们在启动 CastReceiverContext 时提供了 CastReceiverOptions。我们添加了对 PAUSE 命令的支持，并强制玩家仅支持该命令。现在，如果语音指令请求其他操作（例如 SEEK），该请求将被拒绝。系统会通知用户该命令尚不支持。

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

context.start({
  enforceSupportedCommands: true,
  supportedCommands: cast.framework.messages.Command.PAUSE
});

您可以针对要限制的每个命令应用单独的逻辑。移除 enforceSupportedCommands 标志；对于您要限制的每个命令，您都可以拦截传入消息。在这里，我们会拦截 SDK 提供的请求，以便向内置 Google 助理的设备发出的 SEEK 命令不会在网络接收器应用中触发跳转。

对于您的应用不支持的媒体命令，请返回相应的错误原因，例如 NOT_SUPPORTED。

playerManager.setMessageInterceptor(cast.framework.messages.MessageType.SEEK,
  seekData => {
    // Block seeking if the SEEK supported media command is disabled
    if (!(playerManager.getSupportedMediaCommands() & cast.framework.messages.Command.SEEK)) {
      let e = new cast.framework.messages.ErrorData(cast.framework.messages.ErrorType
      .INVALID_REQUEST);
      e.reason = cast.framework.messages.ErrorReason.NOT_SUPPORTED;
      return e;
    }

    return seekData;
  });

从语音 activity 切换到后台运行

如果 Cast 平台因 Google 助理 activity（例如监听用户语音或回复）而将应用的声音置于后台，则当该 activity 启动时，系统会向 Web 接收器应用发送 NOT_IN_FOCUS 的 FocusState 消息。当 activity 结束时，系统会发送另一条包含 IN_FOCUS 的消息。根据您的应用和正在播放的媒体，您可能需要在 FocusState 为 NOT_IN_FOCUS 时通过拦截消息类型 FOCUS_STATE 来暂停媒体。

例如，如果 Google 助理正在响应用户查询，那么暂停有声读物播放就是一种很好的用户体验。

playerManager.setMessageInterceptor(cast.framework.messages.MessageType.FOCUS_STATE,
  focusStateRequestData => {
    // Pause content when the app is out of focus. Resume when focus is restored.
    if (focusStateRequestData.state == cast.framework.messages.FocusState.NOT_IN_FOCUS) {
      playerManager.pause();
    } else {
      playerManager.play();
    }

    return focusStateRequestData;
  });

指定语音的字幕语言

如果用户没有明确说明字幕的语言，则用于字幕的语言与说出命令时所用的语言相同。在这些场景中，传入消息的 isSuggestedLanguage 参数会指示关联的语言是建议还是用户明确请求。

例如，对于“Ok Google，开启字幕”命令，isSuggestedLanguage 设置为 true，因为语言是根据所说命令的语言推断得出的。如果已明确请求该语言（例如在“Ok Google，开启英语字幕”中），则 isSuggestedLanguage 会设置为 false。

元数据和语音投放

虽然默认情况下由网络接收器处理语音指令，但您应确保内容的元数据是完整准确的。这样可确保 Google 助理正确处理语音指令，并确保元数据能在各种新型界面（例如 Google Home 应用和 Google Home Hub 等智能显示屏）中正确显示。

流式传输

保留会话状态是数据流传输的基础，在这种状态中，用户可以使用语音指令、Google Home 应用或智能显示屏在不同设备之间移动现有的音频和视频串流。媒体在一台设备（源设备）上停止播放，然后在另一台设备（目标设备）上继续播放。任何具有最新固件的 Cast 设备都可以用作数据流传输中的来源或目标。

视频流传输的事件流程如下：

  1. 在源设备上：
    1. 媒体停止播放。
    2. Web 接收器应用收到保存当前媒体状态的命令。
    3. Web Receiver 应用已关闭。
  2. 在目标设备上：
    1. Web Receiver 应用已加载。
    2. Web 接收器应用收到恢复已保存的媒体状态的命令。
    3. 媒体继续播放。

媒体状态的元素包括：

  • 歌曲、视频或媒体内容的具体位置或时间戳。
  • 位于范围更广的队列中（例如播放列表或音乐人电台）。
  • 经过身份验证的用户。
  • 播放状态（例如，正在播放或已暂停）。

启用流式传输

要为网络接收器实现流式传输，请执行以下操作：

  1. 使用 STREAM_TRANSFER 命令更新 supportedMediaCommands：
    playerManager.addSupportedMediaCommands(
cast.framework.messages.Command.STREAM_TRANSFER, true);
  2. 可以选择替换 SESSION_STATE 和 RESUME_SESSION 消息拦截器，如保留会话状态中所述。仅当需要将自定义数据作为会话快照的一部分存储时，才替换这些设置。否则，用于保留会话状态的默认实现将支持数据流传输。

保留会话状态

Web 接收器 SDK 为 Web 接收器应用提供了一种默认实现，可通过以下方式保留会话状态：拍摄当前媒体状态的快照，将状态转换为加载请求，然后使用加载请求恢复会话。

如有必要，可以在 SESSION_STATE 消息拦截器中替换 Web 接收器生成的加载请求。如果您要在加载请求中添加自定义数据，我们建议您将它们放在 loadRequestData.customData 中。

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.SESSION_STATE,
    function (sessionState) {
        // Override sessionState.loadRequestData if needed.
        const newCredentials = updateCredentials_(sessionState.loadRequestData.credentials);
        sessionState.loadRequestData.credentials = newCredentials;

        // Add custom data if needed.
        sessionState.loadRequestData.customData = {
            'membership': 'PREMIUM'
        };

        return sessionState;
    });

可以从 RESUME_SESSION 消息拦截器中的 loadRequestData.customData 检索自定义数据。

let cred_ = null;
let membership_ = null;

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.RESUME_SESSION,
    function (resumeSessionRequest) {
        let sessionState = resumeSessionRequest.sessionState;

        // Modify sessionState.loadRequestData if needed.
        cred_ = sessionState.loadRequestData.credentials;

        // Retrieve custom data.
        membership_ = sessionState.loadRequestData.customData.membership;

        return resumeSessionRequest;
    });

内容预加载

Web 接收器支持在队列中的当前播放项之后预加载媒体项。

预加载操作会预先下载即将发布的内容的多个片段。规范是根据 QueueItem 对象中的 preloadTime 值（如未提供，默认为 20 秒）完成的。该时间以相对于当前播放项的结尾的秒数表示。只有正值才有效。例如，如果值为 10 秒，则此项会在前一项内容播放完毕前 10 秒预加载。如果预加载时间长于 currentItem 的剩余时间，系统会尽快进行预加载。因此，如果为 queueItem 指定了非常大的预加载值，当我们播放当前项时，已经在预加载下一项。不过，我们将具体设置和选择留给开发者，因为该值可能会影响当前播放项的带宽和流式传输性能。

默认情况下，预加载适用于 HLS、DASH 和流畅流式传输内容。

系统不会预加载常规 MP4 视频和音频文件（例如 MP3），因为 Cast 设备仅支持一个媒体元素，并且无法在现有内容项仍在播放时用于预加载。

自定义消息

消息交换是网络接收器应用的关键互动方法。

发送者使用适用于其运行的平台（Android、iOS、Web）的发送者 API 向网络接收器发送消息。传递给事件监听器的事件对象（即消息的清单）包含一个数据元素 (event.data)，其中的数据会采用特定事件类型的属性。

Web 接收器应用可以选择监听指定命名空间上的消息。这样一来，Web 接收器应用即视为支持该命名空间协议。然后，希望在该命名空间上进行通信的所有连接的发送方就可以使用适当的协议。

所有命名空间都由字符串定义，必须以“urn:x-cast:”开头，后跟任意字符串。例如，“urn:x-cast:com.example.cast.mynamespace”。

以下代码段可供 Web 接收器监听来自已连接的发送者的自定义消息：

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

const CUSTOM_CHANNEL = 'urn:x-cast:com.example.cast.mynamespace';
context.addCustomMessageListener(CUSTOM_CHANNEL, function(customEvent) {
  // handle customEvent.
});

context.start();

同样，Web 接收器应用可以通过向已连接的发送器发送消息，让发送器随时了解 Web 接收器的状态。Web 接收器应用可以使用 CastReceiverContext 上的 sendCustomMessage(namespace, senderId, message) 发送消息。Web 接收器可以向单个发送者发送消息，无论是响应收到的消息，还是在应用状态发生变化时。除了点对点消息传递（上限为 64kb），网络接收器也可以向所有连接的发送器广播消息。

适用于音频设备的 Cast

如需获得关于纯音频播放的支持，请参阅适用于音频设备的 Google Cast 指南。

Android TV

本部分介绍了 Google Web 接收器如何使用您的输入作为播放，以及 Android TV 兼容性。

将您的应用与遥控器集成

如媒体播放消息中所述，在 Android TV 设备上运行的 Google 网络接收器会将设备控制输入（即手持遥控器）的输入转换为为 urn:x-cast:com.google.cast.media 命名空间定义的媒体播放消息。您的应用必须支持这些消息来控制应用媒体播放，以便从 Android TV 的控制输入实现基本的播放控制。

Android TV 兼容性准则

为确保您的应用与 Android TV 兼容，下面列出了一些建议和避免的常见误区：

  • 请注意，用户代理字符串中同时包含“Android”和“CrKey”；某些网站可能会由于检测到“Android”标签而重定向到移动版网站。请勿假设用户代理字符串中的“Android”始终表示移动设备用户。
  • Android 的媒体堆栈可能会使用透明的 GZIP 来提取数据。确保您的媒体数据可以响应 Accept-Encoding: gzip。
  • Android TV HTML5 媒体事件的触发时间可能与 Chromecast 不同，这可能揭示了 Chromecast 上隐藏的问题。
  • 更新媒体时，请使用由 <audio>/<video> 元素触发的媒体相关事件，如 timeupdate、pause 和 waiting。避免使用 progress、suspend 和 stalled 等网络相关事件，因为这些事件往往取决于平台。如需详细了解如何在接收器中处理媒体事件，请参阅媒体事件。
  • 配置接收器网站的 HTTPS 证书时，请务必包含中间 CA 证书。如需验证，请参阅 Qualsys SSL 测试页面：如果您网站的可信认证路径包含标记为“额外下载”的 CA 证书，则该证书可能无法在 Android 平台上加载。
  • 虽然 Chromecast 会在 720p 图形平面上显示接收器页面，但包括 Android TV 在内的其他 Cast 平台可能会以最高 1080p 的分辨率显示该页面。确保接收器页面在不同分辨率下正常缩放。
上一页
自定义网络接收器
下一页
Shaka Player 迁移中的 HLS