Engage SDK Watch：第三方技术集成说明

通过在用户所在的地方触达他们来提高应用参与度。集成 Engage SDK 可将“继续观看”内容和个性化推荐直接提供给多个设备界面上的用户，包括 Google TV、收藏夹、娱乐空间和 Play 商店。此集成会将 APK 的平均大小增加不到 50 KB（压缩后），并且大多数应用需要大约一周的开发人员时间。通过我们的商业网站了解更多信息。

本指南包含开发者合作伙伴使用 Engage SDK 集成其视频内容，以填充此新界面区域和现有 Google 界面的说明。

集成详情

术语

此集成包括以下三种集群类型：推荐、续播和精选。

推荐集群显示来自单个开发者合作伙伴的个性化内容观看建议。

您的推荐采用以下结构
- 推荐集群：包含来自同一开发者合作伙伴的一组推荐的 UI 视图。
  
  图 1. 娱乐空间 UI 显示来自单个合作伙伴的推荐集群。
- 实体：表示集群中单个项目的对象。实体可以是电影、电视节目、电视剧、直播视频等。有关支持的实体类型列表，请参阅提供实体数据部分。
  
  图 2. 娱乐空间 UI 显示单个合作伙伴的推荐集群中的单个实体。
续播集群在一个 UI 分组中显示来自多个开发者合作伙伴的未完成视频和相关新发布剧集。每个开发者合作伙伴最多可以在续播集群中广播 10 个实体。研究表明，个性化推荐与个性化续播内容相结合，可创造最佳的用户参与度。

图 3. 娱乐空间 UI 显示一个续播集群，其中包含来自多个合作伙伴的未完成推荐（目前只有一个推荐可见）。
精选集群在一个 UI 分组中展示来自多个开发者合作伙伴的精选实体。将有一个单一的精选集群，它位于 UI 顶部附近，优先级高于所有推荐集群。每个开发者合作伙伴最多可以在精选集群中广播 10 个实体。

图 4. 娱乐空间 UI 显示一个精选集群，其中包含来自多个合作伙伴的推荐（目前只有一个推荐可见）。

准备工作

最低 API 级别：19

将 com.google.android.engage:engage-core 库添加到您的应用

dependencies {
    // Make sure you also include that repository in your project's build.gradle file.
    implementation 'com.google.android.engage:engage-core:1.5.2'
}

有关更多信息，请参阅 Android 11 中的软件包可见性。

摘要

该设计基于绑定服务的实现。

客户端可以发布的数据受到不同集群类型的以下限制

集群类型	集群限制	集群中的最大实体限制
推荐集群	最多 7 个	最多 50 个
续播集群	最多 1 个	最多 20 个
精选集群	最多 1 个	最多 20 个

第 0 步：从现有 Media Home SDK 集成迁移

映射现有集成中的数据模型

如果您正在从现有 Media Home 集成迁移，下表概述了如何将现有 SDK 中的数据模型映射到新的 Engage SDK

MediaHomeVideoContract 集成等效项	Engage SDK 集成等效项
`com.google.android.mediahome.video.PreviewChannel`	`com.google.android.engage.common.datamodel.RecommendationCluster`
`com.google.android.mediahome.video.PreviewChannel.Builder`	`com.google.android.engage.common.datamodel.RecommendationCluster.Builder`
`com.google.android.mediahome.video.PreviewChannelHelper`	`com.google.android.engage.video.service.AppEngageVideoClient`
`com.google.android.mediahome.video.PreviewProgram`	分为独立的类：`EventVideo`、`LiveStreamingVideo`、`Movie`、`TvEpisode`、`TvSeason`、`TvShow`、`VideoClipEntity`
`com.google.android.mediahome.video.PreviewProgram.Builder`	分为独立类中的构建器：`EventVideo`、`LiveStreamingVideo`、`Movie`、`TvEpisode`、`TvSeason`、`TvShow`、`VideoClipEntity`
`com.google.android.mediahome.video.VideoContract`	不再需要。
`com.google.android.mediahome.video.WatchNextProgram`	分为独立类中的属性：`EventVideoEntity`、`LiveStreamingVideoEntity`、`MovieEntity`、`TvEpisodeEntity`、`TvSeasonEntity`、`TvShowEntity`、`VideoClipEntity`
`com.google.android.mediahome.video.WatchNextProgram.Builder`	分为独立类中的属性：`EventVideoEntity`、`LiveStreamingVideoEntity`、`MovieEntity`、`TvEpisodeEntity`、`TvSeasonEntity`、`TvShowEntity`、`VideoClipEntity`

在 Media Home SDK 和 Engage SDK 中发布集群

通过 Media Home SDK，集群和实体通过单独的 API 发布

