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

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

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

集成细节

术语

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

**推荐**集群显示来自单个开发者合作伙伴的个性化食品相关建议。这些推荐可以针对用户个性化，也可以泛化（例如，新的特价商品）。您可以根据需要使用它们来显示食谱、商店、菜肴、杂货等。
- 推荐集群可以由ProductEntity、StoreEntity或RecipeEntity列表组成，但不能混合使用不同实体类型。
图示：`ProductEntity`、`StoreEntity`和`RecipeEntity`。（*仅供说明用途的 UI*)
**特色**集群在一个 UI 分组中展示来自多个开发者合作伙伴的实体选择。将有一个单独的特色集群，该集群在 UI 顶部附近显示，优先级高于所有推荐集群。每个开发者合作伙伴将被允许在特色集群中广播最多 10 个实体。

图示：包含`RecipeEntity`的特色集群。（*仅供说明用途的 UI*)
**食品购物车**集群在一个 UI 分组中显示来自多个开发者合作伙伴的杂货购物车的预览，提示用户完成其未完成的购物车。只有一个食品购物车集群。
- 食品购物车集群必须显示购物车中商品的总数，还可以包括用户购物车中 X 件商品的图片。
  
  图示：单个合作伙伴的食品购物车集群。（*仅供说明用途的 UI*)
**食品购物清单**集群在一个 UI 分组中显示来自多个开发者合作伙伴的杂货购物清单的预览，提示用户返回相应的应用以更新和完成其清单。只有一个食品购物清单集群。

图示：单个合作伙伴的食品购物清单集群。（*仅供说明用途的 UI*)
**重新订购**集群在一个 UI 分组中显示来自多个开发者合作伙伴的上一次订单的预览，提示用户重新订购。只有一个重新订购集群。
- 重新订购集群必须显示用户上一次订单中商品的总数，并且还必须包含以下一项
  - 用户上一次订单中 X 件商品的图片。
  - 用户上一次订单中 X 件商品的标签。
图示：单个合作伙伴的食品重新订购集群。（*仅供说明用途的 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'
}

总结

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

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

集群类型	集群限制	集群中实体的最大限制
推荐集群	最多5个	最多25个（`ProductEntity`、`RecipeEntity`或`StoreEntity`）
特色集群	最多1个	最多10个（`ProductEntity`、`RecipeEntity`或`StoreEntity`）
食品购物车集群	最多1个	最多1个`ShoppingCartEntity`
食品购物清单集群	最多1个	最多1个`ShoppingListEntity`
食品重新订购集群	最多1个	最多1个`ReorderEntity`

步骤1：提供实体数据

SDK 已定义不同的实体来表示每种项目类型。我们支持以下食品类别的实体

ProductEntity
StoreEntity
RecipeEntity
FoodShoppingCart
FoodShoppingList
FoodReorderCluster

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

`ProductEntity`

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

属性	要求	描述	格式
海报图片	必需	必须提供至少一张图片。	有关指导，请参阅图片规范。
操作Uri	必需	应用中显示产品详细信息的页面的深层链接。注意：您可以使用深层链接进行归因。请参阅此常见问题解答	Uri
标题	可选	产品的名称。	自由文本建议文本大小：小于90个字符（过长的文本可能会显示省略号）
价格 - 当前	有条件地必需	产品的当前价格。如果提供了删除线价格，则必须提供。	自由文本
价格 - 删除线	可选	实体的原始价格，在UI中以删除线显示。	自由文本
标注	可选	如果可用，则标注以突出显示产品的促销、活动或更新。	自由文本建议文本大小：小于45个字符（过长的文本可能会显示省略号）
标注小字	可选	标注的小字文本。	自由文本建议文本大小：小于45个字符（过长的文本可能会显示省略号）
评分（可选） - 注意：所有评分均使用我们的标准星级评分系统显示。
评分 - 最大值	可选	评分量表的最大值。如果也提供了评分的当前值，则必须提供。	数字 >= 0.0
评分 - 当前值	可选	评分量表的当前值。如果也提供了评分的最大值，则必须提供。	数字 >= 0.0
评分 - 计数	可选	产品的评分计数。注意：如果您的应用控制如何向用户显示计数，则提供此字段。使用简洁的字符串。例如，如果计数为1,000,000，请考虑使用1M之类的缩写，以便计数在较小的显示尺寸上不会被截断。	字符串
评分 - 计数值	可选	产品的评分计数。注意：如果您不自己处理显示缩写逻辑，则提供此字段。如果同时存在Count和Count Value，则Count将显示给用户。	长
DisplayTimeWindow（可选） - 设置内容在界面上显示的时间窗口
开始时间戳	可选	内容应在界面上显示后的纪元时间戳。如果未设置，则内容有资格在界面上显示。	以毫秒为单位的纪元时间戳
结束时间戳	可选	内容不再在界面上显示后的纪元时间戳。如果未设置，则内容有资格在界面上显示。	以毫秒为单位的纪元时间戳

`StoreEntity`

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

