将 Cast SDK 集成到您的 Web 发送者应用中

使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

本开发者指南将介绍如何使用 Cast SDK 为 Web 发送者应用添加 Google Cast 支持。

术语

移动设备或浏览器是控制播放的发送器；Google Cast 设备是接收内容，会在屏幕上显示内容以进行播放。

Web Sender SDK 由两部分组成：Framework API (cast.framework) 和 Base API (chrome.cast)。通常，您可以对更简单的较高级别的 Framework API 进行调用，然后由较低级别的 Base API 处理这些 API。

“发送者框架”是指 Framework API、模块和相关资源，可提供封装容器来封装低级功能。发送者应用或 Google Cast Chrome 应用是指在发送者设备的 Chrome 浏览器内运行的 Web (HTML/JavaScript) 应用。Web 接收器应用是指在 Chromecast 或 Google Cast 设备上运行的 HTML/JavaScript 应用。

发送者框架使用异步回调设计来向发送者应用通知事件，并在 Cast 应用生命周期的各种状态之间过渡。

加载库

为了让您的应用实现 Google Cast 的功能，它需要知道 Google Cast Web Sender SDK 的位置，如下所示。添加 loadCastFramework 网址查询参数也要加载 Web Sender Framework API。应用的所有页面都必须引用该库，具体代码如下所示：

<script src="https://www.gstatic.com/cv/js/sender/v1/cast_sender.js?loadCastFramework=1"></script>

框架

Web Sender SDK 使用 cast.framework.* 命名空间。命名空间表示以下内容：

  • 对 API 调用操作的方法或函数
  • API 中监听器函数的事件监听器

框架由以下主要组件组成：

  • CastContext 是一个单例对象，它可提供有关当前 Cast 状态的信息，并针对 Cast 状态和 Cast 会话状态变化触发事件。
  • CastSession 对象会管理会话 - 它提供状态信息和触发事件，例如对设备音量的更改、静音状态和应用元数据。
  • “投放”按钮元素是一个简单的 HTML 自定义元素，用于扩展 HTML 按钮。如果提供的“投放”按钮不够用，您可以使用“投放”状态来实现“投放”按钮。
  • RemotePlayerController 可提供数据绑定，以简化远程播放器的实现。

如需查看命名空间的完整说明，请参阅 Google Cast Web Sender API 参考文档。

投放按钮

应用中的“投放”按钮组件完全由框架处理。这包括可见性管理以及点击事件处理。

<google-cast-launcher></google-cast-launcher>

或者，您也可以通过编程方式创建该按钮：

document.createElement("google-cast-launcher");

您可以根据需要对元素应用任何其他样式，例如大小或定位。使用 --connected-color 属性为已连接的网络接收器状态选择颜色，并使用 --disconnected-color 表示断开连接的状态。

初始化

加载框架 API 后，应用将调用处理程序 window.__onGCastApiAvailable。在加载发送者库之前，您应确保应用在 window 上设置此处理程序。

在此处理程序中，您可以通过调用 CastContext 的 setOptions(options) 方法初始化 Cast 互动。

例如：

<script>
window['__onGCastApiAvailable'] = function(isAvailable) {
  if (isAvailable) {
    initializeCastApi();
  }
};
</script>

然后，您可以按如下方式初始化该 API：

initializeCastApi = function() {
  cast.framework.CastContext.getInstance().setOptions({
    receiverApplicationId: applicationId,
    autoJoinPolicy: chrome.cast.AutoJoinPolicy.ORIGIN_SCOPED
  });
};

首先，应用检索框架提供的 CastContext 对象的单例实例。然后，它使用 setOptions(options)，通过 CastOptions 对象设置 applicationID。

如果您使用的是默认媒体接收器（不需要注册），请使用 Web Sender SDK 预定义的常量（如下所示），而不是 applicationID：

cast.framework.CastContext.getInstance().setOptions({
  receiverApplicationId: chrome.cast.media.DEFAULT_MEDIA_RECEIVER_APP_ID
});

媒体控件

CastContext 初始化后，应用可以随时使用 getCurrentSession() 检索当前的 CastSession。

var castSession = cast.framework.CastContext.getInstance().getCurrentSession();

CastSession 可用于使用 loadMedia(loadRequest) 将媒体加载到连接的投放设备。首先，使用 contentId 和 contentType 以及与内容相关的任何其他信息创建 MediaInfo。然后，根据该响应创建 LoadRequest，为请求设置所有相关信息。最后，在 CastSession 上调用 loadMedia(loadRequest)。

var mediaInfo = new chrome.cast.media.MediaInfo(currentMediaURL, contentType);
var request = new chrome.cast.media.LoadRequest(mediaInfo);
castSession.loadMedia(request).then(
  function() { console.log('Load succeed'); },
  function(errorCode) { console.log('Error code: ' + errorCode); });

loadMedia 方法将返回一个 promise，它可用于执行任何必要的操作，以确保成功。如果 Promise 被拒绝，则函数参数将为 chrome.cast.ErrorCode。