// 1. Fetch existing channels
List<PreviewChannel> channels = PreviewChannelHelper.getAllChannels();

// 2. If there are no channels, publish new channels
long channelId = PreviewChannelHelper.publishChannel(builder.build());

// 3. If there are existing channels, decide whether to update channel contents
PreviewChannelHelper.updatePreviewChannel(channelId, builder.build());

// 4. Delete all programs in the channel
PreviewChannelHelper.deleteAllPreviewProgramsByChannelId(channelId);

// 5. publish new programs in the channel
PreviewChannelHelper.publishPreviewProgram(builder.build());

通过 Engage SDK，集群和实体发布合并到单个 API 调用中。所有属于集群的实体都与该集群一起发布

Kotlin

RecommendationCluster.Builder()
            .addEntity(MOVIE_ENTITY)
            .addEntity(MOVIE_ENTITY)
            .addEntity(MOVIE_ENTITY)
            .setTitle("Top Picks For You")
            .build()

Java

new RecommendationCluster.Builder()
                        .addEntity(MOVIE_ENTITY)
                        .addEntity(MOVIE_ENTITY)
                        .addEntity(MOVIE_ENTITY)
                        .setTitle("Top Picks For You")
                        .build();

第 1 步：提供实体数据

SDK 定义了不同的实体来表示每种项目类型。我们支持以下用于 Watch 类别的实体

MovieEntity
TvShowEntity
TvSeasonEntity
TvEpisodeEntity
LiveStreamingVideoEntity
VideoClipEntity

下表概述了每种类型的属性和要求。

`MovieEntity`

属性	要求	备注
名称	必填
海报图片	必填	至少需要一张图片，并且必须提供纵横比。（推荐横向图片，但建议为不同场景同时提供纵向和横向图片。）有关指导，请参阅图片规格。
播放 URI	必填	用于在提供商应用中开始播放电影的深层链接。注意：您可以使用深层链接进行归因。请参阅此常见问题解答
信息页 URI	可选	用于在提供商应用中显示电影详细信息的深层链接。注意：您可以使用深层链接进行归因。请参阅此常见问题解答
发布日期	可选	以纪元毫秒为单位。
可用性	必填	AVAILABLE：内容可供用户使用，无需任何进一步操作。 FREE_WITH_SUBSCRIPTION：用户购买订阅后即可使用内容。 PAID_CONTENT：内容需要用户购买或租赁。 PURCHASED：内容已被用户购买或租赁。
优惠价格	可选	自由文本
时长	必填	以毫秒为单位。
类型	必填	自由文本
内容评级	可选	自由文本，遵循行业标准。（示例）
下一个观看类型	条件必填	当项目位于续播集群中时必须提供，并且必须是以下四种类型之一 CONTINUE：用户已观看此内容超过 1 分钟。 NEW：用户已观看所有可用的剧集，但新剧集已可用，并且正好有一集未观看。这适用于电视节目、系列中的录制足球比赛等。 NEXT：用户已观看一部或多部完整剧集，但仍有多于一集或恰好一集剩余，其中最后一集不是“NEW”且发布于用户开始观看剧集内容之前。 WATCHLIST：用户明确选择将电影、活动或系列添加到观看列表，以手动管理他们想要接下来观看的内容。
上次互动时间	条件必填	当项目位于续播集群中时必须提供。以纪元毫秒为单位。
上次播放位置时间	条件必填	当项目位于续播集群且 WatchNextType 为 CONTINUE 时必须提供。以纪元毫秒为单位。

`TvShowEntity`

属性	要求	备注
名称	必填
海报图片	必填	至少需要一张图片，并且必须提供纵横比。（推荐横向图片，但建议为不同场景同时提供纵向和横向图片。）有关指导，请参阅图片规格。
信息页 URI	必填	用于在提供商应用中显示电视节目详细信息的深层链接。注意：您可以使用深层链接进行归因。请参阅此常见问题解答
播放 URI	可选	用于在提供商应用中开始播放电视节目的深层链接。注意：您可以使用深层链接进行归因。请参阅此常见问题解答
首集播出日期	可选	以纪元毫秒为单位。
最新剧集播出日期	可选	以纪元毫秒为单位。
可用性	必填	AVAILABLE：内容可供用户使用，无需任何进一步操作。 FREE_WITH_SUBSCRIPTION：用户购买订阅后即可使用内容。 PAID_CONTENT：内容需要用户购买或租赁。 PURCHASED：内容已被用户购买或租赁。
优惠价格	可选	自由文本
季数	必填	正整数
类型	必填	自由文本
内容评级	可选	自由文本，遵循行业标准。（示例）
下一个观看类型	条件必填	当项目位于续播集群中时必须提供，并且必须是以下四种类型之一 CONTINUE：用户已观看此内容超过 1 分钟。 NEW：用户已观看所有可用的剧集，但新剧集已可用，并且正好有一集未观看。这适用于电视节目、系列中的录制足球比赛等。 NEXT：用户已观看一部或多部完整剧集，但仍有多于一集或恰好一集剩余，其中最后一集不是“NEW”且发布于用户开始观看剧集内容之前。 WATCHLIST：用户明确选择将电影、活动或系列添加到观看列表，以手动管理他们想要接下来观看的内容。
上次互动时间	条件必填	当项目位于续播集群中时必须提供。以纪元毫秒为单位。
上次播放位置时间	条件必填	当项目位于续播集群且 WatchNextType 为 CONTINUE 时必须提供。以纪元毫秒为单位。

