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

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

本指南包含开发者合作伙伴集成其购物内容的说明,使用 Engage SDK 为此新界面区域和现有的 Google 界面(如娱乐空间)提供内容。

集成细节

术语

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

  • **推荐**集群显示来自单个开发者合作伙伴的个性化购物建议。这些推荐可以针对用户个性化,也可以泛化(例如,趋势商品)。根据您的需要,使用这些推荐来展示产品、活动、销售、促销、订阅等。

    您的推荐采用以下结构

    • **推荐集群:**包含来自同一开发者合作伙伴的一组推荐的 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 填充预计送达时间,因为在提供时会显示给用户。

准备工作

最低 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 中的包可见性

摘要

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

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

聚类类型 聚类限制 聚类中的最大实体限制
推荐聚类 最多 5 个 最多 25 个ShoppingEntity
特色聚类 最多 1 个 最多 10 个ShoppingEntity
购物车聚类 最多 1 个 最多 3 个ShoppingCart

仅对于每个商家拥有独立购物车的应用才预计有多个购物车。

购物清单聚类 最多 1 个 最多 1 个ShoppingListEntity
购物重新排序聚类 最多 1 个 最多 1 个ReorderEntity
购物订单跟踪聚类 最多 3 个 最多 3 个ShoppingOrderTrackingEntity

步骤 1:提供实体数据

SDK 已定义不同的实体来表示每种项目类型。以下实体受购物类别的支持

  1. ShoppingEntity
  2. ShoppingCart
  3. ShoppingList
  4. Reorder
  5. ShoppingOrderTracking

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

ShoppingEntity

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

ShoppingEntity
属性 要求 描述 格式
海报图片 必需 必须提供至少一张图片。 有关指南,请参阅图片规格
操作 Uri 必需

应用中显示有关实体详细信息的页面的深度链接。

注意:您可以使用深度链接进行归因。 请参阅此常见问题解答

Uri
标题 可选 实体的名称。

自由文本

推荐文本大小:低于 90 个字符(过长的文本可能会显示省略号)

价格 - 当前 有条件地必需

实体的当前价格。

如果提供了删除线价格,则必须提供。

自由文本
价格 - 删除线 可选 实体的原始价格,将在 UI 中以删除线显示。 自由文本
标注 可选 如果可用,则标注以突出显示实体的促销、活动或更新。

自由文本

推荐文本大小:低于 45 个字符(过长的文本可能会显示省略号)

标注详细说明 可选 标注的详细说明文本。

自由文本

推荐文本大小:低于 45 个字符(过长的文本可能会显示省略号)

评分(可选) - 注意:所有评分均使用我们的标准星级评分系统显示。
评分 - 最大值 可选

评分量表的最大值。

如果还提供了评分的当前值,则必须提供。

数字 >= 0.0
评分 - 当前值 可选

评分量表的当前值。

如果还提供了评分的最大值,则必须提供。

数字 >= 0.0
评分 - 计数 可选

实体评分的计数。

注意:如果您的应用控制如何向用户显示计数,则提供此字段。使用简洁的字符串。例如,如果计数为 1,000,000,请考虑使用 1M 等缩写,以便计数不会在较小的显示尺寸上被截断。

字符串
评分 - 计数值 可选

实体评分的计数。

注意:如果您不自己处理显示缩写逻辑,则提供此字段。如果 Count 和 Count Value 都存在,则 Count 会显示给用户。

长整型
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

文件格式

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 必需 操作的深层链接(即导航到应用登录页面)
图像 可选 - 如果未提供,则必须提供标题

卡片上显示的图像

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

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

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 用于删除用户帐户管理聚合的内容。

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

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

除了通过作业进行内容发布 API 调用外,还需要设置 BroadcastReceiver 以接收内容发布请求。

广播意图的主要目标是应用重新激活和强制数据同步。广播意图并非设计为非常频繁地发送。仅当 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> 标记静态声明实现。这允许应用程序在未运行时接收广播意图,并且还允许应用程序发布内容。
<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>

服务发送以下 意图

  • com.google.android.engage.action.PUBLISH_RECOMMENDATION 建议在收到此意图时启动 publishRecommendationClusters 调用。
  • com.google.android.engage.action.PUBLISH_FEATURED 建议在收到此意图时启动 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 常见问题解答 以获取常见问题解答。

联系方式

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

后续步骤

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

  • 发送电子邮件至 [email protected] 并附上您已集成的 APK,以便 Google 进行测试。
  • Google 会进行验证并在内部审查,以确保集成按预期工作。如果需要更改,Google 会与您联系并提供任何必要的详细信息。
  • 测试完成后且无需更改时,Google 会与您联系,通知您可以开始将更新的集成 APK 发布到 Play 商店。
  • Google 确认您已将更新的 APK 发布到 Play 商店后,您的推荐精选购物车购物清单重新排序群集购物订单跟踪群集可能会发布并对用户可见。