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

通过在用户所在之处触达他们来提升应用互动度。集成 Engage SDK 可将个性化推荐和延续内容直接传达给用户，覆盖多个设备端界面，例如合集、娱乐空间和 Play 商店。此集成将平均 APK 大小增加不到 50 KB（压缩后），并且大多数应用只需要大约一周的开发时间。请访问我们的商业网站了解更多信息。

本指南包含开发者合作伙伴将食品内容（食物订购、食品或餐厅评论和发现、膳食订阅、食谱）交付给 Engage 内容界面的说明。

集成详情

术语

此集成包含以下五种集群类型：推荐、精选、食品购物车、食品购物清单和重新订购。

推荐集群显示来自单个开发者合作伙伴的个性化食品相关建议。这些推荐可以是针对用户的个性化推荐，也可以是通用推荐（例如，新品促销）。您可以根据需要使用它们来展示食谱、商店、菜肴、杂货等。
- 推荐集群可以由 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'
}

摘要

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

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

集群类型	集群限制	集群中的最大实体限制
推荐集群	最多 7 个	最多 50 个（`ProductEntity`、`RecipeEntity` 或 `StoreEntity`）
精选集群	最多 1 个	最多 20 个（`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 等缩写，以免在较小的显示尺寸上被截断。	字符串
评分 - 计数值	可选	产品的评分计数。注意：如果您不自行处理显示缩写逻辑，请提供此字段。如果“计数”和“计数值”都存在，则向用户显示“计数”。	长整型
DisplayTimeWindow（可选）- 为内容在界面上显示设置时间窗口
开始时间戳	可选	内容应在界面上显示后的 epoch 时间戳。如果未设置，内容有资格在界面上显示。	以毫秒为单位的 epoch 时间戳
结束时间戳	可选	内容在此 epoch 时间戳之后将不再显示在界面上。如果未设置，内容有资格在界面上显示。	以毫秒为单位的 epoch 时间戳

`StoreEntity`

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

属性	要求	说明	格式
海报图片	必需	必须提供至少一张图片。	请参阅图片规格了解指南。
操作 URI	必需	指向应用中显示商店详细信息的页面的深层链接。注意：您可以使用深层链接进行归因。请参阅此常见问题	Uri
标题	可选	商店名称。	自由文本建议文字大小：45 个字符以内（过长的文字可能会显示省略号）
位置	可选	商店位置。	自由文本建议文字大小：45 个字符以内（过长的文字可能会显示省略号）
标注	可选	如果有促销、活动或商店更新，请使用标注突出显示。	自由文本建议文字大小：45 个字符以内（过长的文字可能会显示省略号）
标注小字	可选	标注的细则文字。	自由文本建议文字大小：45 个字符以内（过长的文字可能会显示省略号）
说明	可选	商店描述。	自由文本建议文字大小：90 个字符以内（过长的文字可能会显示省略号）
类别	可选	商店类别，在餐饮场所的语境中，可以是“法国菜”、“新美式菜”、“拉面”、“高级餐厅”等菜系。	自由文本建议文字大小：45 个字符以内（过长的文字可能会显示省略号）
注意：所有评分均使用我们的标准星级评分系统显示。
评分 - 最大值	可选	评分标尺的最大值。如果也提供了评分的当前值，则必须提供。	数字 >= 0.0
评分 - 当前值	可选	评分标尺的当前值。如果也提供了评分的最大值，则必须提供。	数字 >= 0.0
评分 - 计数	可选	商店的评分计数。注意：如果您的应用希望控制此项如何向用户显示，请提供此字段。提供可向用户显示的简洁字符串。例如，如果计数为 1,000,000，请考虑使用 1M 等缩写，以免在较小的显示尺寸上被截断。	字符串
评分 - 计数值	可选	商店的评分计数。注意：如果您不想自行处理显示缩写逻辑，请提供此字段。如果“计数”和“计数值”都存在，我们将使用“计数”向用户显示。	长整型

`RecipeEntity`

RecipeEntity 对象表示开发者合作伙伴希望发布的食谱项目。

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

`FoodShoppingCart`

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

`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
标题	可选 - 如果未提供，则必须提供图片	卡片上的标题
操作文本	可选	号召性用语上显示的文本（即登录）
副标题	可选	卡片上的可选副标题

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

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> 标签静态声明一个实现。这允许应用在未运行时接收广播 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.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>