您可以在 RemotePlayer 中访问玩家状态变量。与 RemotePlayer 的所有互动（包括媒体事件回调和命令）均使用 RemotePlayerController 进行处理。

var player = new cast.framework.RemotePlayer();
var playerController = new cast.framework.RemotePlayerController(player);

RemotePlayerController 使应用能够完全控制已加载媒体的播放、暂停、停止和搜索。

  • 播放/暂停：playerController.playOrPause();
  • 停止：playerController.stop();
  • 查看：playerController.seek();

RemotePlayer 和 RemotePlayerController 可与数据绑定框架（如 Polymer 或 Angular）搭配使用，以实现远程播放器。

以下是 Angular 的代码段：

<button id="playPauseButton" class="playerButton"
  ng-disabled="!player.canPause"
  ng-click="controller.playOrPause()">
    {{player.isPaused ? 'Play' : 'Pause'}}
</button>
<script>
var player = new cast.framework.RemotePlayer();
var controller = new cast.framework.RemotePlayerController(player);
// Listen to any player update, and trigger angular data binding
update.controller.addEventListener(
  cast.framework.RemotePlayerEventType.ANY_CHANGE,
  function(event) {
    if (!$scope.$$phase) $scope.$apply();
  });
</script>

媒体状态

在媒体播放期间，系统会通过在 RemotePlayerController 对象上为各种 cast.framework.RemotePlayerEventType 事件设置监听器来捕获各种事件。

如需获取媒体状态信息，请使用 cast.framework.RemotePlayerEventType.MEDIA_INFO_CHANGED 事件，该事件会在播放更改以及 CastSession.getMediaSession().media 更改时触发。

playerController.addEventListener(
  cast.framework.RemotePlayerEventType.MEDIA_INFO_CHANGED, function() {
    // Use the current session to get an up to date media status.
    let session = cast.framework.CastContext.getInstance().getCurrentSession();

    if (!session) {
        return;
    }

    // Contains information about the playing media including currentTime.
    let mediaStatus = session.getMediaSession();
    if (!mediaStatus) {
        return;
    }

    // mediaStatus also contains the mediaInfo containing metadata and other
    // information about the in progress content.
    let mediaInfo = mediaStatus.media;
  });

当发生暂停、播放、恢复或跳转等事件时，应用需要对这些事件执行操作，并在 Cast 设备上的 Web 接收器应用与其之间同步。如需了解详情，请参阅状态更新。

会话管理的运作方式

Cast SDK 引入了 Cast 会话的概念，其定义结合了连接到设备、启动（或加入）Web 接收器应用、连接到该应用以及初始化媒体控制通道的步骤。如需详细了解 Cast 会话和 Web 接收器生命周期，请参阅网络接收器应用生命周期指南。

会话由 CastContext 类管理，您的应用可通过 cast.framework.CastContext.getInstance() 检索该类。各个会话由 Session 类的子类表示。例如，CastSession 表示与投放设备的会话。您的应用可以通过 CastContext.getCurrentSession() 访问当前活跃的 Cast 会话。

如需监控会话状态，请为 CastContextEventType.SESSION_STATE_CHANGED 事件类型的 CastContext 添加监听器。

var context = cast.framework.CastContext.getInstance();
context.addEventListener(
  cast.framework.CastContextEventType.SESSION_STATE_CHANGED,
  function(event) {
    switch (event.sessionState) {
      case cast.framework.SessionState.SESSION_STARTED:
      case cast.framework.SessionState.SESSION_RESUMED:
        break;
      case cast.framework.SessionState.SESSION_ENDED:
        console.log('CastContext: CastSession disconnected');
        // Update locally as necessary
        break;
    }
  })

对于断开连接（例如当用户点击“投射”对话框中的“停止投射”按钮时），您可以在监听器中为 RemotePlayerEventType.IS_CONNECTED_CHANGED 事件类型添加监听器。在监听器中，检查 RemotePlayer 是否已断开连接。如果是这样，请根据需要更新本地播放器的状态。例如：

playerController.addEventListener(
  cast.framework.RemotePlayerEventType.IS_CONNECTED_CHANGED, function() {
    if (!player.isConnected) {
      console.log('RemotePlayerController: Player disconnected');
      // Update local player to disconnected state
    }
  });

虽然用户可以通过框架“投射”按钮直接控制 Cast 终止，但发送者本身可以使用当前的 CastSession 对象停止投射。

function stopCasting() {
  var castSession = cast.framework.CastContext.getInstance().getCurrentSession();
  // End the session and pass 'true' to indicate
  // that Web Receiver app should be stopped.
  castSession.endSession(true);
}

流式传输

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

如需在数据流传输期间获取新的目标设备，请在调用 cast.framework.SessionState.SESSION_RESUMED 事件时调用 CastSession#getCastDevice()。

如需了解详情，请参阅在 Web 接收器上传输流。

上一页
设置
下一页
添加高级功能