Engage SDK 监听:第三方技术集成说明

通过在用户所在的设备界面上触达他们,提升应用互动率。集成 Engage SDK 可直接向用户在多个设备界面(如 收藏夹娱乐空间和 Play 商店)提供个性化推荐和续播内容。此集成会使平均 APK 大小增加不到 50 KB(压缩后),并且大多数应用大约需要一周的开发时间。访问我们的 商业网站了解更多信息。

本指南包含面向开发者合作伙伴的说明,用于将音频内容(音乐、播客、有声读物、直播电台)传递到 Engage 内容界面。

集成详情

术语

此集成包含以下三种集群类型:推荐续播精选

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

    您的推荐采用以下结构

    • 推荐集群:一种 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'
}

摘要

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

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

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

步骤 1:提供实体数据

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

  1. MusicAlbumEntity
  2. MusicArtistEntity
  3. MusicTrackEntity
  4. MusicVideoEntity
  5. PlaylistEntity
  6. PodcastSeriesEntity
  7. PodcastEpisodeEntity
  8. LiveRadioStationEntity
  9. AudiobookEntity

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

MusicAlbumEntity

The MusicAlbumEntity 对象代表一个音乐专辑(例如,Taylor Swift 的《Midnights》)。

属性 要求 备注
名称 必需 音乐专辑的标题。
海报图片 必需 必须提供至少一张图片。请参阅图片规格了解指南。
信息页 URI 必需

指向提供方应用中音乐专辑详情的深层链接。

注意:您可以使用深层链接进行归因。 请参阅此常见问题解答

艺术家 必需 音乐专辑中的艺术家列表。
播放 URI 可选

一个在提供方应用中开始播放专辑的深层链接。

注意:您可以使用深层链接进行归因。 请参阅此常见问题解答

说明 可选 如果提供,必须在 200 个字符以内。
歌曲数量 可选 音乐专辑中的歌曲数量。
流派 可选 音乐专辑中的流派列表。
专辑格式 可选

专辑(包括 LP 和双 LP)

EP

单曲

混音带

音乐厂牌 可选 与专辑关联的音乐厂牌列表。
已下载到设备 可选 一个布尔值,指示音乐专辑是否已下载到设备上。
露骨内容 可选

一个布尔值,指示内容是否为露骨内容

包含露骨内容或家长指导警告的项目应设置为 TRUE。露骨内容项目会显示“E”标签。

发布日期 可选 专辑的发布日期(以 epoch 毫秒为单位)。
时长 可选 专辑的时长(以毫秒为单位)。
最后互动时间 可选

建议用于续播集群中的项目。可用于排名。

以 epoch 毫秒为单位

完成进度百分比 可选

建议用于续播集群中的项目。

介于 0 和 100 之间的整数

MusicArtistEntity

The MusicArtistEntity 对象代表一个音乐艺术家(例如,Adele)。

属性 要求 备注
名称 必需 音乐艺术家的名称。
海报图片 必需 必须提供至少一张图片。请参阅图片规格了解指南。
信息页 URI 必需

指向提供方应用中音乐艺术家详情的深层链接。

注意:您可以使用深层链接进行归因。 请参阅此常见问题解答

播放 URI 可选

一个在提供方应用中开始播放艺术家歌曲的深层链接。

注意:您可以使用深层链接进行归因。 请参阅此常见问题解答

说明 可选 如果提供,必须在 200 个字符以内。
最后互动时间 可选

建议用于续播集群中的项目。可用于排名。

以 epoch 毫秒为单位

MusicTrackEntity

The MusicTrackEntity 对象代表一个音乐曲目(例如,Coldplay 的《Yellow》)。

属性 要求 备注
名称 必需 音乐曲目的标题。
海报图片 必需 必须提供至少一张图片。请参阅图片规格了解指南。
播放 URI 必需

一个在提供方应用中开始播放音乐曲目的深层链接。

注意:您可以使用深层链接进行归因。 请参阅此常见问题解答

艺术家 必需 音乐曲目的艺术家列表。
信息页 URI 可选

指向提供方应用中音乐曲目详情的深层链接。

注意:您可以使用深层链接进行归因。 请参阅此常见问题解答

说明 可选 如果提供,必须在 200 个字符以内。
时长 可选 曲目的时长(以毫秒为单位)。
专辑 可选 歌曲所属专辑的名称。
已下载到设备 可选 一个布尔值,指示音乐曲目是否已下载到设备上。
露骨内容 可选

