在 Android TV 上集成“继续观看”功能

book_path: /distribute/other-docs/_book.yaml project_path: /distribute/other-docs/_project.yaml

本指南介绍了如何使用 Engage SDK 将“继续观看”功能集成到 Android TV 应用中。

准备工作

重要提示： 表达对开发 Video Discovery API 的兴趣。

完成“入门指南”中的准备工作说明。

集成

注意： “继续观看”API 的运作方式与“接下来观看”API 不同。它不会逐个添加或移除项目，而是在每次更新时替换整个“继续观看”项目列表。这意味着，每次更新时，您都需要发送要显示的所有项。您应在“继续观看”行中显示尽可能多的实体，但不得超过 10 个。此外，新 API 将发布列表和发布商品的步骤合并为一个，从而简化了流程。请注意，Google TV 可能会不显示您发送的所有项目，因为它会合并来自不同应用的清单。

创建实体

SDK 定义了不同的实体来代表每种内容类型。延续集群支持以下实体：

1. MovieEntity
2. TvEpisodeEntity
3. LiveStreamingVideoEntity
4. VideoClipEntity

注意： 继续观看功能不支持 TvShowEntity 和 TvSeasonEntity 延续集群。当用户看完一集电视剧后，应发布下一个 TvEpisodeEntity，以便用户继续观看下一集。

为这些实体指定特定于平台的 URI 和海报图片。

此外，如果尚未为每个平台（例如 Android TV、Android 或 iOS）创建播放 URI，请立即创建。因此，当用户在每个平台上继续观看时，应用会使用目标播放 URI 来播放视频内容。

注意： 在极少数情况下，所有平台的播放 URI 都相同，但您仍必须针对要继续观看的每个平台重复执行此操作。

// Required. Set this when you want continue watching entities to show up on
// Google TV
val playbackUriTv = PlatformSpecificUri.Builder()
    .setPlatformType(PlatformType.TYPE_ANDROID_TV)
    .setActionUri(Uri.parse("https://www.example.com/entity_uri_for_tv"))
    .build()

// Required. Set this when you want continue watching entities to show up on
// Google TV Android app, Entertainment Space, Playstore Widget
val playbackUriAndroid = PlatformSpecificUri.Builder()
    .setPlatformType(PlatformType.TYPE_ANDROID_MOBILE)
    .setActionUri(Uri.parse("https://www.example.com/entity_uri_for_android"))
    .build()

// Optional. Set this when you want continue watching entities to show up on
// Google TV iOS app
val playbackUriIos = PlatformSpecificUri.Builder()
    .setPlatformType(PlatformType.TYPE_IOS)
    .setActionUri(Uri.parse("https://www.example.com/entity_uri_for_ios"))
    .build()

val platformSpecificPlaybackUris =
    Arrays.asList(playbackUriTv, playbackUriAndroid, playbackUriIos)

海报图片需要 URI 和像素尺寸（高度和宽度）。通过提供多张海报图片来面向不同的设备规格，但请验证所有图片是否都保持 16:9 的宽高比和至少 200 像素的高度，以便正确显示“继续观看”实体，尤其是在 Google 的娱乐空间内。高度小于 200 像素的图片可能不会显示。

val images = Arrays.asList(
    Image.Builder()
        .setImageUri(Uri.parse("http://www.example.com/entity_image1.png"))
        .setImageHeightInPixel(300)
        .setImageWidthInPixel(169)
        .build(),
    Image.Builder()
        .setImageUri(Uri.parse("http://www.example.com/entity_image2.png"))
        .setImageHeightInPixel(640)
        .setImageWidthInPixel(360)
        .build()
    // Consider adding other images for different form factors
)

MovieEntity

此示例展示了如何创建包含所有必需字段的 MovieEntity：

val movieEntity = MovieEntity.Builder()
   .setWatchNextType(WatchNextType.TYPE_CONTINUE)
   .setName("Movie name")
   .addPlatformSpecificPlaybackUri(platformSpecificPlaybackUris)
   .addPosterImages(images)
   // Timestamp in millis for sample last engagement time 12/1/2023 00:00:00
   .setLastEngagementTimeMillis(1701388800000)
   // Suppose the duration is 2 hours, it is 72000000 in milliseconds
   .setDurationMills(72000000)
   // Suppose last playback offset is 1 hour, 36000000 in milliseconds
   .setLastPlayBackPositionTimeMillis(36000000)
   .build()

提供类型和内容分级等详细信息，可让 Google TV 以更动态的方式展示您的内容，并将其与合适的观看者联系起来。

val genres = Arrays.asList("Action", "Science fiction")
val rating1 = RatingSystem.Builder().setAgencyName("MPAA").setRating("PG-13").build()
val contentRatings = Arrays.asList(rating1)
val movieEntity = MovieEntity.Builder()
    ...
    .addGenres(genres)
    .addContentRatings(contentRatings)
    .build()

