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

Google 正在构建一个设备上的界面，该界面按垂直领域组织用户的应用，并为个性化应用内容使用和发现提供全新的沉浸式体验。此全屏体验为开发者合作伙伴提供了一个机会，让他们能够在应用外部的专用渠道中展示其最佳的丰富内容。

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

集成详情

术语

此集成包括以下三种集群类型：**推荐**、**继续**和**特色**。

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

  您的推荐采用以下结构

  • **推荐集群：**包含来自同一开发者合作伙伴的一组推荐的 UI 视图。

    

  • **实体：**表示集群中单个项目的对象。实体可以是播放列表、有声读物、播客等。有关支持的实体类型的列表，请参阅提供实体数据部分。

    

• **继续**集群显示来自多个开发者合作伙伴的用户最近参与的音频内容，在一个 UI 分组中。每个开发者合作伙伴将被允许在继续集群中广播最多 10 个实体。

  

• **特色**集群在一个 UI 分组中展示来自多个开发者合作伙伴的一系列项目。将有一个特色集群，它将显示在 UI 的顶部附近，优先于所有推荐集群。每个开发者合作伙伴将被允许在特色集群中广播最多 10 个实体。

  

准备工作

最低 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'
}

总结

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

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

步骤 1：提供实体数据

SDK 已定义不同的实体来表示每种项目类型。我们支持以下适用于“倾听”类别的实体

1. 音乐专辑实体
2. 音乐艺术家实体
3. 音乐曲目实体
4. 音乐视频实体
5. 播放列表实体
6. 播客系列实体
7. 播客剧集实体
8. 直播电台实体
9. 有声书实体

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

音乐专辑实体

该MusicAlbumEntity对象表示音乐专辑（例如，泰勒·斯威夫特的《午夜》）。

音乐艺术家实体

该MusicArtistEntity对象表示音乐艺术家（例如，阿黛尔）。

音乐曲目实体

该MusicTrackEntity对象表示音乐曲目（例如，酷玩乐队的《黄色》）。

音乐视频实体

该MusicVideoEntity对象表示音乐视频（例如，《周末 - 让我喘息（官方音乐视频）》）。

播放列表实体

该PlaylistEntity对象表示音乐播放列表（例如，美国前 10 名播放列表）。

播客系列实体

该PodcastSeriesEntity对象表示播客系列（例如，《美国生活》）。

播客剧集实体

该PodcastEpisodeEntity对象表示播客剧集（例如，《火花鸟，第 754 集：美国生活》）。

直播电台实体

该LiveRadioStationEntity对象表示直播电台（例如，98.1 The Breeze）。

有声书实体

该AudiobookEntity对象表示有声书（例如，米歇尔·奥巴马的《成为》的有声书）。

图片规格

下面列出了图像资产的必要规格

文件格式

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 用于检查服务是否可用于集成以及内容是否可以在设备上呈现。

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.
    }
}

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对象的列表。

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

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

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

• 删除开发合作伙伴的现有RecommendationCluster数据。
• 分析请求中的数据并将其存储在更新的推荐集群中。

如果发生错误，则会拒绝整个请求并保持现有状态。

publishFeaturedCluster

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

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

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

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

• 删除开发合作伙伴的现有FeaturedCluster数据。
• 分析请求中的数据并将其存储在更新的特色集群中。

如果发生错误，则会拒绝整个请求并保持现有状态。

publishContinuationCluster

此 API 用于发布ContinuationCluster对象。

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

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

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

• 删除开发合作伙伴的现有ContinuationCluster数据。
• 请求中的数据被解析并存储在更新后的 Continuation Cluster 中。

如果发生错误，则会拒绝整个请求并保持现有状态。

publishUserAccountManagementRequest

此 API 用于发布登录卡片。登录操作将用户引导至应用的登录页面，以便应用发布内容（或提供更个性化的内容）。

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

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

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。

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

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

deleteRecommendationClusters

此 API 用于删除 Recommendation Clusters 的内容。

client.deleteRecommendationClusters()

client.deleteRecommendationClusters();

当服务收到请求时，它会从 Recommendation Clusters 中删除现有数据。如果发生错误，则整个请求将被拒绝，并保持现有状态。

deleteFeaturedCluster

此 API 用于删除 Featured Cluster 的内容。

client.deleteFeaturedCluster()

client.deleteFeaturedCluster();

当服务收到请求时，它会从 Featured Cluster 中删除现有数据。如果发生错误，则整个请求将被拒绝，并保持现有状态。

deleteContinuationCluster

此 API 用于删除 Continuation Cluster 的内容。

client.deleteContinuationCluster()

client.deleteContinuationCluster();

当服务收到请求时，它会从 Continuation Cluster 中删除现有数据。如果发生错误，则整个请求将被拒绝，并保持现有状态。

deleteUserManagementCluster

此 API 用于删除 UserAccountManagement Cluster 的内容。

client.deleteUserManagementCluster()

client.deleteUserManagementCluster();

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

deleteClusters

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

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

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 返回。

步骤 3：处理广播意图

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

广播意图的目标主要是应用重新激活和强制数据同步。广播意图并非设计为非常频繁地发送。仅当 Engage 服务确定内容可能已过期（例如，一周前）时才会触发。这样，即使应用程序长时间未执行，也可以更有把握地确保用户获得新鲜的内容体验。

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> 标记静态声明实现。这允许应用程序在未运行时接收广播意图，也允许应用程序发布内容。

<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>

服务将发送以下 意图

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

集成工作流程

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

常见问题

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

联系方式

如有任何疑问，请在集成过程中联系 [email protected]。我们的团队会尽快回复您。

后续步骤

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

• 发送电子邮件至 [email protected] 并附上您已准备好由 Google 测试的集成 APK。
• Google 将在内部进行验证和审查，以确保集成按预期工作。如果需要更改，Google 将与您联系，提供任何必要的详细信息。
• 测试完成后且无需任何更改时，Google 将与您联系，通知您您可以开始将更新的集成 APK 发布到 Play 商店。
• Google 确认您已将更新的 APK 发布到 Play 商店后，您的推荐、特色和续集集群将发布并对用户可见。