一个布尔值,指示内容是否为露骨内容

包含露骨内容或家长指导警告的项目应设置为 TRUE。露骨内容项目会显示“E”标签。

最后互动时间 可选

建议用于续播集群中的项目。可用于排名。

以 epoch 毫秒为单位

完成进度百分比 可选

建议用于续播集群中的项目。

介于 0 和 100 之间的整数

MusicVideoEntity

The MusicVideoEntity 对象代表一个音乐视频(例如,The Weeknd - Take My Breath (Official Music Video))。

属性 要求 备注
名称 必需 音乐视频的标题。
海报图片 必需 必须提供至少一张图片。请参阅图片规格了解指南。
播放 URI 必需

一个在提供方应用中开始播放音乐视频的深层链接。

注意:您可以使用深层链接进行归因。 请参阅此常见问题解答

信息页 URI 可选

指向提供方应用中音乐视频详情的深层链接。

注意:您可以使用深层链接进行归因。 请参阅此常见问题解答

时长 可选 视频的时长(以毫秒为单位)。
观看次数 可选 视频的观看次数(以自由文本格式表示)。
艺术家 可选 音乐视频的艺术家列表。
内容分级 可选 曲目的内容分级列表。
说明 可选 如果提供,必须在 200 个字符以内。
已下载到设备 可选 一个布尔值,指示音乐视频是否已下载到设备上。
露骨内容 可选

一个布尔值,指示内容是否为露骨内容

包含露骨内容或家长指导警告的项目应设置为 TRUE。露骨内容项目会显示“E”标签。

最后互动时间 可选

建议用于续播集群中的项目。可用于排名。

以 epoch 毫秒为单位

完成进度百分比 可选

建议用于续播集群中的项目。

介于 0 和 100 之间的整数

PlaylistEntity

The PlaylistEntity 对象代表一个音乐播放列表(例如,美国 Top 10 播放列表)。

属性 要求 备注
名称 必需 播放列表的标题。
海报图片 必需 必须提供至少一张图片。请参阅图片规格了解指南。
播放 URI 必需

一个在提供方应用中开始播放音乐播放列表的深层链接。

注意:您可以使用深层链接进行归因。 请参阅此常见问题解答

信息页 URI 可选

指向提供方应用中音乐播放列表详情的深层链接。

注意:您可以使用深层链接进行归因。 请参阅此常见问题解答

时长 可选 播放列表的时长(以毫秒为单位)。
歌曲数量 可选 音乐播放列表中的歌曲数量。
说明 可选 如果提供,必须在 200 个字符以内。
已下载到设备 可选 一个布尔值,指示播放列表是否已下载到设备上。
露骨内容 可选

一个布尔值,指示内容是否为露骨内容

包含露骨内容或家长指导警告的项目应设置为 TRUE。露骨内容项目会显示“E”标签。

最后互动时间 可选

建议用于续播集群中的项目。可用于排名。

以 epoch 毫秒为单位

完成进度百分比 可选

建议用于续播集群中的项目。

介于 0 和 100 之间的整数

PodcastSeriesEntity

The PodcastSeriesEntity 对象代表一个播客系列(例如,This American Life)。

属性 要求 备注
名称 必需 播客系列的标题。
海报图片 必需 必须提供至少一张图片。请参阅图片规格了解指南。
信息页 URI 必需

指向提供方应用中播客系列详情的深层链接。

注意:您可以使用深层链接进行归因。 请参阅此常见问题解答

播放 URI 可选

一个在提供方应用中开始播放播客系列的深层链接。

注意:您可以使用深层链接进行归因。 请参阅此常见问题解答

剧集数量 可选 播客系列中的剧集数量。
制作名称 可选 播客系列的制作名称。
主持人 可选 播客系列的主持人列表。
流派 可选 播客系列的流派列表。
已下载到设备 可选 一个布尔值,指示播客是否已下载到设备上。
说明 可选 如果提供,必须在 200 个字符以内。
露骨内容 可选

一个布尔值,指示内容是否为露骨内容

包含露骨内容或家长指导警告的项目应设置为 TRUE。露骨内容项目会显示“E”标签。

最后互动时间 可选

建议用于续播集群中的项目。可用于排名。

以 epoch 毫秒为单位