`TvSeasonEntity`

属性	要求	备注
名称	必填
海报图片	必填	至少需要一张图片，并且必须提供纵横比。（推荐横向图片，但建议为不同场景同时提供纵向和横向图片。）有关指导，请参阅图片规格。
信息页 URI	必填	用于在提供商应用中显示电视节目季详细信息的深层链接。注意：您可以使用深层链接进行归因。请参阅此常见问题解答
播放 URI	可选	用于在提供商应用中开始播放电视节目季的深层链接。注意：您可以使用深层链接进行归因。请参阅此常见问题解答
显示季号	可选在 v1.3.1 中可用	字符串
首集播出日期	可选	以纪元毫秒为单位。
最新剧集播出日期	可选	以纪元毫秒为单位。
可用性	必填	AVAILABLE：内容可供用户使用，无需任何进一步操作。 FREE_WITH_SUBSCRIPTION：用户购买订阅后即可使用内容。 PAID_CONTENT：内容需要用户购买或租赁。 PURCHASED：内容已被用户购买或租赁。
优惠价格	可选	自由文本
剧集数	必填	正整数
类型	必填	自由文本
内容评级	可选	自由文本，遵循行业标准。（示例）
下一个观看类型	条件必填	当项目位于续播集群中时必须提供，并且必须是以下四种类型之一 CONTINUE：用户已观看此内容超过 1 分钟。 NEW：用户已观看所有可用的剧集，但新剧集已可用，并且正好有一集未观看。这适用于电视节目、系列中的录制足球比赛等。 NEXT：用户已观看一部或多部完整剧集，但仍有多于一集或恰好一集剩余，其中最后一集不是“NEW”且发布于用户开始观看剧集内容之前。 WATCHLIST：用户明确选择将电影、活动或系列添加到观看列表，以手动管理他们想要接下来观看的内容。
上次互动时间	条件必填	当项目位于续播集群中时必须提供。以纪元毫秒为单位。
上次播放位置时间	条件必填	当项目位于续播集群且 WatchNextType 为 CONTINUE 时必须提供。以纪元毫秒为单位。

`TvEpisodeEntity`

属性	要求	备注
名称	必填
海报图片	必填	至少需要一张图片，并且必须提供纵横比。（推荐横向图片，但建议为不同场景同时提供纵向和横向图片。）有关指导，请参阅图片规格。
播放 URI	必填	用于在提供商应用中开始播放剧集的深层链接。注意：您可以使用深层链接进行归因。请参阅此常见问题解答
信息页 URI	可选	用于在提供商应用中显示电视节目剧集详细信息的深层链接。注意：您可以使用深层链接进行归因。请参阅此常见问题解答
显示剧集号	可选在 v1.3.1 中可用	字符串
播出日期	必填	以纪元毫秒为单位。
可用性	必填	AVAILABLE：内容可供用户使用，无需任何进一步操作。 FREE_WITH_SUBSCRIPTION：用户购买订阅后即可使用内容。 PAID_CONTENT：内容需要用户购买或租赁。 PURCHASED：内容已被用户购买或租赁。
优惠价格	可选	自由文本
时长	必填	必须是正值（毫秒）。
类型	必填	自由文本
内容评级	可选	自由文本，遵循行业标准。（示例）
下一个观看类型	条件必填	当项目位于续播集群中时必须提供，并且必须是以下四种类型之一 CONTINUE：用户已观看此内容超过 1 分钟。 NEW：用户已观看所有可用的剧集，但新剧集已可用，并且正好有一集未观看。这适用于电视节目、系列中的录制足球比赛等。 NEXT：用户已观看一部或多部完整剧集，但仍有多于一集或恰好一集剩余，其中最后一集不是“NEW”且发布于用户开始观看剧集内容之前。 WATCHLIST：用户明确选择将电影、活动或系列添加到观看列表，以手动管理他们想要接下来观看的内容。
上次互动时间	条件必填	当项目位于续播集群中时必须提供。以纪元毫秒为单位。
上次播放位置时间	条件必填	当项目位于续播集群且 WatchNextType 为 CONTINUE 时必须提供。以纪元毫秒为单位。

