此页面由 Cloud Translation API 翻译。

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

Google 将打造一种设备端 surface，该 surface 可按行业整理用户的应用，并且支持全新的沉浸式体验，使用户能够以个性化的方式消费和发现应用内容。这种全屏体验可为开发者合作伙伴提供新的机会，使其能够通过自己的应用以外的专用渠道展示最优质的富媒体内容。

本指南包含面向开发者合作伙伴的说明，介绍了如何使用 Engage SDK 填充这个新的 surface 区域和现有的各种 Google surface，以便集成视频内容。

集成详情

术语

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

推荐集群用于显示来自单个开发者合作伙伴的个性化推荐视频内容。

您的推荐将采用如下结构：
- 推荐集群：一个界面视图，其中包含来自同一开发者合作伙伴的一组推荐。
  
  图 1. 显示来自单个合作伙伴的推荐集群的 Entertainment Space 界面。
- 实体：代表集群中单个内容的对象。实体可以是电影、电视节目、电视连续剧、直播视频等内容。如需查看受支持的实体类型的列表，请参阅提供实体数据部分。
  
  图 2. 显示单个合作伙伴的推荐集群内的单个实体的 Entertainment Space 界面。
接续集群用于在一个界面分组中显示来自多个开发者合作伙伴的未看完视频和相关的新发布剧集。每个开发者合作伙伴最多可以在接续集群中广播 10 个实体。研究表明，将个性化推荐与个性化接续内容相结合可以产生最佳的用户互动度。

图 3. 显示接续集群（其中包含来自多个合作伙伴的未看完内容推荐，目前仅显示一个推荐）的 Entertainment Space 界面。
精选集群用于在一个界面分组中展示来自多个开发者合作伙伴的精选实体。精选集群只有一个，并将显示在界面顶部附近，其展示位置的优先级高于所有推荐集群。每个开发者合作伙伴最多可以在精选集群中广播 10 个实体。

图 4. 显示精选集群（其中包含来自多个合作伙伴的推荐，目前仅显示一个推荐）的 Entertainment Space 界面。

准备工作

最低 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 中的软件包可见性。

摘要

设计的前提是已实现了绑定服务。

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

集群类型	集群限制	集群中的实体数上限
推荐集群	最多 5 个	最多 50 个
接续集群	最多 1 个	最多 10 个
精选集群	最多 1 个	最多 10 个

第 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：内容已被用户购买或租借。
价格	可选	自由文本
时长	必需	以毫秒为单位。
类型	必需	自由文本
内容分级	必需	自由文本，请遵循业界标准。（示例）
接下来观看内容的类型	在特定条件下必需	当内容位于接续集群中时，必须提供，并且必须为以下 4 种类型之一： CONTINUE：用户观看此内容的时长已超过 1 分钟。 NEW：用户已观看某些剧集式内容的所有已上线剧集，但新剧集已上线，且恰好只有一个剧集尚未观看。这适用于电视节目、系列足球比赛录像等内容。 NEXT：用户已观看某些剧集式内容的一个或多个完整剧集，还剩多个或恰好一个剧集尚未观看，并且最后一个剧集并非“NEW”类型，而且在用户开始观看相应剧集内容之前便已发布。 WATCHLIST：用户已明确选择将电影、活动或系列剧集添加到观看列表，以手动挑选接下来要观看的内容。
上次互动时长	在特定条件下必需	当内容位于接续集群中时，必须提供。以从公元纪年开始计算的毫秒数表示。
上次播放位置时间	在特定条件下必需	当内容位于接续集群中，且 WatchNextType 为 CONTINUE 时，必须提供。以从公元纪年开始计算的毫秒数表示。

`TvShowEntity`

属性	要求	备注
名称	必需
海报图片	必需	至少需要一张图片，并且必须按照一定的宽高比提供。（首选横向图片，但建议针对不同的场景传递纵向和横向图片。）如需相关指导，请参阅图片规范。
信息页 URI	必需	指向提供商应用、用于显示电视节目详情的深层链接。注意：您可以使用深层链接进行归因。请参阅此处的常见问题解答
播放 URI	可选	指向提供商应用、用于播放电视节目的深层链接。注意：您可以使用深层链接进行归因。请参阅此处的常见问题解答
首个剧集播出日期	必需	以从公元纪年开始计算的毫秒数表示。
最新剧集播出日期	可选	以从公元纪年开始计算的毫秒数表示。
提供情况	必需	AVAILABLE：内容无需进一步操作即对用户可用。 FREE_WITH_SUBSCRIPTION：内容在用户购买订阅后可用。 PAID_CONTENT：内容要求用户购买或租借。 PURCHASED：内容已被用户购买或租借。
价格	可选	自由文本
剧季数	必需	正整数
类型	必需	自由文本
内容分级	必需	自由文本，请遵循业界标准。（示例）
接下来观看内容的类型	在特定条件下必需	当内容位于接续集群中时，必须提供，并且必须为以下 4 种类型之一： CONTINUE：用户观看此内容的时长已超过 1 分钟。 NEW：用户已观看某些剧集式内容的所有已上线剧集，但新剧集已上线，且恰好只有一个剧集尚未观看。这适用于电视节目、系列足球比赛录像等内容。 NEXT：用户已观看某些剧集式内容的一个或多个完整剧集，还剩多个或恰好一个剧集尚未观看，并且最后一个剧集并非“NEW”类型，而且在用户开始观看相应剧集内容之前便已发布。 WATCHLIST：用户已明确选择将电影、活动或系列剧集添加到观看列表，以手动挑选接下来要观看的内容。
上次互动时长	在特定条件下必需	当内容位于接续集群中时，必须提供。以从公元纪年开始计算的毫秒数表示。
上次播放位置时间	在特定条件下必需	当内容位于接续集群中，且 WatchNextType 为 CONTINUE 时，必须提供。以从公元纪年开始计算的毫秒数表示。

