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

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

本指南包含开发者合作伙伴向 Engage 内容界面提供购物内容的说明。

集成详情

术语

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

推荐集群显示来自单个开发者合作伙伴的个性化购物建议。这些推荐可以根据用户进行个性化，也可以是通用性的（例如，热门商品）。您可以根据需要使用它们来展示产品、活动、促销、订阅等。

您的推荐采用以下结构
- 推荐集群：一个 UI 视图，其中包含来自同一开发者合作伙伴的一组推荐。
- ShoppingEntity：表示集群中单个项目的对象。
精选集群在一个 UI 分组中展示来自多个开发者合作伙伴的精选实体。将有一个单一的精选集群，它显示在 UI 顶部附近，其优先级高于所有推荐集群。每个开发者合作伙伴最多可以在精选集群中广播 10 个实体。
购物车集群在一个 UI 分组中显示来自许多开发者合作伙伴的购物车预览，提示用户完成他们未完成的购物车。只有一个购物车集群，它显示在 UI 顶部附近，其优先级高于所有推荐集群。每个开发者合作伙伴最多可以在购物车集群中广播 3 个 ShoppingCart 实例。

您的购物车采用以下结构
- 购物车集群：一个 UI 视图，其中包含来自许多开发者合作伙伴的一组购物车预览。
- ShoppingCart：表示单个开发者合作伙伴的购物车预览的对象，将在购物车集群中显示。ShoppingCart 必须显示购物车中商品的总数，并且还可以包含用户购物车中某些商品的图片。
购物清单集群在一个 UI 分组中显示来自多个开发者合作伙伴的购物清单预览，提示用户返回相应应用更新和完成其清单。只有一个购物清单集群。
重新订购集群在一个 UI 分组中显示来自多个开发者合作伙伴的先前订单预览，提示用户重新订购。只有一个重新订购集群。
- 重新订购集群必须显示用户先前订单中商品的总数，并且还必须包含以下其中一项
  - 用户先前订单中 X 个商品的图片。
  - 用户先前订单中 X 个商品的标签。
购物订单跟踪集群在一个 UI 分组中显示来自许多开发者合作伙伴的待处理或最近完成的购物订单预览，允许用户跟踪其订单。

只有一个 ShoppingOrderTracking 集群，它显示在 UI 顶部附近，其优先级高于所有推荐集群。每个开发者合作伙伴都可以在购物订单跟踪集群中广播多个 ShoppingOrderTrackingEntity 项目。
- 您的 ShoppingOrderTrackingCluster 采用以下结构
  - ShoppingOrderTracking 集群：一个 UI 视图，其中包含来自许多开发者合作伙伴的一组订单跟踪预览
  - ShoppingOrderTrackingEntity：表示单个开发者合作伙伴的购物订单跟踪预览的对象，将在购物订单跟踪集群中显示。ShoppingOrderTrackingEntity 必须显示订单状态和订单时间。我们强烈建议为 ShoppingOrderTrackingEntity 填充预计送达时间，因为提供后会向用户显示该时间。
  注意：如果一个订单已拆分为多个发货，请提供多个 ShoppingOrderTrackingEntity 对象。

准备工作

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

如需了解更多信息，请参阅 Android 11 中的软件包可见性。

摘要

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

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

集群类型	集群限制	集群中的最大实体限制
推荐集群	最多 7 个	最多 50 个 `ShoppingEntity`
精选集群	最多 1 个	最多 20 个 `ShoppingEntity`
购物车集群	最多 1 个	最多 3 个 `ShoppingCart` 仅适用于每个商家单独设置购物车的应用。
购物清单集群	最多 1 个	最多 1 个 `ShoppingListEntity`
购物重新订购集群	最多 1 个	最多 1 个 `ReorderEntity`
购物订单跟踪集群	最多 3 个	最多 3 个 `ShoppingOrderTrackingEntity`

第 1 步：提供实体数据

SDK 定义了不同的实体来表示每种商品类型。购物类别支持以下实体：

ShoppingEntity
ShoppingCart
ShoppingList
Reorder
ShoppingOrderTracking

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

`ShoppingEntity`

ShoppingEntity 对象表示开发者合作伙伴想要发布的产品、促销、交易、订阅或活动。

