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. EbookEntity
2. AudiobookEntity
3. BookSeriesEntity

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

EbookEntity

EbookEntity 对象代表电子书（例如，米歇尔·奥巴马的《成为》的电子书）。

AudiobookEntity

The AudiobookEntity 对象表示有声读物（例如，米歇尔·奥巴马的成为的有声读物）。

BookSeriesEntity

The BookSeriesEntity 对象表示一个书籍系列（例如，哈利·波特书籍系列，包含 7 本书）。

图像规格

下面列出了图像资源的必需规格

文件格式

PNG、JPG、静态 GIF、WebP

最大文件大小

5120 KB

其他建议

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

示例

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("Reconnect with yourself")
                        .build())
                .build())

client.publishRecommendationClusters(
            new PublishRecommendationClustersRequest.Builder()
                .addRecommendationCluster(
                    new RecommendationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .setTitle("Reconnect with yourself")
                        .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(book_entity1)
                        .addEntity(book_entity2)
                        .build())
                .build())

client.publishContinuationCluster(
            PublishContinuationClusterRequest.Builder()
                .setContinuationCluster(
                    ContinuationCluster.Builder()
                        .addEntity(book_entity1)
                        .addEntity(book_entity2)
                        .build())
                .build())

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

• 删除开发合作伙伴的现有 ContinuationCluster 数据。
• 解析请求中的数据并将其存储在更新的继续集群中。

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

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 用于删除推荐集群的内容。

client.deleteRecommendationClusters()

client.deleteRecommendationClusters();

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

deleteFeaturedCluster

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

client.deleteFeaturedCluster()

client.deleteFeaturedCluster();

当服务收到请求时，它会从特色集群中删除现有数据。如果出现错误，整个请求将被拒绝，并将保持现有状态。

deleteContinuationCluster

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

client.deleteContinuationCluster()

client.deleteContinuationCluster();

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

deleteUserManagementCluster

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

client.deleteUserManagementCluster()

client.deleteUserManagementCluster();

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

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 商店后，您的 **推荐**、**精选** 和 **延续** 集群将发布并对用户可见。