`TvSeasonEntity`

属性	要求	备注
名称	必需
海报图片	必需	至少需要一张图片，并且必须按照一定的宽高比提供。（首选横向图片，但建议针对不同的场景传递纵向和横向图片。）如需相关指导，请参阅图片规范。
信息页 URI	必需	指向提供商应用、用于显示电视节目剧季详情的深层链接。注意：您可以使用深层链接进行归因。请参阅此处的常见问题解答
播放 URI	可选	指向提供商应用、用于播放电视节目剧季的深层链接。注意：您可以使用深层链接进行归因。请参阅此处的常见问题解答
显示剧季编号	可选在 v1.3.1 中可用	字符串
首个剧集播出日期	必需	以从公元纪年开始计算的毫秒数表示。
最新剧集播出日期	可选	以从公元纪年开始计算的毫秒数表示。
提供情况	必需	AVAILABLE：内容无需进一步操作即对用户可用。 FREE_WITH_SUBSCRIPTION：内容在用户购买订阅后可用。 PAID_CONTENT：内容要求用户购买或租借。 PURCHASED：内容已被用户购买或租借。
价格	可选	自由文本
剧集数	必需	正整数
类型	必需	自由文本
内容分级	必需	自由文本，请遵循业界标准。（示例）
接下来观看内容的类型	在特定条件下必需	当内容位于接续集群中时，必须提供，并且必须为以下 4 种类型之一： CONTINUE：用户观看此内容的时长已超过 1 分钟。 NEW：用户已观看某些剧集式内容的所有已上线剧集，但新剧集已上线，且恰好只有一个剧集尚未观看。这适用于电视节目、系列足球比赛录像等内容。 NEXT：用户已观看某些剧集式内容的一个或多个完整剧集，还剩多个或恰好一个剧集尚未观看，并且最后一个剧集并非“NEW”类型，而且在用户开始观看相应剧集内容之前便已发布。 WATCHLIST：用户已明确选择将电影、活动或系列剧集添加到观看列表，以手动挑选接下来要观看的内容。
上次互动时长	在特定条件下必需	当内容位于接续集群中时，必须提供。以从公元纪年开始计算的毫秒数表示。
上次播放位置时间	在特定条件下必需	当内容位于接续集群中，且 WatchNextType 为 CONTINUE 时，必须提供。以从公元纪年开始计算的毫秒数表示。

`TvEpisodeEntity`

属性	要求	备注
名称	必需
海报图片	必需	至少需要一张图片，并且必须按照一定的宽高比提供。（首选横向图片，但建议针对不同的场景传递纵向和横向图片。）如需相关指导，请参阅图片规范。
播放 URI	必需	指向提供商应用、用于播放剧集的深层链接。注意：您可以使用深层链接进行归因。请参阅此常见问题解答
信息页 URI	可选	指向提供商应用、用于显示电视节目剧集详情的深层链接。注意：您可以使用深层链接进行归因。请参阅此处的常见问题解答
显示剧集编号	可选在 v1.3.1 中可用	字符串
播出日期	必需	以从公元纪年开始计算的毫秒数表示。
提供情况	必需	AVAILABLE：内容无需进一步操作即对用户可用。 FREE_WITH_SUBSCRIPTION：内容在用户购买订阅后可用。 PAID_CONTENT：内容要求用户购买或租借。 PURCHASED：内容已被用户购买或租借。
价格	可选	自由文本
时长	必需	必须是正数，以毫秒为单位。
类型	必需	自由文本
内容分级	必需	自由文本，符合业界标准。（示例）
接下来观看内容的类型	在特定条件下必需	当内容位于接续集群中时，必须提供，并且必须为以下 4 种类型之一： CONTINUE：用户观看此内容的时长已超过 1 分钟。 NEW：用户已观看某些剧集式内容的所有已上线剧集，但新剧集已上线，且恰好只有一个剧集尚未观看。这适用于电视节目、系列足球比赛录像等内容。 NEXT：用户已观看某些剧集式内容的一个或多个完整剧集，还剩多个或恰好一个剧集尚未观看，并且最后一个剧集并非“NEW”类型，而且在用户开始观看相应剧集内容之前便已发布。 WATCHLIST：用户已明确选择将电影、活动或系列剧集添加到观看列表，以手动挑选接下来要观看的内容。
上次互动时长	在特定条件下必需	当内容位于接续集群中时，必须提供。以从公元纪年开始计算的毫秒数表示。
上次播放位置时间	在特定条件下必需	当内容位于接续集群中，且 WatchNextType 为 CONTINUE 时，必须提供。以从公元纪年开始计算的毫秒数表示。