`ShoppingEntity`

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

`ShoppingCart`

属性	要求	说明	格式
操作 URI	必需	指向合作伙伴应用中购物车的深层链接。注意：您可以将深层链接用于归因。请参阅此常见问题解答	URI
商品数量	必需	购物车中的商品数量（不仅仅是产品数量）。例如：如果购物车中有 3 件相同衬衫和 1 顶帽子，则此数字应为 4。	整数 >= 1
操作文本	可选	购物车上按钮的号召性操作文本（例如，您的购物袋）。 *如果开发者未提供操作文本，则默认显示查看购物车。* 此属性在版本 1.1.0 及更高版本中受支持。	字符串
标题	可选	购物车标题（例如，您的购物袋）。 *如果开发者未提供标题，则默认显示您的购物车。* *如果开发者合作伙伴为每个商家发布单独的购物车，请在标题中包含商家名称。*	自由文本建议文本长度：25 个字符以下（过长的文本可能会显示省略号）
购物车图片	可选	购物车中每个产品的图片。最多可按优先级顺序提供 10 张图片；实际显示的图片数量取决于设备外形尺寸。	有关指南，请参阅图片规格。
商品标签	可选	购物清单上商品的标签列表。实际显示的标签数量取决于设备外形尺寸。	自由文本标签列表建议文本长度：20 个字符以下（过长的文本可能会显示省略号）
上次用户互动时间戳	可选	自纪元以来经过的毫秒数，标识用户上次与购物车互动的时间。这将由为每个商家发布单独购物车的开发者合作伙伴作为输入传递，并可能用于排名。	毫秒为单位的纪元时间戳
DisplayTimeWindow（可选）- 设置内容在界面上显示的时间窗口
开始时间戳	可选	内容应在界面上显示后的纪元时间戳。如果未设置，则内容有资格在界面上显示。	毫秒为单位的纪元时间戳
结束时间戳	可选	内容不再在界面上显示后的纪元时间戳。如果未设置，则内容有资格在界面上显示。	毫秒为单位的纪元时间戳

`ShoppingList`

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

`ShoppingReorderCluster`

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

`ShoppingOrderTrackingCluster`

属性	要求	说明	格式
标题	必需	被跟踪包裹/商品的简短标题或跟踪号。	自由文本建议文本长度：50 个字符（过长的文本将显示省略号）
订单类型	必需	被跟踪包裹/商品的简短标题或跟踪号。	枚举：IN_STORE_PICKUP（店内取货）、SAME_DAY_DELIVERY（当日送达）、MULTI_DAY_DELIVERY（多日送达）
状态	必需	订单的当前状态。例如：“运行延迟”、“运输中”、“已延迟”、“已发货”、“已送达”、“缺货”、“订单准备就绪”	自由文本建议文本长度：25 个字符（过长的文本将显示省略号）
订单时间	必需	下单时以毫秒为单位的纪元时间戳。如果不存在预计送达时间窗口，将显示订单时间	毫秒为单位的纪元时间戳
操作 URI	必需	指向合作伙伴应用中订单跟踪的深层链接。	URI
OrderDeliveryTimeWindow（可选）- 为正在跟踪的订单设置一个时间窗口，从下单时间到预计/实际送达时间。
OrderDeliveryTimeWindow - 开始时间	可选	订单将送达或准备取货时/之后以毫秒为单位的纪元时间戳。	毫秒为单位的纪元时间戳
OrderDeliveryTimeWindow - 结束时间	可选	订单将送达或准备取货时/之前以毫秒为单位的纪元时间戳。	毫秒为单位的纪元时间戳
海报图片	可选	订单中一件商品/产品的图片。建议纵横比为 1:1	有关指南，请参阅图片规格。
商品数量	可选	订单中的商品数量。	整数 >= 1
说明	可选	描述订单中商品的单段文本。注意：描述或副标题列表将显示给用户，两者不会同时显示。	自由文本建议文本长度：180 个字符
副标题列表	可选	最多 3 个副标题，每个副标题为单行文本。注意：描述或副标题列表将显示给用户，两者不会同时显示。	自由文本建议每个副标题的文本长度：最多 50 个字符
订单价值 - 当前价格	可选	订单的当前价值。	自由文本
订单号	可选	可用于唯一标识订单的订单号/ID。	自由文本建议文本长度：最多 25 个字符
跟踪号	可选	如果订单需要配送，则为订单/包裹配送的跟踪号。	自由文本建议文本长度：最多 25 个字符