除非您指定较短的过期时间，否则实体会自动保持可用状态 60 天。只有在需要在此默认期限之前移除实体时，才需要设置自定义过期时间。

// Set the expiration time to be now plus 30 days in milliseconds
val expirationTime = DisplayTimeWindow.Builder()
    .setEndTimestampMillis(now().toMillis()[phone]).build()
val movieEntity = MovieEntity.Builder()
    ...
    .addAvailabilityTimeWindow(expirationTime)
    .build()

TvEpisodeEntity

此示例展示了如何创建包含所有必需字段的 TvEpisodeEntity：

val tvEpisodeEntity = TvEpisodeEntity.Builder()
    .setWatchNextType(WatchNextType.TYPE_CONTINUE)
    .setName("Episode name")
    .addPlatformSpecificPlaybackUri(platformSpecificPlaybackUris)
    .addPosterImages(images)
    // Timestamp in millis for sample last engagement time 12/1/2023 00:00:00
    .setLastEngagementTimeMillis(1701388800000)
    .setDurationMills(72000000) // 2 hours in milliseconds
    // 45 minutes and 15 seconds in milliseconds is 2715000
    .setLastPlayBackPositionTimeMillis(2715000)
    .setEpisodeNumber("2")
    .setSeasonNumber("1")
    .setShowTitle("Title of the show")
    .build()

剧集编号字符串（例如 "2"）和季编号字符串（例如 "1"）在显示在“继续观看”卡片上之前，会扩展为适当的形式。请注意，它们应该是数字字符串，不要使用“e2”“第 2 集”“s1”或“第 1 季”。

如果某个电视节目只有一季，请将季数设置为 1。

为了最大限度地提高观看者在 Google TV 上找到您的内容的机会，请考虑提供其他数据，例如流派、内容分级和播放时间窗口，因为这些详细信息可以增强显示效果和过滤选项。

val genres = Arrays.asList("Action", "Science fiction")
val rating1 = RatingSystem.Builder().setAgencyName("MPAA").setRating("PG-13").build()
val contentRatings = Arrays.asList(rating1)
val tvEpisodeEntity = TvEpisodeEntity.Builder()
    ...
    .addGenres(genres)
    .addContentRatings(contentRatings)
    .setSeasonTitle("Season Title")
    .setShowTitle("Show Title")
    .build()

VideoClipEntity

以下示例展示了如何创建包含所有必需字段的 VideoClipEntity。

VideoClipEntity 表示用户生成的剪辑，例如 YouTube 视频。

val videoClipEntity = VideoClipEntity.Builder()
    .setPlaybackUri(Uri.parse("https://www.example.com/uri_for_current_platform"))
    .setWatchNextType(WatchNextType.TYPE_CONTINUE)
    .setName("Video clip name")
    .addPlatformSpecificPlaybackUri(platformSpecificPlaybackUris)
    .addPosterImages(images)
    // Timestamp in millis for sample last engagement time 12/1/2023 00:00:00
    .setLastEngagementTimeMillis(1701388800000)
    .setDurationMills(600000) //10 minutes in milliseconds
    .setLastPlayBackPositionTimeMillis(300000) //5 minutes in milliseconds
    .addContentRating(contentRating)
    .build()

您可以选择性地设置创建者、创建者图片、创建时间（以毫秒为单位）或有效时间窗口。

LiveStreamingVideoEntity

以下示例展示了如何创建包含所有必需字段的 LiveStreamingVideoEntity。

val liveStreamingVideoEntity = LiveStreamingVideoEntity.Builder()
    .setPlaybackUri(Uri.parse("https://www.example.com/uri_for_current_platform"))
    .setWatchNextType(WatchNextType.TYPE_CONTINUE)
    .setName("Live streaming name")
    .addPlatformSpecificPlaybackUri(platformSpecificPlaybackUris)
    .addPosterImages(images)
    // Timestamp in millis for sample last engagement time 12/1/2023 00:00:00
    .setLastEngagementTimeMillis(1701388800000)
    .setDurationMills(72000000) //2 hours in milliseconds
    .setLastPlayBackPositionTimeMillis(36000000) //1 hour in milliseconds
    .addContentRating(contentRating)
    .build()

您可以选择性地为直播实体设置开始时间、广播者、广播者图标或播放时间窗口。

如需详细了解属性和要求，请参阅 API 参考文档。

提供接续集群数据

AppEngagePublishClient 负责发布接续集群。 您可以使用 publishContinuationCluste 方法发布 ContinuationCluster 对象。

请务必按照入门指南中的说明初始化客户端并检查服务可用性。