`LiveStreamingVideoEntity`

属性	要求	备注
名称	必填
海报图片	必填	至少需要一张图片，并且必须提供纵横比。（推荐横向图片，但建议为不同场景同时提供纵向和横向图片。）有关指导，请参阅图片规格。
播放 URI	必填	用于在提供商应用中开始播放视频的深层链接。注意：您可以使用深层链接进行归因。请参阅此常见问题解答
广播公司	必填	自由文本
开始时间	可选	以纪元毫秒为单位。
结束时间	可选	以纪元毫秒为单位。
观看次数	可选	自由文本，必须本地化。
下一个观看类型	条件必填	当项目位于续播集群中时必须提供，并且必须是以下四种类型之一 CONTINUE：用户已观看此内容超过 1 分钟。 NEW：用户已观看所有可用的剧集，但新剧集已可用，并且正好有一集未观看。这适用于电视节目、系列中的录制足球比赛等。 NEXT：用户已观看一部或多部完整剧集，但仍有多于一集或恰好一集剩余，其中最后一集不是“NEW”且发布于用户开始观看剧集内容之前。 WATCHLIST：用户明确选择将电影、活动或系列添加到观看列表，以手动管理他们想要接下来观看的内容。
上次互动时间	条件必填	当项目位于续播集群中时必须提供。以纪元毫秒为单位。
上次播放位置时间	条件必填	当项目位于续播集群且 WatchNextType 为 CONTINUE 时必须提供。以纪元毫秒为单位。

`VideoClipEntity`

VideoClipEntity 对象表示来自社交媒体（如 TikTok 或 YouTube）的视频实体。

属性	要求	备注
名称	必填
海报图片	必填	至少需要一张图片，并且必须提供纵横比。（推荐横向图片，但建议为不同场景同时提供纵向和横向图片。）有关指导，请参阅图片规格。
播放 URI	必填	用于在提供商应用中开始播放视频的深层链接。注意：您可以使用深层链接进行归因。请参阅此常见问题解答
创建时间	必填	以纪元毫秒为单位。
时长	必填	必须是正值（毫秒）。
创建者	必填	自由文本
创建者图片	可选	创建者头像图片
观看次数	可选	自由文本，必须本地化。
下一个观看类型	条件必填	当项目位于续播集群中时必须提供，并且必须是以下四种类型之一 CONTINUE：用户已观看此内容超过 1 分钟。 NEW：用户已观看所有可用的剧集，但新剧集已可用，并且正好有一集未观看。这适用于电视节目、系列中的录制足球比赛等。 NEXT：用户已观看一部或多部完整剧集，但仍有多于一集或恰好一集剩余，其中最后一集不是“NEW”且发布于用户开始观看剧集内容之前。 WATCHLIST：用户明确选择将电影、活动或系列添加到观看列表，以手动管理他们想要接下来观看的内容。
上次互动时间	条件必填	当项目位于续播集群中时必须提供。以纪元毫秒为单位。
上次播放位置时间	条件必填	当项目位于续播集群且 WatchNextType 为 CONTINUE 时必须提供。以纪元毫秒为单位。

图片规格

以下部分列出了图片资产的所需规格

文件格式

PNG、JPG、静态 GIF、WebP

最大文件大小

5120 KB

其他建议

图像安全区域：将您的重要内容放置在图像的中心 80% 区域。

示例

Kotlin

var movie = MovieEntity.Builder()
    .setName("Avengers")
    .addPosterImage(Image.Builder()
                          .setImageUri(Uri.parse("http://www.x.com/image.png"))
                          .setImageHeightInPixel(960)
                          .setImageWidthInPixel(408)
                          .build())
    .setPlayBackUri(Uri.parse("http://tv.com/playback/1"))
    .setReleaseDateEpochMillis(1633032895L)
    .setAvailability(ContentAvailability.AVAILABILITY_AVAILABLE)
    .setDurationMillis(12345678L)
    .addGenre("action")
    .addContentRating("R")
    .setWatchNextType(WatchNextType.TYPE_NEW)
    .setLastEngagementTimeMillis(1664568895L)
    .build()

Java

MovieEntity movie = new MovieEntity.Builder()
                  .setName("Avengers")
                  .addPosterImage(
                      new Image.Builder()
                          .setImageUri(Uri.parse("http://www.x.com/image.png"))
                          .setImageHeightInPixel(960)
                          .setImageWidthInPixel(408)
                          .build())
                  .setPlayBackUri(Uri.parse("http://tv.com/playback/1"))
                  .setReleaseDateEpochMillis(1633032895L)
                  .setAvailability(ContentAvailability.AVAILABILITY_AVAILABLE)
                  .setDurationMillis(12345678L)
                  .addGenre("action")
                  .addContentRating("R")
                  .setWatchNextType(WatchNextType.TYPE_NEW)
                  .setLastEngagementTimeMillis(1664568895L)
                  .build();