服务将发送以下 Intent：

com.google.android.engage.action.PUBLISH_RECOMMENDATION 建议在收到此 Intent 时开始调用 publishRecommendationClusters。
com.google.android.engage.action.PUBLISH_FEATURED 建议在收到此 Intent 时开始调用 publishFeaturedCluster。
com.google.android.engage.action.food.PUBLISH_FOOD_SHOPPING_CART 建议在收到此 Intent 时开始调用 publishFoodShoppingCart。
com.google.android.engage.action.food.PUBLISH_FOOD_SHOPPING_LIST 建议在收到此 Intent 时开始调用 publishFoodShoppingList。
com.google.android.engage.action.food.PUBLISH_REORDER_CLUSTER 建议在收到此 Intent 时开始调用 publishReorderCluster。

集成工作流程

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

常见问题

请参阅Engage SDK 常见问题了解常见问题。

联系方式

如果在集成过程中有任何问题，请联系engage-developers@google.com。我们的团队将尽快回复。

后续步骤

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

向engage-developers@google.com发送电子邮件，并附上您已集成且准备好由 Google 测试的 APK。
Google 将进行内部验证和审查，以确保集成按预期工作。如果需要更改，Google 将与您联系并提供所有必要的详细信息。
测试完成后，如果无需更改，Google 将联系您，通知您可以开始将更新和集成的 APK 发布到 Play 商店。
在 Google 确认您的更新 APK 已发布到 Play 商店后，您的推荐、精选、购物车、购物清单和重新订购集群将发布并对用户可见。

Engage SDK 食品：第三方技术集成说明 使用合集保持井然有序 根据您的偏好保存和分类内容。

集成详情

术语

前期准备

摘要

第 1 步：提供实体数据

ProductEntity

StoreEntity

RecipeEntity

FoodShoppingCart

FoodShoppingList

FoodReorderCluster

图片规格

第 2 步：提供集群数据

isServiceAvailable

Kotlin

Java

publishRecommendationClusters

Kotlin

Java

publishFeaturedCluster

Kotlin

Java

publishFoodShoppingCart

Kotlin

Java

publishFoodShoppingList

Kotlin

Java

publishReorderCluster

Kotlin

Java

publishUserAccountManagementRequest

Kotlin

Java

updatePublishStatus

Kotlin

Java

deleteRecommendationClusters

Kotlin

Java

deleteFeaturedCluster

Kotlin

Java

deleteFoodShoppingCartCluster

Kotlin

Java

deleteFoodShoppingListCluster

Kotlin

Java

deleteReorderCluster

Kotlin

Java

deleteUserManagementCluster

Kotlin

Java

deleteClusters

Kotlin

Java

错误处理

第 3 步：处理广播 Intent

集成工作流程

常见问题

联系方式

后续步骤

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

`ProductEntity`

`StoreEntity`

`RecipeEntity`

`FoodShoppingCart`

`FoodShoppingList`

`FoodReorderCluster`

`isServiceAvailable`

`publishRecommendationClusters`

`publishFeaturedCluster`

`publishFoodShoppingCart`

`publishFoodShoppingList`

`publishReorderCluster`

`publishUserAccountManagementRequest`

`updatePublishStatus`

`deleteRecommendationClusters`

`deleteFeaturedCluster`

`deleteFoodShoppingCartCluster`

`deleteFoodShoppingListCluster`

`deleteReorderCluster`

`deleteUserManagementCluster`

`deleteClusters`