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

Google 正在构建一个设备上的界面，它按垂直领域组织用户的应用，并为个性化的应用内容消费和发现提供新的沉浸式体验。此全屏体验为开发者合作伙伴提供了一个机会，让他们在专门的频道中展示他们最好的富媒体内容，该频道位于他们的应用之外。

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

集成细节

术语

此集成包括以下五种集群类型：**推荐**、**特色**、**食品购物车**、**食品购物清单**和**重新订购**。

• **推荐**集群显示来自单个开发者合作伙伴的个性化食品相关建议。这些推荐可以针对用户个性化或通用化（例如，新上架）。根据您的需要，将它们用于展示食谱、商店、菜肴、杂货等。

  • 推荐集群可以由ProductEntity、StoreEntity或RecipeEntity列表组成，但不能混合使用不同的实体类型。

  

• **特色**集群展示来自许多开发者合作伙伴的选定英雄ProductEntity、StoreEntity或RecipeEntity，在一个 UI 分组中。只有一个特色集群，它出现在 UI 顶部附近，优先级高于所有推荐集群。每个开发者合作伙伴都可以广播一个支持类型的实体，该实体位于特色中，并且特色集群中有多个实体（可能是不同类型的实体）来自多个应用开发者。

  

• **食品购物车**集群显示来自多个开发者合作伙伴的杂货购物车的预览，在一个 UI 分组中，提示用户完成他们未完成的购物车。只有一个食品购物车集群。

  • 食品购物车集群必须显示购物车中的商品总数，并且还可以包含用户购物车中 X 个商品的图片。

    

• **食品购物清单**集群显示来自多个开发者合作伙伴的杂货购物清单的预览，在一个 UI 分组中，提示用户返回相应的应用以更新和完成他们的清单。只有一个食品购物清单集群。

  

• **重新订购**集群显示来自多个开发者合作伙伴的先前订单的预览，在一个 UI 分组中，提示用户重新订购。只有一个重新订购集群。

  • 重新订购集群必须显示用户先前订单中的商品总数，并且还必须包含以下内容之一

    • 用户先前订单中 X 个商品的图片。
    • 用户先前订单中 X 个商品的标签。

  

预先工作

最低 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. ProductEntity
2. StoreEntity
3. RecipeEntity
4. FoodShoppingCart
5. FoodShoppingList
6. FoodReorderCluster

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

ProductEntity

该 ProductEntity 对象表示开发合作伙伴想要发布的单个项目（例如，杂货商品、餐厅菜肴或促销活动）。

StoreEntity

该 StoreEntity 对象表示开发合作伙伴想要发布的单个商店，例如餐厅或杂货店。

RecipeEntity

该 RecipeEntity 对象表示开发合作伙伴想要发布的食谱项目。

FoodShoppingCart

FoodShoppingList

FoodReorderCluster

图片规格

以下列出了图片资产的必需规格

文件格式

PNG、JPG、静态 GIF、WebP

最大文件大小

5120 KB

其他建议

• 图片安全区域：将您的重要内容放在图片中心 80% 的区域内。
• 使用透明背景，以便图片可以在深色和浅色主题设置中正确显示。

步骤 2：提供聚类数据

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

AppEngageFoodClient 负责发布食品聚类。

客户端中以下 API 用于发布聚类

• isServiceAvailable
• publishRecommendationClusters
• publishFeaturedCluster
• publishFoodShoppingCart
• publishFoodShoppingList
• publishReorderCluster
• publishUserAccountManagementRequest
• updatePublishStatus
• deleteRecommendationsClusters
• deleteFeaturedCluster
• deleteFoodShoppingCartCluster
• deleteFoodShoppingListCluster
• deleteReorderCluster
• 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 对象列表。

该 RecommendationCluster 对象可以具有以下属性

client.publishRecommendationClusters(
            PublishRecommendationClustersRequest.Builder()
                .addRecommendationCluster(
                    RecommendationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .setTitle("Big savings on Thanksgiving menu")
                        .build())
                .build())

client.publishRecommendationClusters(
            new PublishRecommendationClustersRequest.Builder()
                .addRecommendationCluster(
                    new RecommendationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .setTitle("Big savings on Thanksgiving menu")
                        .build())
                .build());

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

• 删除所有现有的推荐群组数据。
• 解析请求中的数据并将其存储到新的推荐群组中。

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

publishFeaturedCluster

此 API 用于发布 FeaturedCluster 对象。

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

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

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

• 删除开发者合作伙伴提供的现有 FeaturedCluster 数据。
• 解析请求中的数据并将其存储到更新的精选群组中。

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

publishFoodShoppingCart