第 2 步：提供集群数据

建议将内容发布作业在后台执行（例如，使用WorkManager），并定期或根据事件（例如，每次用户打开应用或用户刚将某物添加到购物车时）进行调度。

AppEngagePublishClient 负责发布集群。客户端中提供以下 API

isServiceAvailable
publishRecommendationClusters
publishFeaturedCluster
publishContinuationCluster
publishUserAccountManagementRequest
updatePublishStatus
deleteRecommendationsClusters
deleteFeaturedCluster
deleteContinuationCluster
deleteUserManagementCluster
deleteClusters

`isServiceAvailable`

此 API 用于检查服务是否可用于集成以及内容是否可以在设备上显示。

Kotlin

client.isServiceAvailable.addOnCompleteListener { task ->
    if (task.isSuccessful) {
        // Handle IPC call success
        if(task.result) {
          // Service is available on the device, proceed with content publish
          // calls.
        } else {
          // Service is not available, no further action is needed.
        }
    } else {
      // The IPC call itself fails, proceed with error handling logic here,
      // such as retry.
    }
}

Java

client.isServiceAvailable().addOnCompleteListener(task - > {
    if (task.isSuccessful()) {
        // Handle success
        if(task.getResult()) {
          // Service is available on the device, proceed with content publish
          // calls.
        } else {
          // Service is not available, no further action is needed.
        }
    } else {
      // The IPC call itself fails, proceed with error handling logic here,
      // such as retry.
    }
});

`publishRecommendationClusters`

此 API 用于发布 RecommendationCluster 对象的列表。

Kotlin

client.publishRecommendationClusters(
      PublishRecommendationClustersRequest.Builder()
        .addRecommendationCluster(
          RecommendationCluster.Builder()
            .addEntity(entity1)
            .addEntity(entity2)
            .setTitle("Top Picks For You")
            .build()
        )
        .build()
    )

Java

client.publishRecommendationClusters(
            new PublishRecommendationClustersRequest.Builder()
                .addRecommendationCluster(
                    new RecommendationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .setTitle("Top Picks For You")
                        .build())
                .build());

当服务收到请求时，将在一个事务中执行以下操作

来自开发者合作伙伴的现有 RecommendationCluster 数据被删除。
请求中的数据被解析并存储在更新后的推荐集群中。

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

`publishFeaturedCluster`

此 API 用于发布 FeaturedCluster 对象的列表。

Kotlin

client.publishFeaturedCluster(
    PublishFeaturedClusterRequest.Builder()
      .setFeaturedCluster(
        FeaturedCluster.Builder()
          .addEntity(entity1)
          .addEntity(entity2)
          .build())
      .build())

Java

client.publishFeaturedCluster(
            new PublishFeaturedClustersRequest.Builder()
                .addFeaturedCluster(
                    new FeaturedCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .build())
                .build());

当服务收到请求时，将在一个事务中执行以下操作

来自开发者合作伙伴的现有 FeaturedCluster 数据被删除。
请求中的数据被解析并存储在更新后的精选集群中。

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

`publishContinuationCluster`

此 API 用于发布 ContinuationCluster 对象。

Kotlin

client.publishContinuationCluster(
    PublishContinuationClusterRequest.Builder()
      .setContinuationCluster(
        ContinuationCluster.Builder()
          .addEntity(entity1)
          .addEntity(entity2)
          .build())
      .build())

Java

client.publishContinuationCluster(
            new PublishContinuationClusterRequest.Builder()
                .setContinuationCluster(
                    new ContinuationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .build())
                .build());

当服务收到请求时，将在一个事务中执行以下操作

来自开发者合作伙伴的现有 ContinuationCluster 数据被删除。
请求中的数据被解析并存储在更新后的续播集群中。

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

`publishUserAccountManagementRequest`

此 API 用于发布登录卡。登录操作会将用户定向到应用的登录页面，以便应用可以发布内容（或提供更多个性化内容）

以下元数据是登录卡的一部分 -

属性	要求	描述
操作 URI	必填	操作的深层链接（即导航到应用登录页面）
图片	可选 - 如果未提供，则必须提供标题	卡片上显示的图片 16x9 宽高比图片，分辨率为 1264x712
标题	可选 - 如果未提供，则必须提供图片	卡片上的标题
操作文本	可选	CTA 上显示的文本（即登录）
副标题	可选	卡片上的可选副标题

Kotlin