`LiveStreamingVideoEntity`

属性	要求	备注
名称	必需
海报图片	必需	至少需要一张图片，并且必须按照一定的宽高比提供。（首选横向图片，但建议针对不同的场景传递纵向和横向图片。）如需相关指导，请参阅图片规范。
播放 URI	必需	指向提供商应用、用于播放视频的深层链接。注意：您可以使用深层链接进行归因。请参阅此处的常见问题解答
广播方	必需	自由文本
开始时间	可选	以从公元纪年开始计算的毫秒数表示。
结束时间	可选	以从公元纪年开始计算的毫秒数表示。
观看次数	可选	自由文本，必须本地化。
接下来观看内容的类型	在特定条件下必需	当内容位于接续集群中时，必须提供，并且必须为以下 4 种类型之一： CONTINUE：用户观看此内容的时长已超过 1 分钟。 NEW：用户已观看某些剧集式内容的所有已上线剧集，但新剧集已上线，且恰好只有一个剧集尚未观看。这适用于电视节目、系列足球比赛录像等内容。 NEXT：用户已观看某些剧集式内容的一个或多个完整剧集，还剩多个或恰好一个剧集尚未观看，并且最后一个剧集并非“NEW”类型，而且在用户开始观看相应剧集内容之前便已发布。 WATCHLIST：用户已明确选择将电影、活动或系列剧集添加到观看列表，以手动挑选接下来要观看的内容。
上次互动时长	在特定条件下必需	当内容位于接续集群中时，必须提供。以从公元纪年开始计算的毫秒数表示。
上次播放位置时间	在特定条件下必需	当内容位于接续集群中，且 WatchNextType 为 CONTINUE 时，必须提供。以从公元纪年开始计算的毫秒数表示。

`VideoClipEntity`

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

属性	要求	备注
名称	必需
海报图片	必需	至少需要一张图片，并且必须按照一定的宽高比提供。（首选横向图片，但建议针对不同的场景传递纵向和横向图片。）如需相关指导，请参阅图片规范。
播放 URI	必需	指向提供商应用、用于播放视频的深层链接。注意：您可以使用深层链接进行归因。请参阅此常见问题解答
创建时间	必需	以从公元纪年开始计算的毫秒数表示。
时长	必需	必须是正数，以毫秒为单位。
创作者	必需	自由文本
创作者图片	可选	创作者头像的图片
观看次数	可选	自由文本，必须本地化。
接下来观看内容的类型	在特定条件下必需	当内容位于接续集群中时，必须提供，并且必须为以下 4 种类型之一： 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 建议发布登录卡片。如果提供商因任何原因无法发布登录卡片，我们建议调用 updatePublishStatus API 并将状态代码设为 NOT_PUBLISHED_REQUIRES_SIGN_IN

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();

当服务收到请求时，此 API 会从建议集群中移除现有数据。如果发生错误，系统将拒绝整个请求，并保留现有状态。

`deleteFeaturedCluster`

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

Kotlin

client.deleteFeaturedCluster()

Java

client.deleteFeaturedCluster();

当服务收到请求时，此 API 会从精选集群中移除现有数据。如果发生错误，系统将拒绝整个请求，并保留现有状态。

`deleteContinuationCluster`

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

Kotlin

client.deleteContinuationCluster()

Java

client.deleteContinuationCluster();

当服务收到请求时，此 API 会从接续集群中移除现有数据。如果发生错误，系统将拒绝整个请求，并保留现有状态。

`deleteUserManagementCluster`

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

Kotlin

client.deleteUserManagementCluster()

Java

client.deleteUserManagementCluster();

当服务收到请求时，此 API 会从 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 会从所有与指定集群类型匹配的集群中移除现有数据。客户端可以选择传递一个或多个集群类型。如果发生错误，系统将拒绝整个请求，并保留现有状态。

错误处理

强烈建议开发者监听来自发布 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 Service 确定内容可能已过时（例如，内容是一周前的）的情况下，广播 intent 才会触发。这样一来，开发者将更加确信，即使应用长时间未执行，用户也能够获得新鲜的内容体验。

必须通过以下两种方式设置 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 常见问题解答。

联系人

如果在集成过程中有任何疑问，请与 [email protected] 联系。

后续步骤

完成此集成后，请执行下列后续步骤：

发送电子邮件至 [email protected]，并将可供 Google 测试的集成 APK 添加为附件。
Google 会执行验证，并在内部进行审核，以确保集成按预期运行。如果需要更改，Google 会与您联系，将所有必要的详细信息告知您。
测试完毕后，如果无需进行任何更改，Google 将与您联系，向您说明您已可以开始将经过更新的集成 APK 发布到 Play 商店。
在 Google 确认经过更新的 APK 已发布到 Play 商店后，您的推荐、精选和接续集群便可被发布并向用户显示。