图片规格

图片资产的必需规格如下所示

纵横比	最小像素	推荐像素
正方形 (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），并定期或按事件调度（例如，每次用户打开应用或用户刚将商品添加到购物车时）。

AppEngageShoppingClient 负责发布购物集群。

客户端公开以下 API 以发布集群

isServiceAvailable
publishRecommendationClusters
publishFeaturedCluster
publishShoppingCart
publishShoppingCarts
publishShoppingList
publishShoppingReorderCluster
publishShoppingOrderTrackingCluster
publishUserAccountManagementRequest
updatePublishStatus
deleteRecommendationsClusters
deleteFeaturedCluster
deleteShoppingCartCluster
deleteShoppingListCluster
deleteShoppingReorderCluster
deleteShoppingOrderTrackingCluster
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 对象可以具有以下属性

属性	要求	说明
ShoppingEntity 列表	必需	构成此推荐集群推荐内容的 ShoppingEntity 对象列表。
标题	必需	推荐集群的标题。建议文本长度：25 个字符以下（过长的文本可能会显示省略号）
副标题	可选	推荐集群的副标题。
操作 URI	可选	指向合作伙伴应用中用户可以查看完整推荐列表页面的深层链接。注意：您可以将深层链接用于归因。请参阅此常见问题解答

Kotlin

client.publishRecommendationClusters(
            PublishRecommendationClustersRequest.Builder()
                .addRecommendationCluster(
                    RecommendationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .setTitle("Black Friday Deals")
                        .build())
                .build())

Java

client.publishRecommendationClusters(
            new PublishRecommendationClustersRequest.Builder()
                .addRecommendationCluster(
                    new RecommendationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .setTitle("Black Friday Deals")
                        .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 数据将被移除。
请求中的数据将被解析并存储到更新的精选集群中。

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

`publishShoppingCart`

此 API 用于发布 ShoppingCartCluster 对象。

Kotlin

client.publishShoppingCart(
            PublishShoppingCartRequest.Builder()
                .setShoppingCart(
                    ShoppingCart.Builder()
                        ...
                        .build())
                .build())

Java

client.publishShoppingCart(
            new PublishShoppingCartRequest.Builder()
                .setShoppingCart(
                    new ShoppingCart.Builder()
                        ...
                        .build())
                .build())

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

来自开发者合作伙伴的现有 ShoppingCart 数据将被移除。
请求中的数据将被解析并存储到更新的购物车集群中。

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

`publishShoppingCarts`

此 API 用于发布多个 ShoppingCart 对象。这适用于为每个商家发布单独购物车的开发者合作伙伴。使用此 API 时，请在标题中包含商家名称。

Kotlin

client.publishShoppingCarts(
            PublishShoppingCartClustersRequest.Builder()
                .addShoppingCart(
                    ShoppingCart.Builder()
                        ...
                        .build())
                .build())

Java

client.publishShoppingCarts(
            new PublishShoppingCartClustersRequest.Builder()
                .addShoppingCart(
                    new ShoppingCart.Builder()
                        ...
                        .build())
                .build())

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

来自开发者合作伙伴的现有 ShoppingCart 数据将被移除。
请求中的数据将被解析并存储到更新的购物车集群中。

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

`publishShoppingList`

此 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 数据将被移除。
请求中的数据将被解析并存储到更新的购物清单集群中。

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

`publishShoppingReorderCluster`

此 API 用于发布 ShoppingReorderCluster 对象。

Kotlin

client.publishShoppingReorderCluster(
            PublishShoppingReorderClusterRequest.Builder()
                .setReorderCluster(
                    ShoppingReorderCluster.Builder()
                        ...
                        .build())
                .build())

Java

client.publishShoppingReorderCluster(
            new PublishShoppingReorderClusterRequest.Builder()
                .setReorderCluster(
                    new ShoppingReorderCluster.Builder()
                        ...
                        .build())
                .build());

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

来自开发者合作伙伴的现有 ShoppingReorderCluster 数据将被移除。
请求中的数据将被解析并存储到更新的重新订购集群中。

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

`publishShoppingOrderTrackingCluster`

此 API 用于发布 ShoppingOrderTrackingCluster 对象。

Kotlin

client.publishShoppingOrderTrackingCluster(
            PublishShoppingOrderTrackingClusterRequest.Builder()
                .setShoppingOrderTrackingCluster(
                    ShoppingOrderTrackingCluster.Builder()
                        ...
                        .build())
                .build())

Java

client.publishShoppingOrderTrackingCluster(
            new PublishShoppingOrderTrackingClusterRequest.Builder()
                .setShoppingOrderTrackingCluster(
                    new ShoppingOrderTrackingCluster.Builder()
                        ...
                        .build())
                .build());

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

来自开发者合作伙伴的现有 ShoppingOrderTrackingCluster 数据将被移除。
请求中的数据将被解析并存储到更新的购物订单跟踪集群中。

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

`publishUserAccountManagementRequest`

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

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

属性	要求	说明
操作 URI	必需	操作的深层链接（即导航到应用登录页面）
图片	可选 - 如果未提供，则必须提供标题	卡片上显示的图片分辨率为 1264x712 的 16x9 纵横比图片
标题	可选 - 如果未提供，则必须提供图片	卡片标题
操作文本	可选	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();

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

`deleteShoppingCartCluster`

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

Kotlin

client.deleteShoppingCartCluster()

Java

client.deleteShoppingCartCluster();

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

`deleteShoppingListCluster`

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

Kotlin

client.deleteShoppingListCluster()

Java

client.deleteShoppingListCluster();

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

`deleteShoppingReorderCluster`

此 API 用于删除购物重新订购集群的内容。

Kotlin

client.deleteShoppingReorderCluster()

Java

client.deleteShoppingReorderCluster();

当服务收到请求时，它会从购物重新订购集群中移除现有数据。如果发生错误，整个请求将被拒绝，并保留现有状态。

`deleteShoppingOrderTrackingCluster`

此 API 用于删除购物订单跟踪集群的内容。

Kotlin

client.deleteShoppingOrderTrackingCluster()

Java

client.deleteShoppingOrderTrackingCluster();

当服务收到请求时，它会从购物订单跟踪集群中移除现有数据。如果发生错误，整个请求将被拒绝，并保留现有状态。

`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 的任务结果，以便可以采取后续操作来恢复并重新提交成功的任务。

Kotlin

client.publishRecommendationClusters(
        PublishRecommendationClustersRequest.Builder()
          .addRecommendationCluster(..)
          .build())
      .addOnCompleteListener { task ->
        if (task.isSuccessful) {
          // do something
        } else {
          val exception = task.exception
          if (exception is AppEngageException) {
            @AppEngageErrorCode val errorCode = exception.errorCode
            if (errorCode == AppEngageErrorCode.SERVICE_NOT_FOUND) {
              // do something
            }
          }
        }
      }

Java

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 类的一个实例。这使得仍在内存中运行的应用能够进行通信。

Kotlin

class AppEngageBroadcastReceiver : 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_SHOPPING_CART broadcast
  // is received
  // Trigger shopping list cluster publish when PUBLISH_SHOPPING_LIST broadcast
  // is received
  // Trigger reorder cluster publish when PUBLISH_REORDER_CLUSTER broadcast is
  // received
  // Trigger shopping order tracking cluster publish when
  // PUBLISH_SHOPPING_ORDER_TRACKING_CLUSTER broadcast is received
}

fun registerBroadcastReceivers(context: Context){
  var  context = context
  context = context.applicationContext

// Register Recommendation Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(Intents.ACTION_PUBLISH_RECOMMENDATION))

// Register Featured Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(Intents.ACTION_PUBLISH_FEATURED))

// Register Shopping Cart Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(Intents.ACTION_PUBLISH_SHOPPING_CART))

// Register Shopping List Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(Intents.ACTION_PUBLISH_SHOPPING_LIST))

// Register Reorder Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(Intents.ACTION_PUBLISH_REORDER_CLUSTER))

// Register Shopping Order Tracking Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(Intents.ACTION_PUBLISH_SHOPPING_ORDER_TRACKING_CLUSTER))
}

Java

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_SHOPPING_CART broadcast is
// received

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

// Trigger reorder cluster publish when PUBLISH_REORDER_CLUSTER broadcast is
// received

// Trigger reorder cluster publish when PUBLISH_SHOPPING_ORDER_TRACKING_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.shopping.service.Intents.ACTION_PUBLISH_SHOPPING_CART));

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

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

// Register Shopping Order Tracking Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
new IntentFilter(com.google.android.engage.shopping.service.Intents.ACTION_PUBLISH_SHOPPING_ORDER_TRACKING_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.shopping.PUBLISH_SHOPPING_CART" />
      </intent-filter>
      <intent-filter>
         <action android:name="com.google.android.engage.action.shopping.PUBLISH_SHOPPING_LIST" />
      </intent-filter>
      <intent-filter>
         <action android:name="com.google.android.engage.action.shopping.PUBLISH_REORDER_CLUSTER" />
      </intent-filter>
      <intent-filter>
         <action android:name="com.google.android.engage.action.shopping.PUBLISH_SHOPPING_ORDER_TRACKING_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.shopping.PUBLISH_SHOPPING_CART 收到此 Intent 时，建议启动 publishShoppingCart 调用。
com.google.android.engage.action.shopping.PUBLISH_SHOPPING_LIST 收到此 Intent 时，建议启动 publishShoppingList 调用。
com.google.android.engage.action.shopping.PUBLISH_REORDER_CLUSTER 收到此 Intent 时，建议启动 publishReorderCluster 调用。
com.google.android.engage.action.shopping.PUBLISH_SHOPPING_ORDER_TRACKING_CLUSTER 收到此 Intent 时，建议启动 publishShoppingOrderTrackingCluster 调用。

集成工作流

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

常见问题解答

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

联系我们

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

后续步骤

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

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

Engage SDK 购物：第三方技术集成说明 使用收藏功能保持井井有条 根据您的偏好保存和分类内容。

集成详情

术语

准备工作

摘要

第 1 步：提供实体数据

ShoppingEntity

ShoppingEntity

ShoppingCart

ShoppingList

ShoppingReorderCluster

ShoppingOrderTrackingCluster

图片规格

第 2 步：提供集群数据

isServiceAvailable

Kotlin

Java

publishRecommendationClusters

Kotlin

Java

publishFeaturedCluster

Kotlin

Java

publishShoppingCart

Kotlin

Java

publishShoppingCarts

Kotlin

Java

publishShoppingList

Kotlin

Java

publishShoppingReorderCluster

Kotlin

Java

publishShoppingOrderTrackingCluster

Kotlin

Java

publishUserAccountManagementRequest

Kotlin

Java

updatePublishStatus

Kotlin

Java

deleteRecommendationClusters

Kotlin

Java

deleteFeaturedCluster

Kotlin

Java

deleteShoppingCartCluster

Kotlin

Java

deleteShoppingListCluster

Kotlin

Java

deleteShoppingReorderCluster

Kotlin

Java

deleteShoppingOrderTrackingCluster

Kotlin

Java

deleteUserManagementCluster

Kotlin

Java

deleteClusters

Kotlin

Java

错误处理

Kotlin

Java

第 3 步：处理广播 Intent

Kotlin

Java

集成工作流

常见问题解答

联系我们

后续步骤

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

`ShoppingEntity`

`ShoppingEntity`

`ShoppingCart`

`ShoppingList`

`ShoppingReorderCluster`

`ShoppingOrderTrackingCluster`

`isServiceAvailable`

`publishRecommendationClusters`

`publishFeaturedCluster`

`publishShoppingCart`

`publishShoppingCarts`

`publishShoppingList`

`publishShoppingReorderCluster`

`publishShoppingOrderTrackingCluster`

`publishUserAccountManagementRequest`

`updatePublishStatus`

`deleteRecommendationClusters`

`deleteFeaturedCluster`

`deleteShoppingCartCluster`

`deleteShoppingListCluster`

`deleteShoppingReorderCluster`

`deleteShoppingOrderTrackingCluster`

`deleteUserManagementCluster`

`deleteClusters`