此 API 用于发布 FoodShoppingCart 对象。

client.publishFoodShoppingCart(
            PublishFoodShoppingCartClusterRequest.Builder()
                .setShoppingCart(
                    FoodShoppingCart.Builder()
                        ...
                        .build())
                .build())

client.publishFoodShoppingCart(
            new PublishFoodShoppingCartClusterRequest.Builder()
                .setShoppingCart(
                    new FoodShoppingCart.Builder()
                        ...
                        .build())
                .build());

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

• 删除开发者合作伙伴提供的现有 FoodShoppingCart 数据。
• 解析请求中的数据并将其存储到更新的购物车群组中。

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

publishFoodShoppingList

此 API 用于发布 FoodShoppingList 对象。

client.publishFoodShoppingList(
            PublishFoodShoppingListRequest.Builder()
                .setFoodShoppingList(
                    FoodShoppingListEntity.Builder()
                        ...
                        .build())
                .build())

client.publishFoodShoppingList(
            new PublishFoodShoppingListRequest.Builder()
                .setFoodShoppingList(
                    new FoodShoppingListEntity.Builder()
                        ...
                        .build())
                .build());

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

• 删除开发者合作伙伴提供的现有 FoodShoppingList 数据。
• 解析请求中的数据并将其存储到更新的购物清单群组中。

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

publishReorderCluster

此 API 用于发布 FoodReorderCluster 对象。

client.publishReorderCluster(
            PublishReorderClusterRequest.Builder()
                .setReorderCluster(
                    FoodReorderCluster.Builder()
                        ...
                        .build())
                .build())

client.publishReorderCluster(
            new PublishReorderClusterRequest.Builder()
                .setReorderCluster(
                    new FoodReorderCluster.Builder()
                        ...
                        .build())
                .build());

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

• 删除开发者合作伙伴提供的现有 FoodReorderCluster 数据。
• 解析请求中的数据并将其存储到更新的重新排序群组中。

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

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

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

deleteFoodShoppingCartCluster

此 API 用于删除食品购物车群组的内容。

client.deleteFoodShoppingCartCluster()

client.deleteFoodShoppingCartCluster();

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

deleteFoodShoppingListCluster

此 API 用于删除食品购物清单群组的内容。

client.deleteFoodShoppingListCluster()

client.deleteFoodShoppingListCluster();

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

deleteReorderCluster

此 API 用于删除 FoodReorderCluster 的内容。

client.deleteReorderCluster()

client.deleteReorderCluster();

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

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 shopping cart cluster publish when PUBLISH_FOOD_SHOPPING_CART
// broadcast is received

// Trigger shopping list cluster publish when PUBLISH_FOOD_SHOPPING_LIST
// broadcast is received

// Trigger reorder cluster publish when PUBLISH_REORDER_CLUSTER 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 Shopping Cart Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
new IntentFilter(com.google.android.engage.food.service.Intents.ACTION_PUBLISH_FOOD_SHOPPING_CART));

// Register Shopping List Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
new IntentFilter(com.google.android.engage.food.service.Intents.ACTION_PUBLISH_FOOD_SHOPPING_LIST));

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

}

• 在您的 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.food.PUBLISH_FOOD_SHOPPING_CART" />
      </intent-filter>
      <intent-filter>
         <action android:name="com.google.android.engage.action.food.PUBLISH_FOOD_SHOPPING_LIST" />
      </intent-filter>
      <intent-filter>
         <action android:name="com.google.android.engage.action.food.PUBLISH_REORDER_CLUSTER" />
      </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.food.PUBLISH_FOOD_SHOPPING_CART 建议在收到此意图时启动 publishFoodShoppingCart 调用。
• com.google.android.engage.action.food.PUBLISH_FOOD_SHOPPING_LIST 建议在收到此意图时启动 publishFoodShoppingList 调用。
• com.google.android.engage.action.food.PUBLISH_REORDER_CLUSTER 建议在收到此意图时启动 publishReorderCluster 调用。

集成工作流程

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

常见问题解答

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

联系方式

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

下一步

完成此集成后，您的下一步操作如下：

• 向 [email protected] 发送电子邮件，并附加您已准备好由 Google 测试的集成 APK。
• Google 将在内部执行验证和审核，以确保集成按预期工作。如果需要更改，Google 会与您联系，并提供必要的详细信息。
• 当测试完成后，并且不需要进行任何更改时，Google 会与您联系，通知您可以开始将更新的集成 APK 发布到 Play 商店。
• 在 Google 确认您已将更新的 APK 发布到 Play 商店后，您的推荐、精选、购物车、购物清单和重新排序群组将发布并对用户可见。