client.publishContinuationCluster(
    PublishContinuationClusterRequest
        .Builder()
        .setContinuationCluster(
            ContinuationCluster.Builder()
                .setAccountProfile(accountProfile)
                .addEntity(movieEntity1)
                .addEntity(movieEntity2)
                .addEntity(tvEpisodeEntity1)
                .addEntity(tvEpisodeEntity2)
                .setSyncAcrossDevices(true)
                .build()
        )
        .build()
)

当服务收到请求时，系统会在一项事务中执行以下操作：

• 系统会移除开发者合作伙伴的现有 ContinuationCluster 数据。
• 系统会解析请求中的数据，并将其存储在经过更新的 ContinuationCluster 中。

如果发生错误，系统将拒绝整个请求，并保留现有状态。

发布 API 是更新/插入 API；它会替换现有内容。如果您需要更新延续集群中的特定实体，则需要重新发布所有实体。

继续观看集群数据应仅针对成人账号提供。仅当账号个人资料属于成人时发布。

警告： 请勿随后调用删除和发布 API 来替换内容，因为发布 API 本身会执行此操作。

跨设备同步

SyncAcrossDevices 标志用于控制用户的 ContinuationCluster 数据是否在电视、手机、平板电脑等设备之间同步。默认情况下，跨设备同步处于停用状态。

值：

• true：续播集群数据会在用户的所有设备之间共享，以实现无缝观看体验。我们强烈建议您选择此选项，以获得最佳跨设备体验。
• false：延续集群数据仅限于当前设备。

征求用户意见

媒体应用必须提供清晰的设置来启用或停用跨设备同步。向用户说明好处，然后存储用户偏好设置一次，并在 publishContinuationCluster 中相应地应用该设置。

// Example to allow cross device syncing.
client.publishContinuationCluster(
    PublishContinuationClusterRequest
        .Builder()
        .setContinuationCluster(
            ContinuationCluster.Builder()
                .setAccountProfile(accountProfile)
                .setSyncAcrossDevices(true)
                .build()
        )
        .build()
)

如需充分利用我们的跨设备功能，请验证应用是否已征得用户同意，并将 SyncAcrossDevices 启用为 true。这样一来，内容便可在设备之间无缝同步，从而带来更出色的用户体验并提高用户互动度。例如，一位合作伙伴在实施此功能后，“继续观看”点击次数增加了 40%，因为其内容可在多种设备上显示。

删除视频发现数据

如需在标准 60 天保留期限之前从 Google TV 服务器手动删除用户的数据，请使用 deleteClusters 方法。收到请求后，服务将删除相应账号个人资料或整个账号的所有现有视频发现数据。

重要提示： 即使在删除请求中，也务必要将 syncAcrossDevices 标志设置为 true，以便从服务器中删除数据（即使删除原因是 USER_LOGOUT）。

DeleteReason 枚举定义了数据删除的原因。以下代码会在用户退出登录时移除“继续观看”数据。

// If the user logs out from your media app, you must make the following call
// to remove continue watching data from the current google TV device,
// otherwise, the continue watching data will persist on the current
// google TV device until 60 days later.
client.deleteClusters(
    DeleteClustersRequest.Builder()
        .setAccountProfile(AccountProfile())
        .setReason(DeleteReason.DELETE_REASON_USER_LOG_OUT)
        .setSyncAcrossDevices(true)
        .build()
)

警告： 请勿随后调用删除和发布 API 来替换内容，因为发布 API 本身会执行此操作。

测试

使用验证应用验证 Engage SDK 集成是否正常运行。

注意： 在 logcat 中检查您的应用是否正确调用了 isServiceAvailable 和 publishClusters API。在提交 APK 之前，请检查您是否能够在开发期间在 logcat 中看到 publishClusters 被调用的日志，以验证您是否在正确的事件中调用了 API。

调用发布 API 后，请检查验证应用，确认您的数据是否正在正确发布。您的延续集群应在应用的界面中显示为单独的一行。

• 在应用中测试以下操作：
  • 登录。
  • 在个人资料之间切换（如适用）。
  • 开始播放视频，然后暂停视频，或返回首页。
  • 在视频播放期间关闭应用。
  • 从“继续观看”行中移除内容（如果支持）。
• 每次操作后，请确认您的应用已调用 publishContinuationClusters API，并且数据已在验证应用中正确显示。

• 对于正确实现的相关实体，验证应用会显示一个绿色的“一切正常”对勾标记。

  

  图 1. 验证应用成功

• 验证应用会标记出所有存在问题的实体。

  

  图 2. 验证应用错误

• 如需排查存在错误的实体，请使用电视遥控器选择并点击验证应用中的实体。系统会显示具体问题，并以红色突出显示以供您查看（请参阅下方示例）。

  

  图 3. 验证应用错误详情