var SIGN_IN_CARD_ENTITY =
      SignInCardEntity.Builder()
          .addPosterImage(
              Image.Builder()
                  .setImageUri(Uri.parse("http://www.x.com/image.png"))
                  .setImageHeightInPixel(500)
                  .setImageWidthInPixel(500)
                  .build())
          .setActionText("Sign In")
          .setActionUri(Uri.parse("http://xx.com/signin"))
          .build()

client.publishUserAccountManagementRequest(
            PublishUserAccountManagementRequest.Builder()
                .setSignInCardEntity(SIGN_IN_CARD_ENTITY)
                .build());

Java

SignInCardEntity SIGN_IN_CARD_ENTITY =
      new SignInCardEntity.Builder()
          .addPosterImage(
              new Image.Builder()
                  .setImageUri(Uri.parse("http://www.x.com/image.png"))
                  .setImageHeightInPixel(500)
                  .setImageWidthInPixel(500)
                  .build())
          .setActionText("Sign In")
          .setActionUri(Uri.parse("http://xx.com/signin"))
          .build();

client.publishUserAccountManagementRequest(
            new PublishUserAccountManagementRequest.Builder()
                .setSignInCardEntity(SIGN_IN_CARD_ENTITY)
                .build());

当服务收到请求时，将在一个事务中执行以下操作

来自开发者合作伙伴的现有 UserAccountManagementCluster 数据被删除。
请求中的数据被解析并存储在更新后的 UserAccountManagementCluster 集群中。

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

`updatePublishStatus`

如果由于任何内部业务原因，任何集群都未发布，我们强烈建议使用 updatePublishStatus API 更新发布状态。这很重要，因为

在所有场景中提供状态，即使内容已发布（STATUS == PUBLISHED），对于填充使用此明确状态来传达集成健康状况和其他指标的仪表板至关重要。
如果没有内容发布但集成状态未损坏（STATUS == NOT_PUBLISHED），Google 可以避免在应用健康仪表板中触发警报。这确认了内容未发布是提供方预期的情况。
它帮助开发者深入了解数据何时发布，何时未发布。
Google 可以使用状态代码来提示用户在应用中执行某些操作，以便他们可以看到应用内容或克服问题。

符合条件的发布状态代码列表为

// Content is published
AppEngagePublishStatusCode.PUBLISHED,

// Content is not published as user is not signed in
AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SIGN_IN,

// Content is not published as user is not subscribed
AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SUBSCRIPTION,

// Content is not published as user location is ineligible
AppEngagePublishStatusCode.NOT_PUBLISHED_INELIGIBLE_LOCATION,

// Content is not published as there is no eligible content
AppEngagePublishStatusCode.NOT_PUBLISHED_NO_ELIGIBLE_CONTENT,

// Content is not published as the feature is disabled by the client
// Available in v1.3.1
AppEngagePublishStatusCode.NOT_PUBLISHED_FEATURE_DISABLED_BY_CLIENT,

// Content is not published as the feature due to a client error
// Available in v1.3.1
AppEngagePublishStatusCode.NOT_PUBLISHED_CLIENT_ERROR,

// Content is not published as the feature due to a service error
// Available in v1.3.1
AppEngagePublishStatusCode.NOT_PUBLISHED_SERVICE_ERROR,

// Content is not published due to some other reason
// Reach out to engage-developers@ before using this enum.
AppEngagePublishStatusCode.NOT_PUBLISHED_OTHER

如果内容因用户未登录而未发布，Google 建议发布登录卡。如果提供方因任何原因无法发布登录卡，我们建议使用状态代码 NOT_PUBLISHED_REQUIRES_SIGN_IN 调用 updatePublishStatus API

Kotlin

client.updatePublishStatus(
   PublishStatusRequest.Builder()
     .setStatusCode(AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SIGN_IN)
     .build())

Java

client.updatePublishStatus(
    new PublishStatusRequest.Builder()
        .setStatusCode(AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SIGN_IN)
        .build());

`deleteRecommendationClusters`

此 API 用于删除推荐集群的内容。

Kotlin

client.deleteRecommendationClusters()

Java

client.deleteRecommendationClusters();

当服务收到请求时，它会删除推荐集群中的现有数据。如果发生错误，整个请求将被拒绝，并保留现有状态。

`deleteFeaturedCluster`

此 API 用于删除精选集群的内容。

Kotlin

client.deleteFeaturedCluster()

Java

client.deleteFeaturedCluster();

当服务收到请求时，它会删除精选集群中的现有数据。如果发生错误，整个请求将被拒绝，并保留现有状态。

`deleteContinuationCluster`

此 API 用于删除续播集群的内容。

Kotlin

client.deleteContinuationCluster()

Java

client.deleteContinuationCluster();

当服务收到请求时，它会删除续播集群中的现有数据。如果发生错误，整个请求将被拒绝，并保留现有状态。