属性	要求	描述	格式
海报图片	必需	必须提供至少一张图片。	有关指导，请参阅图片规范。
操作Uri	必需	应用中显示商店详细信息的页面的深层链接。注意：您可以使用深层链接进行归因。请参阅此常见问题解答	Uri
标题	可选	商店的名称。	自由文本建议文本大小：小于45个字符（过长的文本可能会显示省略号）
位置	可选	商店的位置。	自由文本建议文本大小：小于45个字符（过长的文本可能会显示省略号）
标注	可选	如果可用，则标注以突出显示商店的促销、活动或更新。	自由文本建议文本大小：小于45个字符（过长的文本可能会显示省略号）
标注小字	可选	标注的小字文本。	自由文本建议文本大小：小于45个字符（过长的文本可能会显示省略号）
描述	可选	商店的描述。	自由文本建议文本大小：小于90个字符（过长的文本可能会显示省略号）
注意：所有评分均使用我们的标准星级评分系统显示。
评分 - 最大值	可选	评分量表的最大值。如果也提供了评分的当前值，则必须提供。	数字 >= 0.0
评分 - 当前值	可选	评分量表的当前值。如果也提供了评分的最大值，则必须提供。	数字 >= 0.0
评分 - 计数	可选	商店的评分计数。注意：如果您的应用想要控制如何向用户显示此内容，则提供此字段。提供可以显示给用户的简洁字符串。例如，如果计数为1,000,000，请考虑使用1M之类的缩写，以便它在较小的显示尺寸上不会被截断。	字符串
评分 - 计数值	可选	商店的评分计数。注意：如果您不想自己处理显示缩写逻辑，则提供此字段。如果同时存在Count和Count Value，我们将使用Count显示给用户	长

`RecipeEntity`

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

属性	要求	描述	格式
海报图片	必需	必须提供至少一张图片。	有关指导，请参阅图片规范。
操作Uri	必需	应用中显示食谱详细信息的页面的深层链接。注意：您可以使用深层链接进行归因。请参阅此常见问题解答	Uri
标题	可选	食谱的名称。	自由文本建议文本大小：小于45个字符（过长的文本可能会显示省略号）
作者	可选	食谱的作者。	自由文本建议文本大小：小于45个字符（过长的文本可能会显示省略号）
烹饪/准备时间	可选	食谱的烹饪时间。	自由文本建议文本大小：小于45个字符（过长的文本可能会显示省略号）
标注	可选	如果可用，则标注以突出显示食谱的促销、活动或更新。	自由文本建议文本大小：小于45个字符（过长的文本可能会显示省略号）
类别	可选	食谱的类别。	自由文本建议文本大小：小于45个字符（过长的文本可能会显示省略号）
描述	可选	食谱的描述。	自由文本建议文本大小：小于90个字符（过长的文本可能会显示省略号）
注意：所有评分均使用我们的标准星级评分系统显示。
评分 - 最大值	可选	评分量表的最大值。如果也提供了评分的当前值，则必须提供。	数字 >= 0.0
评分 - 当前值	可选	评分量表的当前值。如果也提供了评分的最大值，则必须提供。	数字 >= 0.0
评分 - 计数	可选	食谱的评分计数。注意：如果您的应用想要控制如何向用户显示此内容，则提供此字段。提供可以显示给用户的简洁字符串。例如，如果计数为1,000,000，请考虑使用1M之类的缩写，以便它在较小的显示尺寸上不会被截断。	字符串
评分 - 计数值	可选	食谱的评分计数。注意：如果您不想自己处理显示缩写逻辑，则提供此字段。如果同时存在Count和Count Value，我们将使用Count显示给用户	长

`FoodShoppingCart`

属性	要求	描述	格式
操作Uri	必需	合作伙伴应用中购物车的深层链接。注意：您可以使用深层链接进行归因。请参阅此常见问题解答	Uri
商品数量	必需	购物车中商品的数量（不仅仅是产品的数量）。例如：如果购物车中有3个橙子和1个苹果，则此数字应为4。	整数 >= 1
标题	可选	购物车的标题（例如，您的购物车）。 *如果开发人员未提供标题，则您的购物车为默认值。*	自由文本建议文本大小：小于25个字符（过长的文本可能会显示省略号）
操作文本	可选	购物车上按钮的号召性用语文本（例如，您的购物袋）。 *如果开发人员未提供操作文本，则查看购物车为默认值。* 此属性在1.1.0及更高版本中受支持。	字符串
购物车图片	可选	购物车中每个产品的图片。最多可以按优先级顺序提供10张图片；实际显示的图片数量取决于设备的外形尺寸。	有关指导，请参阅图片规范。
商品标签	可选	购物清单上商品的标签列表。实际显示的标签数量取决于设备的外形尺寸。	自由文本标签列表建议文本大小：小于20个字符（过长的文本可能会显示省略号）
DisplayTimeWindow（可选） - 设置内容在界面上显示的时间窗口
开始时间戳	可选	内容应在界面上显示后的纪元时间戳。如果未设置，则内容有资格在界面上显示。	以毫秒为单位的纪元时间戳
结束时间戳	可选	内容不再在界面上显示后的纪元时间戳。如果未设置，则内容有资格在界面上显示。	以毫秒为单位的纪元时间戳

