使用 REST API 集成“继续观看”功能

Engage SDK 提供 REST API，可在 iOS 和 Roku TV 等非 Android 平台上提供一致的“继续观看”体验。借助此 API，开发者可以从非 Android 平台为选择启用的用户更新“继续观看”状态。

前提条件

您必须先完成基于设备端 Engage SDK 的集成。此关键步骤可在 Google 的用户 ID 与应用的 AccountProfile 之间建立必要的关联。
API 访问和身份验证：如需在 Google Cloud 项目中查看和启用该 API，您必须完成许可名单流程。所有 API 请求都需要进行身份验证。

获取访问权限

如需在 Google Cloud 控制台中查看和启用该 API，您的账号需要注册。

Google Workspace 客户 ID 应该可用。如果不可用，您可能需要设置 Google Workspace 以及您想要用于调用 API 的任何 Google 账号。
使用与 Google Workspace 关联的电子邮件地址通过 Google Cloud 控制台设置账号。
创建新项目。
创建用于 API 身份验证的服务账号。创建服务账号后，您将获得以下两项内容：
- 服务账号 ID。
- 包含您的服务账号密钥的 JSON 文件。请确保此文件的安全。您稍后需要使用此密钥对客户端进行身份验证，以便访问 API。
Workspace 和关联的 Google 账号现在可以使用 REST API。更改传播完毕后，您会收到通知，告知您服务账号是否可以调用该 API。
请按照以下步骤准备进行委托的 API 调用。

发布接续集群

如需发布视频发现数据，请使用以下语法向 publishContinuationCluster API 发出 POST 请求。

https://tvvideodiscovery.googleapis.com/v1/packages/{package_name}/accounts/{account_id}/profiles/{profile_id}/publishContinuationCluster

其中：

package_name：媒体提供方软件包名称
accountId：用户账号在您系统中的唯一 ID。它必须与设备端路径中使用的 accountId 相匹配。
profileId：用户在您系统中的账号内的个人资料的唯一 ID。必须与设备端路径中使用的 profileId 一致。

不含个人资料的账号的网址为：

https://tvvideodiscovery.googleapis.com/v1/packages/{package_name}/accounts/{account_id}/publishContinuationCluster

请求的载荷在 entities 字段中表示。entities 表示内容实体的列表，可以是 MovieEntity 或 TVEpisodeEntity。此字段是必填字段。

请求正文

字段	类型	必需	说明
实体	MediaEntity 对象列表	是	内容实体列表，最多包含 5 个实体。系统只会保留前 5 个，其余的都会被舍弃。允许使用空列表来表示用户已观看完所有实体。

字段 entities 包含各个 movieEntity 和 tvEpisodeEntity。

字段	类型	必需	说明
movieEntity	MovieEntity	是	表示 ContinuationCluster 中的电影的对象。
tvEpisodeEntity	TvEpisodeEntity	是	表示 ContinuationCluster 中的电视节目剧集的对象。

实体数组中的每个对象都必须是可用的 MediaEntity 类型之一，即 MovieEntity 和 TvEpisodeEntity，以及通用字段和特定于类型的字段。

以下代码段展示了 publishContinuationCluster API 的请求正文载荷。

{
  "entities": [
    {
      "movieEntity": {
        "watch_next_type": "WATCH_NEXT_TYPE_CONTINUE",
        "name": "Movie1",
        "platform_specific_playback_uris": [
          "https://www.example.com/entity_uri_for_android",
          "https://www.example.com/entity_uri_for_iOS"
        ],
        "poster_images": [
          "http://www.example.com/movie1_img1.png",
          "http://www.example.com/movie1_imag2.png"
        ],
        "last_engagement_time_millis": 864600000,
        "duration_millis": 5400000,
        "last_play_back_position_time_millis": 3241111
      }
    },
    {
      "tvEpisodeEntity": {
        "watch_next_type": "WATCH_NEXT_TYPE_CONTINUE",
        "name": "TV SERIES EPISODE 1",
        "platform_specific_playback_uris": [
          "https://www.example.com/entity_uri_for_android",
          "https://www.example.com/entity_uri_for_iOS"
        ],
        "poster_images": [
          "http://www.example.com/episode1_img1.png",
          "http://www.example.com/episode1_imag2.png"
        ],
        "last_engagement_time_millis": 864600000,
        "duration_millis": 1800000,
        "last_play_back_position_time_millis": 2141231,
        "episode_display_number": "1",
        "season_number": "1",
        "show_title": "title"
      }
    }
  ]
}

删除视频发现数据

使用 clearClusters API 移除视频发现数据。

如需删除续播集群数据，请使用以下语法向 clearClusters API 发出 POST 请求。

https://tvvideodiscovery.googleapis.com/v1/packages/{package_name}/accounts/{account_id}/profiles/{profile_id}/clearClusters

其中：

package_name：媒体提供方软件包名称。
accountId：用户账号在您系统中的唯一 ID。它必须与设备端路径中使用的 accountId 相匹配。
profileId：用户在您系统中的账号内的个人资料的唯一 ID。必须与设备端路径中使用的 profileId 一致。

clearClusters API 的载荷仅包含一个字段，即 reason，其中包含一个 DeleteReason，用于指定移除数据的原因。

{
  "reason": "DELETE_REASON_LOSS_OF_CONSENT"
}

测试

成功发布数据后，请使用用户测试账号验证目标 Google 平台（例如 Google TV 以及 Android 和 iOS 版 Google TV 移动应用）的“继续观看”行中是否显示了预期内容。

在测试中，请允许合理的传播延迟时间（几分钟），并遵守观看要求，例如观看部分电影或看完一集电视剧。如需了解详情，请参阅面向应用开发者的“接下来观看”准则。