`deleteUserManagementCluster`

此 API 用于删除 UserAccountManagement 集群的内容。

Kotlin

client.deleteUserManagementCluster()

Java

client.deleteUserManagementCluster();

当服务收到请求时，它会删除 UserAccountManagement 集群中的现有数据。如果发生错误，整个请求将被拒绝，并保留现有状态。

`deleteClusters`

此 API 用于删除给定集群类型的内容。

Kotlin

client.deleteClusters(
    DeleteClustersRequest.Builder()
      .addClusterType(ClusterType.TYPE_CONTINUATION)
      .addClusterType(ClusterType.TYPE_FEATURED)
      .addClusterType(ClusterType.TYPE_RECOMMENDATION)
      .build())

Java

client.deleteClusters(
            new DeleteClustersRequest.Builder()
                .addClusterType(ClusterType.TYPE_CONTINUATION)
                .addClusterType(ClusterType.TYPE_FEATURED)
                .addClusterType(ClusterType.TYPE_RECOMMENDATION)
                .build());

当服务收到请求时，它会删除所有与指定集群类型匹配的集群中的现有数据。客户端可以选择传递一种或多种集群类型。如果发生错误，整个请求将被拒绝，并保留现有状态。

错误处理

强烈建议监听来自发布 API 的任务结果，以便采取后续操作来恢复并重新提交成功的任务。

Kotlin

client.publishRecommendationClusters(
        PublishRecommendationClustersRequest.Builder()
          .addRecommendationCluster(..)
          .build())
      .addOnCompleteListener { task ->
        if (task.isSuccessful) {
          // do something
        } else {
          val exception = task.exception
          if (exception is AppEngageException) {
            @AppEngageErrorCode val errorCode = exception.errorCode
            if (errorCode == AppEngageErrorCode.SERVICE_NOT_FOUND) {
              // do something
            }
          }
        }
      }

Java

client.publishRecommendationClusters(
              new PublishRecommendationClustersRequest.Builder()
                  .addRecommendationCluster(...)
                  .build())
          .addOnCompleteListener(
              task -> {
                if (task.isSuccessful()) {
                  // do something
                } else {
                  Exception exception = task.getException();
                  if (exception instanceof AppEngageException) {
                    @AppEngageErrorCode
                    int errorCode = ((AppEngageException) exception).getErrorCode();
                    if (errorCode == AppEngageErrorCode.SERVICE_NOT_FOUND) {
                      // do something
                    }
                  }
                }
              });

错误作为 AppEngageException 返回，其中原因包含为错误代码。

错误代码	错误名称	注意
`1`	`SERVICE_NOT_FOUND`	给定设备上找不到服务。
`2`	`SERVICE_NOT_AVAILABLE`	服务在给定设备上可用，但在调用时不可用（例如，它被明确禁用）。
`3`	`SERVICE_CALL_EXECUTION_FAILURE`	由于线程问题，任务执行失败。在这种情况下，可以重试。
`4`	`SERVICE_CALL_PERMISSION_DENIED`	调用者不允许进行服务调用。
`5`	`SERVICE_CALL_INVALID_ARGUMENT`	请求包含无效数据（例如，超过允许的集群数量）。
`6`	`SERVICE_CALL_INTERNAL`	服务端发生错误。
`7`	`SERVICE_CALL_RESOURCE_EXHAUSTED`	服务调用过于频繁。

第 3 步：处理广播 Intent

除了通过作业进行发布内容 API 调用外，还需要设置 BroadcastReceiver 来接收内容发布请求。

广播 Intent 的主要目标是应用重新激活和强制数据同步。广播 Intent 不会频繁发送。它仅在 Engage 服务确定内容可能已过时（例如，一周前）时触发。这样，即使应用程序长时间未执行，用户也能更自信地获得新鲜的内容体验。

BroadcastReceiver 必须通过以下两种方式设置

使用 Context.registerReceiver() 动态注册 BroadcastReceiver 类实例。这使得仍存在于内存中的应用程序能够进行通信。

Kotlin

class AppEngageBroadcastReceiver : BroadcastReceiver(){
  // Trigger recommendation cluster publish when PUBLISH_RECOMMENDATION broadcast
  // is received
  // Trigger featured cluster publish when PUBLISH_FEATURED broadcast is received
  // Trigger continuation cluster publish when PUBLISH_CONTINUATION broadcast is
  // received
}

fun registerBroadcastReceivers(context: Context){
  var  context = context
  context = context.applicationContext

// Register Recommendation Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(Intents.ACTION_PUBLISH_RECOMMENDATION))

// Register Featured Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(Intents.ACTION_PUBLISH_FEATURED))

// Register Continuation Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(Intents.ACTION_PUBLISH_CONTINUATION))
}