`FoodShoppingList`

属性	要求	描述	格式
操作Uri	必需	合作伙伴应用中购物清单的深层链接。注意：您可以使用深层链接进行归因。请参阅此常见问题解答	Uri
商品数量	必需	购物清单中商品的数量。	整数 >= 1
标题	可选	清单的标题（例如，您的杂货清单）。 *如果开发人员未提供标题，则购物清单为默认值。*	自由文本建议文本大小：小于25个字符（过长的文本可能会显示省略号）
商品标签	必需	购物清单上商品的标签列表。必须提供至少1个标签，最多可以按优先级顺序提供10个标签；实际显示的标签数量取决于设备的外形尺寸。	自由文本标签列表建议文本大小：小于20个字符（过长的文本可能会显示省略号）

`FoodReorderCluster`

属性	要求	描述	格式
操作Uri	必需	合作伙伴应用中重新订购的深层链接。注意：您可以使用深层链接进行归因。请参阅此常见问题解答	Uri
操作文本	可选	重新订购按钮上的号召性用语文本（例如，再次订购）。 *如果开发人员未提供操作文本，则重新订购为默认值。* 此属性在1.1.0及更高版本中受支持。	字符串
商品数量	必需	先前订单中商品的数量（不仅仅是产品的数量）。例如：如果先前订单中有3杯小咖啡和1个羊角面包，则此数字应为4。	整数 >= 1
标题	必需	重新订购项目的标题。	自由文本建议文本大小：小于40个字符（过长的文本可能会显示省略号）
商品标签	可选（如果未提供，则应提供海报图片）	先前订单的商品标签列表。最多可以按优先级顺序提供10个标签；实际显示的标签数量取决于设备的外形尺寸。	自由文本列表每个标签的建议文本大小：小于20个字符（过长的文本可能会显示省略号）
海报图片	可选（如果未提供，则应提供商品标签）	先前订单中商品的图片。最多可以按优先级顺序提供10张图片；实际显示的图片数量取决于设备的外形尺寸。	有关指导，请参阅图片规范。

图片规范

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

纵横比	最小像素	推荐像素
正方形（1x1）首选	300x300	1200x1200
横向（1.91x1）	600x314	1200x628
纵向（4x5）	480x600	960x1200

纵横比

最小像素

推荐像素

正方形（1x1）

首选

300x300

1200x1200

横向（1.91x1）

600x314

1200x628

纵向（4x5）

480x600

960x1200

文件格式

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

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

RecommendationCluster对象可以具有以下属性

属性	要求	描述
ProductEntity、StoreEntity或RecipeEntity列表	必需	构成此推荐集群的推荐的实体列表。单个集群中的实体必须属于同一类型。
标题	必需	推荐集群的标题（例如，感恩节菜单大促销）。建议文本大小：小于25个字符（过长的文本可能会显示省略号）
副标题	可选	推荐集群的副标题。
操作Uri	可选	合作伙伴应用中用户可以查看完整推荐列表的页面深度链接。注意：您可以使用深层链接进行归因。请参阅此常见问题解答

Kotlin

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

Java

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

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

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

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

`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 数据。
解析请求中的数据并将其存储到更新的特色集群中。

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

`publishFoodShoppingCart`

此 API 用于发布 FoodShoppingCart 对象。

Kotlin

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

Java

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

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

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

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

`publishFoodShoppingList`

此 API 用于发布 FoodShoppingList 对象。

Kotlin

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

Java

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

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

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

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

`publishReorderCluster`

此 API 用于发布 FoodReorderCluster 对象。

Kotlin

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

Java

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

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

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

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

`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 建议发布登录卡片。如果由于任何原因提供方无法发布登录卡片，我们建议使用状态代码NOT_PUBLISHED_REQUIRES_SIGN_IN调用updatePublishStatus API。

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

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

`deleteFoodShoppingCartCluster`

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

Kotlin

client.deleteFoodShoppingCartCluster()

Java

client.deleteFoodShoppingCartCluster();

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

`deleteFoodShoppingListCluster`

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

Kotlin

client.deleteFoodShoppingListCluster()

Java

client.deleteFoodShoppingListCluster();

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

`deleteReorderCluster`

此 API 用于删除 FoodReorderCluster 的内容。

Kotlin

client.deleteReorderCluster()

Java

client.deleteReorderCluster();

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

`deleteUserManagementCluster`

此 API 用于删除用户帐户管理集群的内容。

Kotlin

client.deleteUserManagementCluster()

Java

client.deleteUserManagementCluster();

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

`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：处理广播意图

除了通过作业进行发布内容 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 商店后，您的推荐、特色、购物车、购物清单和重新排序集群将发布并对用户可见。