PodcastEpisodeEntity

The PodcastEpisodeEntity 对象代表一个播客剧集(例如,Spark Bird, Episode 754: This American Life)。

属性 要求 备注
名称 必需 播客剧集的标题。
海报图片 必需 必须提供至少一张图片。请参阅图片规格了解指南。
播放 URI 必需

一个在提供方应用中开始播放播客剧集的深层链接。

注意:您可以使用深层链接进行归因。 请参阅此常见问题解答

播客系列标题 必需 剧集所属播客系列的名称。
时长 必需 播客剧集的时长(以毫秒为单位)。
发布日期 必需 播客的发布日期(以 epoch 毫秒为单位)
信息页 URI 可选

指向提供方应用中播客剧集详情的深层链接。

注意:您可以使用深层链接进行归因。 请参阅此常见问题解答

制作名称 可选 播客系列的制作名称。
剧集索引 可选 剧集在系列中的索引(第一个索引为 1)。
主持人 可选 播客剧集的主持人列表。
流派 可选 播客剧集的流派列表。
已下载到设备 可选 一个布尔值,指示播客剧集是否已下载到设备上。
说明 可选 如果提供,必须在 200 个字符以内。
视频播客 可选 一个布尔值,指示播客剧集是否包含视频内容
露骨内容 可选

一个布尔值,指示内容是否为露骨内容

包含露骨内容或家长指导警告的项目应设置为 TRUE。露骨内容项目会显示“E”标签。

下一步收听类型 可选

建议用于续播集群中的项目

TYPE_CONTINUE - 从未完成的音频项目继续播放。

TYPE_NEXT - 继续播放系列中的新一集。

TYPE_NEW - 新发布。

最后互动时间 可选

建议用于续播集群中的项目。可用于排名。

以 epoch 毫秒为单位

完成进度百分比 可选

建议用于续播集群中的项目。

介于 0 和 100 之间的整数

LiveRadioStationEntity

The LiveRadioStationEntity 对象代表一个直播电台(例如,98.1 The Breeze)。

属性 要求 备注
名称 必需 直播电台的标题。
海报图片 必需 必须提供至少一张图片。请参阅图片规格了解指南。
播放 URI 必需

一个在提供方应用中开始播放电台的深层链接。

注意:您可以使用深层链接进行归因。 请参阅此常见问题解答

信息页 URI 可选

指向提供方应用中电台详情的深层链接。

注意:您可以使用深层链接进行归因。 请参阅此常见问题解答

频率 可选 电台广播的频率(例如,“98.1 FM”)。
节目名称 可选 电台当前正在播放的节目。
主持人 可选 电台主持人列表。
说明 可选 如果提供,必须在 200 个字符以内。
最后互动时间 可选

建议用于续播集群中的项目。可用于排名。

以 epoch 毫秒为单位

AudiobookEntity

The AudiobookEntity 对象代表一个有声读物(例如,Michelle Obama 的《Becoming》有声读物)。

属性 要求 备注
名称 必需
海报图片 必需 必须提供至少一张图片。请参阅图片规格了解指南。
作者 必需 必须提供至少一位作者姓名。
操作链接 URI 必需

指向提供方应用中有声读物的深层链接。

注意:您可以使用深层链接进行归因。 请参阅此常见问题解答

旁白 可选 必须提供至少一位旁白姓名。
发布日期 可选 如果提供,以 epoch 毫秒为单位。
说明 可选 如果提供,必须在 200 个字符以内。
价格 可选 自由文本
时长 可选 如果提供,必须是正值。
流派 可选 与图书关联的流派列表。
系列名称 可选 有声读物所属系列的名称(例如,Harry Potter)。
系列单元索引 可选 有声读物在系列中的索引,其中 1 是系列中的第一个有声读物。例如,如果《Harry Potter and the Prisoner of Azkaban》是系列中的第 3 本书,则应将其设置为 3。
继续阅读书籍类型 可选

TYPE_CONTINUE - 从未完成的书籍继续阅读。

TYPE_NEXT - 继续播放系列中的新一集。

TYPE_NEW - 新发布。

最后互动时间 条件性要求

当项目位于续播集群中时必须提供。

以 epoch 毫秒为单位。

完成进度百分比 条件性要求

当项目位于续播集群中时必须提供。

获取的有声读物可以作为继续阅读集群的一部分。