Java

class AppEngageBroadcastReceiver extends BroadcastReceiver {
// Trigger recommendation cluster publish when PUBLISH_RECOMMENDATION broadcast
// is received

// Trigger featured cluster publish when PUBLISH_FEATURED broadcast is received

// Trigger continuation cluster publish when PUBLISH_CONTINUATION broadcast is
// received
}

public static void registerBroadcastReceivers(Context context) {

context = context.getApplicationContext();

// Register Recommendation Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
new IntentFilter(com.google.android.engage.service.Intents.ACTION_PUBLISH_RECOMMENDATION));

// Register Featured Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
new IntentFilter(com.google.android.engage.service.Intents.ACTION_PUBLISH_FEATURED));

// Register Continuation Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
new IntentFilter(com.google.android.engage.service.Intents.ACTION_PUBLISH_CONTINUATION));

}

在您的 AndroidManifest.xml 文件中使用 <receiver> 标签静态声明实现。这允许应用程序在未运行时接收广播 Intent，并且还允许应用程序发布内容。

<application>
   <receiver
      android:name=".AppEngageBroadcastReceiver"
      android:exported="true"
      android:enabled="true">
      <intent-filter>
         <action android:name="com.google.android.engage.action.PUBLISH_RECOMMENDATION" />
      </intent-filter>
      <intent-filter>
         <action android:name="com.google.android.engage.action.PUBLISH_FEATURED" />
      </intent-filter>
      <intent-filter>
         <action android:name="com.google.android.engage.action.PUBLISH_CONTINUATION" />
      </intent-filter>
   </receiver>
</application>

服务发送以下 Intent

com.google.android.engage.action.PUBLISH_RECOMMENDATION 建议在收到此 Intent 时启动 publishRecommendationClusters 调用。
com.google.android.engage.action.PUBLISH_FEATURED 建议在收到此 Intent 时启动 publishFeaturedCluster 调用。
com.google.android.engage.action.PUBLISH_CONTINUATION 建议在收到此 Intent 时启动 publishContinuationCluster 调用。

集成工作流

有关集成完成后验证集成的分步指南，请参阅Engage 开发者集成工作流。

常见问题

有关常见问题，请参阅Engage SDK 常见问题。

联系我们

如果在集成过程中有任何疑问，请联系 engage-developers@google.com。

后续步骤

完成此集成后，您的后续步骤如下

向 engage-developers@google.com 发送电子邮件，并附上您已集成且已准备好供 Google 测试的 APK。
Google 将执行验证并在内部审查，以确保集成按预期工作。如果需要更改，Google 将联系您并提供所有必要的详细信息。
测试完成后，如果不需要更改，Google 将联系您，通知您可以开始将更新和集成的 APK 发布到 Play 商店。
Google 确认您的更新 APK 已发布到 Play 商店后，您的推荐、精选和续播集群可能会发布并对用户可见。

Engage SDK Watch：第三方技术集成说明 使用收藏夹整理内容 根据您的偏好保存和分类内容。

集成详情

术语

准备工作

摘要

第 0 步：从现有 Media Home SDK 集成迁移

映射现有集成中的数据模型

在 Media Home SDK 和 Engage SDK 中发布集群

Kotlin

Java

第 1 步：提供实体数据

MovieEntity

TvShowEntity

TvSeasonEntity

TvEpisodeEntity

LiveStreamingVideoEntity

VideoClipEntity

图片规格

示例

Kotlin

Java

第 2 步：提供集群数据

isServiceAvailable

Kotlin

Java

publishRecommendationClusters

Kotlin

Java

publishFeaturedCluster

Kotlin

Java

publishContinuationCluster

Kotlin

Java

publishUserAccountManagementRequest

Kotlin

Java

updatePublishStatus

Kotlin

Java

deleteRecommendationClusters

Kotlin

Java

deleteFeaturedCluster

Kotlin

Java

deleteContinuationCluster

Kotlin

Java

deleteUserManagementCluster

Kotlin

Java

deleteClusters

Kotlin

Java

错误处理

Kotlin

Java

第 3 步：处理广播 Intent

Kotlin

Java

集成工作流

常见问题

联系我们

后续步骤

Engage SDK Watch：第三方技术集成说明

`MovieEntity`

`TvShowEntity`

`TvSeasonEntity`

`TvEpisodeEntity`

`LiveStreamingVideoEntity`

`VideoClipEntity`

`isServiceAvailable`

`publishRecommendationClusters`

`publishFeaturedCluster`

`publishContinuationCluster`

`publishUserAccountManagementRequest`

`updatePublishStatus`

`deleteRecommendationClusters`

`deleteFeaturedCluster`

`deleteContinuationCluster`

`deleteUserManagementCluster`

`deleteClusters`