值必须大于 0 且小于 100。

DisplayTimeWindow - 为内容在界面上显示设置时间窗口
开始时间戳 可选

内容应在界面上显示后的 epoch 时间戳。

如果未设置,则内容有资格在界面上显示。

以 epoch 毫秒为单位。

结束时间戳 可选

内容不再在界面上显示后的 epoch 时间戳。

如果未设置,则内容有资格在界面上显示。

以 epoch 毫秒为单位。

图片规格

图片资产的必需规格如下所示

宽高比 要求 最小像素 推荐像素
正方形 (1x1) 必需 300x300 1200x1200
横向 (1.91x1) 可选 600x314 1200x628
纵向 (4x5) 可选 480x600 960x1200

文件格式

PNG、JPG、静态 GIF、WebP

最大文件大小

5120 KB

其他建议

  • 图片安全区域:将您的重要内容放在图片中心 80% 的区域内。

示例

MusicAlbumEntity musicAlbumEntity =
        new MusicAlbumEntity.Builder()
            .setName(NAME)
             .addPosterImage(new Image.Builder()
                  .setImageUri(Uri.parse("http://www.x.com/image.png"))
                  .setImageHeightInPixel(960)
                  .setImageWidthInPixel(408)
                  .build())
            .setPlayBackUri("https://play.google/album/play")
            .setInfoPageUri("https://play.google/album/info")
            .setDescription("A description of this album.")
            .addArtist("Artist")
            .addGenre("Genre")
            .addMusicLabel("Label")
            .addContentRating("Rating")
            .setSongsCount(960)
            .setReleaseDateEpochMillis(1633032895L)
            .setDurationMillis(1633L)
            .build();
AudiobookEntity audiobookEntity =
        new AudiobookEntity.Builder()
            .setName("Becoming")
            .addPosterImage(new Image.Builder()
                 .setImageUri(Uri.parse("http://www.x.com/image.png"))
                 .setImageHeightInPixel(960)
                 .setImageWidthInPixel(408)
                  .build())
            .addAuthor("Michelle Obama")
            .addNarrator("Michelle Obama")
            .setActionLinkUri(
               Uri.parse("https://play.google/audiobooks/1"))
            .setDurationMillis(16335L)
            .setPublishDateEpochMillis(1633032895L)
            .setDescription("An intimate, powerful, and inspiring memoir")
            .setPrice("$16.95")
            .addGenre("biography")
            .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("Trending music")
                        .build())
                .build())

Java

client.publishRecommendationClusters(
            new PublishRecommendationClustersRequest.Builder()
                .addRecommendationCluster(
                    new RecommendationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .setTitle("Trending music")
                        .build())
                .build());

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

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

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

publishFeaturedCluster

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

Kotlin

client.publishFeaturedCluster(
            PublishFeaturedClusterRequest.Builder()
                .setFeaturedCluster(
                    FeaturedCluster.Builder()
                        ...
                        .build())
                .build())

Java

client.publishFeaturedCluster(
            new PublishFeaturedClusterRequest.Builder()
                .setFeaturedCluster(
                    new FeaturedCluster.Builder()
                        ...
                        .build())
                .build());

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

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

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

publishContinuationCluster

此 API 用于发布 ContinuationCluster 对象。

Kotlin

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

Java

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

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

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

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

publishUserAccountManagementRequest

此 API 用于发布登录卡。登录操作会将用户引导至应用的登录页面,以便应用可以发布内容(或提供更个性化的内容)

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

属性 要求 说明
操作 URI 必需 操作深层链接(即导航到应用登录页面)
图片 可选 - 如果未提供,则必须提供标题

卡片上显示的图片

分辨率为 1264x712 的 16x9 宽高比图片

标题 可选 - 如果未提供,则必须提供图片 卡片上的标题
操作文本 可选 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();

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

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_FEATURED)
      .addClusterType(ClusterType.TYPE_RECOMMENDATION)
      ...
      .build())

Java

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

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

错误处理

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

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 服务确定内容可能已过期(例如,一周前的内容)时触发。这样,即使应用长时间未执行,用户也能更确信地获得新鲜的内容体验。

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

  • 使用 Context.registerReceiver() 动态注册 BroadcastReceiver 类的一个实例。这使得仍在内存中运行的应用能够进行通信。
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 商店后,您的推荐精选续播集群将发布并对用户可见。