Google Play Cubes

文档基于 engage sdk v1.4.0

Google Play Cubes 是什么？

Cubes 是 Google 开发的一个新的功能。

• CUBES 以 Play 商店的小组件形式存在，需用户手动添加后才会展现，桌面以 5 个 ICON 的信息条样式展现，点击后可打开 CUBES；（用户手动添加小组件方式：手动长按 Play 商店，添加小组件；桌面缩放，添加小组件）
• 顶部拆分为 5 个分类（Category apps）：Watch、Games、Read、Listen、Shopping，当前仅 Watch、Games 有信息，后面 3 个分类为空白，分类内展示顺序按最后使用时间排序（空白是因为设备当前未安装该分类下支持的 APP）
• 每个分类下面可以发布不同种类的集群，如 Shopping 分类（具体见 #Cluster types），可分为：
  • Recommendation cluster：推荐集群。可用来展示推荐的商品、活动、销售、促销或订阅信息；可根据用户是否登录来做个性化还是一般化的推荐；可以展示多个；Google 建议一天更新一次就行
  • Featured cluster：精选集群。用于展示精选的 ShoppingEntity，Google 建议放促销、重要事件、会员相关等；可根据用户是否登录来做个性化还是一般化的推荐；只有一个；
  • Shopping Cart cluster：购物车集群。用于展示购物车商品，购物车商品总数量；需要登录态；只有一个；
  • Shopping List cluster：购物清单集群。用于展示购物清单；需要登录态；只有一个；
  • Reorder cluster：再订购集群。用于展示上一次购物订单，引导用户再次下单；需要登录态；只有一个；
  • Order tracking cluster：可用于物流追踪，新增的 api，还没有文档；需要登录态；只有一个；
• 一些 Cubes 功能的截图 Source: Google News Telegram

Google Play Engage Shopping for app 交互流程

Engage 开发者集成流程

Engage 开发者集成工作流程  |  Android 开发者  |  Android Developers

Shared files

Verification app 验证应用程序

engage_verify_app_dev_03052024.apk

该 APP 的包名为：com.google.android.engage.verifyapp，用于验证 APP 发布集群测试

查看 Engage SDK：

public final class zzac {
	@VisibleForTesting  
	static final Intent zza = (new Intent("com.google.android.engage.BIND_APP_ENGAGE_SERVICE")).setPackage("com.android.vending");  
	static final Intent zzb = (new Intent("com.google.android.engage.BIND_APP_ENGAGE_SERVICE")).setPackage("com.google.android.engage.verifyapp");
}

• com.android.vending 是 Google Play Store APP 的包名；Google Play app
• com.google.android.engage.verifyapp 是 Google 提供给我们验证集群发布状态的 APP 的包名；verifyapp app

如果同时存在 2 个 App，优先级：verifyapp > Google Play

内容发布指南

#Engage SDK Cluster publishing guidelines （Engage SDK 集群发布指南 ）

1、使用 SDK 调试模式进行开发

在 build.gradle 文件中添加 Engage SDK，并遵循相应的类别特定集成指南来完成集成。

dependencies {
    // Make sure you also include the repository in your project's build.gradle file.
    implementation 'com.google.android.engage:engage-core:1.4.0'
}

不同类别的，按照不同类别的集成文档集成，如 Shopping：#Shopping 类别集成指南

2、安装验证应用程序

验证应用程序（engage_verify_app_dev_03052024.apk）是一个 Android 应用程序，开发人员可以使用它来验证集成是否正常工作。该应用程序包括帮助开发人员验证数据和广播意图的功能。

3、验证数据在验证应用程序中是否可见

验证数据在验证应用程序中是否可见

• 输入正在发布数据的开发包的名称。

• 验证集群中的所有实体均已发布。

• 验证实体中的所有字段均已发布。对于该行中的每个项目，开发人员可以单击海报图像来验证意图。

4、验证广播意图流

要验证广播意图，请单击 UI 顶部的按钮来触发发送广播的逻辑。

完成步骤 1 到 4 后，您就完成了集成测试。

5、调试完成后，您必须更新清单文件中的元数据

<application>
  <meta-data
	android:name="com.google.android.engage.service.ENV"
	android:value="PRODUCTION"></meta-data>
</application>

警告：在将应用程序发布到 Play 商店之前，请确保元数据已更新。

6、Send Google the release-ready APK

将您的可发布 APK 文件的副本作为电子邮件附件发送至 engage-developers@google.com 。 Google 将验证整个流程是否按我们的预期运行。完成后，应用程序就可以提交到生产环境进行发布。

警告：确保 APK 的包名称与发布到 Play 商店的包名称匹配。

7、Publish the APK to the Play Store

获得批准后，将 APK 发布到 Play 商店。发布后，将发布的版本号发送电子邮件至 engage-developers@google.com 。谷歌将采取后续措施予以回应。

Shopping 类别集成指南

Engage SDK Shopping：第三方技术集成说明  |  Android 开发者  |  Android Developers

Engage SDK Shopping 是 Google 给合作伙伴在其 APP 外展示其购物相关内容，在一块新的 Surface 区域或者 Google Surface 如 Entertainment 区域。

Cluster types

Shopping 下面有 6 种 cluster type：

Recommendation, Featured, Shopping Cart, Shopping List and Reorder

V 1.4.0 新增了 Order Track

Recommendation cluster 推荐集群（多个）

Recommendation clusters 展示来自各个开发者合作伙伴提供的个性化的 shopping 建议。这些推荐可以针对用户进行个性化或一般化（如：趋势项目）。使用它们来显示你认为合适的产品、活动、销售、促销或订阅。

你的 Recommendations 采用下面的结构：

• Recommendation Cluster：包含来自同一开发合作伙伴的一组推荐的 UI 视图
• ShoppingEntity：代表集群中单个项目的对象

Featured cluster 特色集群（单个）

Featured cluster 展示了来自多个开发合作伙伴的精选购物实体 (ShoppingEntity)，以一个 UI 分组的形式呈现。在 UI 的顶部附近，有一个单独的Featured cluster ，优先于所有Recommendation cluster。每个开发合作伙伴都可以在Featured cluster 中发布一个购物实体 (ShoppingEntity)。

Shopping Cart cluster 购物车集群（单个）

Shopping Cart cluster 在一个 UI 分组中展示多个开发者合作伙伴的购物车商品一撇，促使用户完成未完成的购物车。只有一个 Shopping Cart cluster，在 UI 的顶部附近显示，优先于所有的 Recommendation clusters。每个开发者合作伙伴在只能在 Shopping Cart cluster 广播一个 ShoppingCart。

你的 Shopping Cart 采用下面的结构：

• Shopping Cart Cluster: 包含来自许多开发合作伙伴的一组购物车预览的 UI 视图。
• ShoppingCart: 一个表示单个开发者合作伙伴购物车预览的对象，将在 Shopping Cart cluster 中显示。ShoppingCart 必须显示购物车中物品的总数量，并且可能还包括用户购物车中某些物品的图片。

Shopping List cluster 购物清单集群（单个）

Shopping List cluster 展示了来自多个开发者合作伙伴的购物清单一撇，将用户引导返回 APP 去更新和完成他们的清单。只有一个 Shopping List cluster。

Reorder cluster 购物重新订购集群

Reorder cluster 展示了来自多个开发者合作伙伴的上一笔订单的一撇，以一个 UI 界面分组的方式提示用户再去下单。只有一个 Record cluster。

Reorder cluster 必须显示用户先前订单中的所有商品数量，并且还必须包含以下内容之一：

1. 用户先前订单中 X 件商品的图片
2. 用户先前订单中 X 件商品的标签

Order Track 物流追踪 v1.4.0新增的

展示优先级

先展示 ShoppingCart，然后 Featured，然后 Recommendations

Pre-work 前期工作

• 最低 API 级别：19
• 添加依赖库

dependencies {
    // Make sure you also include that repository in your project's build.gradle file.
    implementation 'com.google.android.engage:engage-core:1.4.0'
}

For more information, see Package visibility in Android 11.

Summary

前提条件：绑定了 SDK 提供的 Service？

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

步骤一：提供 Entity 数据

SDK 定义了不同的 Entity 来表示每种类型，Shopping 类别支持以下 Entity：

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

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

ShoppingEntity

ShoppingEntity 对象代表开发者合作伙伴希望发布的 product, promotion, deal, subscription, or event。

Rating（可选，注意：我们使用标准的星级评分系统显示所有评级）

DisplayTimeWindow（可选，设置要在表面上显示的内容的时间窗口）

ShoppingCart

• 在 shoppingCart 里传入图片或者 label 的时候就会显示效果 1
• 有图片或者文字的话就会显示效果 2

Play Engage Verify App 效果：

Google Play Cubes 上效果：

• Image 的图片必须是 https，http 的会加载不出来

DisplayTimeWindow（可选，设置要在表面上显示的内容的时间窗口）

ShoppingList

ShoppingReorderCluster

Image specifications

下面列出了图像资源所需的规格：

• File formats 文件格式： PNG, JPG, static GIF, WebP
• Maximum file size 最大文件大小： 5120 KB
• Additional recommendations 其他建议：
  • Image safe area 图像安全区域：将重要内容放在图像中心 80% 的位置。
  • 使用透明背景，以便图像可以在深色和浅色主题设置中正确显示。

ShoppingOrderTrackingCluster

v 1.4.0 文档还未更新

Sign In Card

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

appEngagePublishClient.publishUserAccountManagementRequest(
            PublishUserAccountManagementRequest.Builder()
                .setSignInCardEntity(SIGN_IN_CARD_ENTITY)
                .build());

注意：用户登录后，开发者必须通过调用 deleteUserManagementCluster() API 删除卡片。

步骤二：提供 Cluster 数据 publish 发布

建议在后台执行内容发布作业 (publish)（例如，使用 WorkManager）并定期或按事件安排（例如，每次用户打开应用程序或用户刚刚向应用程序添加内容时）他们的购物车）。

AppEngageShoppingClient 负责 publish shopping clusters。

以下 API 公开用于在客户端中发布集群：

• isServiceAvailable
• publishRecommendationClusters
• publishFeaturedCluster
• publishShoppingCart
• publishShoppingList
• publishShoppingReorderCluster
• publishUserAccountManagementRequest
• updatePublishStatus
• deleteRecommendationsClusters
• deleteFeaturedCluster
• deleteShoppingCartCluster
• deleteShoppingListCluster
• deleteShoppingReorderCluster
• deleteUserManagementCluster
• deleteClusters

isServiceAvailable

该 API 用于检查服务是否可集成以及内容是否可以在设备上呈现。

client.isServiceAvailable.addOnCompleteListener { task ->
    if (task.isSuccessful) {
        // Handle IPC call success
        if(task.result) {
          // Service is available on the device, proceed with content publish
          // calls.
        } else {
          // Service is not available, no further action is needed.
        }
    } else {
      // The IPC call itself fails, proceed with error handling logic here,
      // such as retry.
    }
}

注意：我们强烈建议保持定期作业运行，以检查该服务是否在以后的某个时间点可用。该服务的可用性可能会随着 Android 版本升级、应用程序升级、安装和卸载而变化。
通过确保以一定时间间隔进行定期作业检查，一旦服务可用，就可以发布数据。其他 publishXXX API 也是一样。

publishRecommendationClusters

该 API 用于发布 RecommendationCluster 对象，可能是一个列表。

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

重要提示：发布 API 是更新插入 API; 它替换了现有内容。不要随后调用 delete 和 publish API 来替换内容，因为发布 API 本质上是这样做的。

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

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

• 所有现有的 Recommendation Cluster 数据都将被移除。
• 来自请求的数据将被解析并存储在新的 Recommendation Cluster 中。

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

publishFeaturedCluster

此 API 用于发布 FeaturedCluster 对象。

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

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

• 将删除来自开发人员合作伙伴的现有 FeaturedCluster 数据。
• 来自请求的数据将被解析并存储在更新的 Featured Cluster 中

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

注意：

• Shopping featured 的 Entity 是 ShoppingEntity
• ShoppingEntity 的 price 和 rating 同时存在，优先展示 rating
• 如果通过 FeaturedCluster.Builder.addEntity 添加了多个 Entity，只有第 1 个生效
• deeplink 只需要设置每个 Entity 的 setActionLinkUri，最外层不需要设置 deeplink
• 目前 featured 只会显示一个，API 可以 add 多个是允许当有一个过期了之后我们可以自动选择下一个有效的

效果：

示例：

public final class GetFeaturedCluster {
    private static final String ACTION_LINK_URI = "xxx://applink/ad_landing_recommend?test=1&mallcode=b&page_type=B";
    @RequiresApi(api = Build.VERSION_CODES.O)
    public static FeaturedCluster getFeaturedCluster() {
        FeaturedCluster.Builder clusterBuilder = new FeaturedCluster.Builder();

        Image image = new Image.Builder()
                .setImageUri(Uri.parse("https://img1.baidu.com/it/u=2127952341,1978494606&fm=253&fmt=auto&app=138&f=PNG?w=600&h=477"))
                .setImageHeightInPixel(314)
                .setImageWidthInPixel(600)
                .build();

        for (int i = 0; i < 5; i++) {
            Price price = new Price.Builder()
                    .setCurrentPrice("$" + (100.00 + i))
                    .setStrikethroughPrice("$" + (200.00 + i))
                    .build();

            Rating rating = new Rating.Builder()
                    .setCurrentValue(1.1 + i)
                    .setMaxValue(10.0)
                    .build();

            ShoppingEntity shoppingEntity = new ShoppingEntity.Builder()
                    .addPosterImage(image)
                    .setActionLinkUri(Uri.parse(ACTION_LINK_URI))
                    .setTitle("Goods_" + i + "_" + MyRecommendationCluster.INSTANCE.getCurrentTimestampAndFormat())
                    .setPrice(price)
                    .setCallout("Callout_" + i)
                    .setRating(rating)
                    .build();
            clusterBuilder.addEntity(shoppingEntity);
        }
        return clusterBuilder.build();
    }

    private GetFeaturedCluster() {
    }
}

publishShoppingCart

此 API 用于发布 ShoppingCartCluster 对象。

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

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

• 将删除来自开发人员合作伙伴的现有 ShoppingCart 数据。
• 来自请求的数据将被解析并存储在更新的 Shopping Cart Cluster 中。

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

效果 1：没有 image 和 label

效果 2：有 image

publishShoppingList

此 API 用于发布 FoodShoppingList 对象。

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

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

• 将删除来自开发人员合作伙伴的现有 FoodShoppingList 数据。
• 来自请求的数据将被解析并存储在更新的  Shopping List Cluster 中。

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

publishShoppingReorderCluster

此 API 用于发布 ShoppingReorderCluster 对象。

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

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

• 将删除来自开发人员合作伙伴的现有 ShoppingReorderCluster 数据。
• 来自请求的数据将被解析并存储在更新的 Reorder Cluster 中。

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

publishShoppingOrderTrackingCluster

截止到 sdk v1.4.0，Shopping order tracking 这个是一个新开发的功能

Shopping reorder 说的是我买了一个东西可能之后还会再买一次，比如说日用品，order tracking 是物流追踪

object GetShoppingOrderTrackingCluster {  
  
    private const val ACTION_LINK_URI = "mysheinlink://applink/order_detail"  
  
    fun getShoppingOrderTrackingCluster(): ShoppingOrderTrackingCluster {  
  
        val orderType = 10;  
  
        val builder = with(ShoppingOrderTrackingCluster.Builder()) {  
            // 必选  
            setTitle("order tracking title")  
            setStatus("订单已发货")  
            setShoppingOrderType(orderType)  
            setTrackingId("order trackingId:shin3121sdf489djsij")  
            setOrderTime(System.currentTimeMillis())  
            val readyTimeWindow = OrderReadyTimeWindow.Builder()  
                .setStartTimestampMillis(System.currentTimeMillis() - 10000L)  
                .setEndTimestampMillis(System.currentTimeMillis() + 10000000L)  
                .build()  
            setOrderReadyTimeWindow(readyTimeWindow)  
  
            // 可选  
            setOrderDescription("my order orderDescription")  
            setActionLinkUri(ACTION_LINK_URI.toUri())  
        }  
        return builder.build()  
    }  
}

val request = PublishShoppingOrderTrackingClusterRequest.Builder()  .setShoppingOrderTrackingCluster(GetShoppingOrderTrackingCluster.getShoppingOrderTrackingCluster())  
    .build()
client.publishShoppingOrderTrackingCluster(request)

publishUserAccountManagementRequest（其他类别可以共用）

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

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

var SIGN_IN_CARD_ENTITY =
  SignInCardEntity.Builder()
	  .addPosterImage(
		  Image.Builder()
			  .setImageUri(Uri.parse("http://www.x.com/image.png"))
			  .setImageHeightInPixel(500)
			  .setImageWidthInPixel(500)
			  .build())
	  .setActionText("Sign In")
	  .setActionUri(Uri.parse("http://xx.com/signin"))
	  .build()

client.publishUserAccountManagementRequest(
	PublishUserAccountManagementRequest.Builder()
		.setSignInCardEntity(SIGN_IN_CARD_ENTITY)
		.build());

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

• 将删除来自开发人员合作伙伴的现有 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

如果由于用户未登录而导致内容未发布，我们建议发布登录卡。如果由于任何原因提供商无法发布登录卡，那么我们建议使用状态代码 NOT_PUBLISHED_REQUIRES_SIGN_IN 调用 updatePublishStatus API

client.updatePublishStatus(
   PublishStatusRequest.Builder()
     .setStatusCode(AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SIGN_IN)
     .build())

deleteXXX

删除相关发布的 cluster

重要提示：仅当没有要发布的内容时才应调用删除 API。不要随后调用删除和发布 API 来替换内容，因为发布 API 本身就会执行此操作。在使用删除 API 之前，请联系 engage-developers@google.com 。

• deleteRecommendationsClusters
• deleteFeaturedCluster
• deleteShoppingCartCluster
• deleteShoppingListCluster
• deleteShoppingReorderCluster
• deleteUserManagementCluster 删除用户登录卡片，在登录后移除
• deleteClusters

client.deleteClusters(
    DeleteClustersRequest.Builder()
      .addClusterType(ClusterType.TYPE_FEATURED)
      .addClusterType(ClusterType.TYPE_RECOMMENDATION)
      // ...
      .build())

Error handling 错误处理

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
		}
	  }
	}
  }

步骤三：处理 broadcast intents

除了通过作业发出发布内容 API 调用外，还需要设置 BroadcastReceiver 来接收内容发布请求

目的：广播 intent 主要用于重新激活应用和强制同步数据。不应过于频繁地发送广播 intent。仅在 Engage Service 确定内容可能已过时（例如，内容是一周前的）的情况下，广播 intent 才会触发。这样一来，开发者将更加确信，即使应用长时间未执行，用户也能够获得新鲜的内容体验。

必须通过以下两种方式设置 BroadcastReceiver：

• 使用 Context.registerReceiver() 动态注册 BroadcastReceiver 类的实例。这样一来，仍位于内存中的应用即可进行通信。

 private fun registerBroadcastReceiver(context: Context) {  
    // Register Recommendation Cluster Publish Intent  
    ActivityCompat.registerReceiver(  
        context,  
        mReceiver,  
        IntentFilter(Intents.ACTION_PUBLISH_RECOMMENDATION),  
        ContextCompat.RECEIVER_EXPORTED  
    )  
  
    // Register Featured Cluster Publish Intent  
    ActivityCompat.registerReceiver(  
        context,  
        mReceiver,  
        IntentFilter(Intents.ACTION_PUBLISH_FEATURED),  
        ContextCompat.RECEIVER_EXPORTED  
    )  
  
    // Register Shopping Cart Cluster Publish Intent  
    ActivityCompat.registerReceiver(  
        context,  
        mReceiver,  
        IntentFilter(ShoppingIntents.ACTION_PUBLISH_SHOPPING_CART),  
        ContextCompat.RECEIVER_EXPORTED  
    )  
  
    // Register Shopping List Cluster Publish Intent  
    ActivityCompat.registerReceiver(  
        context,  
        mReceiver,  
        IntentFilter(ShoppingIntents.ACTION_PUBLISH_SHOPPING_LIST),  
        ContextCompat.RECEIVER_EXPORTED  
    )  
  
    // Register Reorder Cluster Publish Intent  
    ActivityCompat.registerReceiver(  
        context,  
        mReceiver,  
        IntentFilter(ShoppingIntents.ACTION_PUBLISH_REORDER_CLUSTER),  
        ContextCompat.RECEIVER_EXPORTED  
    )  
    // Register Reorder Cluster Publish Intent  
    ActivityCompat.registerReceiver(  
        context,  
        mReceiver,  
        IntentFilter(ShoppingIntents.ACTION_PUBLISH_SHOPPING_ORDER_TRACKING_CLUSTER),  
        ContextCompat.RECEIVER_EXPORTED  
    )  
}

• 在 AndroidManifest.xml 文件中使用 <receiver> 标记静态声明实现。这样一来，应用便可以在未运行时接收广播 intent，并且应用也可以发布内容。

<receiver
	android:name=".AppEngageBroadcastReceiver"
	android:enabled="true"
	android:exported="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>

该服务会发送以下 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

其他类别 SDK 集成

• Watch: Engage SDK Watch：第三方技术集成说明  |  Android 开发者  |  Android Developers
• Listen: Engage SDK Listen：第三方技术集成说明  |  Android 开发者  |  Android Developers
• Read: Engage SDK Read：第三方技术集成说明  |  Android 开发者  |  Android Developers
• Food: Engage SDK Food：第三方技术集成说明  |  Android 开发者  |  Android Developers
• Social: Engage SDK Social：第三方技术集成说明  |  Android 开发者  |  Android Developers

集群 publish 指南

Engage SDK Cluster 发布指南  |  Android 开发者  |  Android Developers

本指南包含一组集群发布指南，开发人员在与 Engage SDK 集成时可以使用这些指南。

Recommendation clusters 推荐集群 s

Cluster Title

我们建议提供一个独特且相关的集群标题，让用户能够更深入地了解集群的内容。

以下是一些基于内容的良好集群标题的示例：

Shopping-related clusters 购物相关集群

• Lightning Deals 秒杀优惠
• Weekly must buys 每周必买
• Related to your purchase of Pixel Buds 与您购买 Pixel Buds 相关
• Women’s rain boots 女式雨鞋

Clusters of books on health 健康书籍簇

• Health, mind & body 健康、精神和身体
• Recommended for you in Health 为您推荐健康类
• Best-sellers in Fitness 健身类畅销书

Cluster Content 集群内容

发布推荐集群时，开发者必须考虑用户是否登录到开发者的应用程序。

已登录

如果用户登录到开发者应用程序，我们建议发布个性化或用户生成的内容集群。由于个性化和用户生成的内容与用户更相关，因此他们更有动力从 Google 界面访问开发者应用程序。

• Personalized recommendations can be published. 可以发布个性化推荐。以下是个性化推荐的一些示例：
  • Top picks based on the user's watch history. 基于用户观看历史记录的首选。
  • Books similar to books that are in the user's read history. 与用户阅读历史中的书籍相似的书籍。
  • Songs by the user's favorite artists. 用户最喜欢的艺术家的歌曲。
• User-generated content libraries can be published. 可以发布用户生成的内容库。以下是用户生成的内容库的一些示例：
  • The user's watchlist from the developer app. 来自开发者应用程序的用户监视列表。
  • A self-reported list of the user's favorite artists from the developer app. 来自开发者应用程序的用户最喜欢的艺术家的自我报告列表。

未登录

如果用户未登录开发者应用，我们仍然建议发布集群，以便鼓励用户从 Google Surface 访问开发者应用。

• Non-personalized recommendation clusters should be published. 应发布非个性化推荐簇。以下是一些非个性化推荐的示例：
  • Top 10 books read this year. 今年阅读的前十本书。
  • Newly released movies. 新上映的电影。
  • Trending podcasts. 热门播客。
• Publish a sign-in card. 发布签到卡。
  • 为了鼓励用户登录开发者应用，开发者可以选择在发布非个性化推荐集群的同时发布登录卡。请查看以下部分，了解有关如何发布登录卡的更多详细信息 Sign In Card.。

Continuation clusters

已登录

示例：

• Continue Watching from where the user left off. 从用户停止的地方继续观看。
• Continue Reading from where the user left off. 从用户上次停下的地方继续阅读。

未登录

Continuation clusters 主要面向登录用户；但是，如果您的应用程序支持访客会话，您还可以为注销用户发布 Continuation clusters。

User Management Cluster 用户管理集群

User Management Cluster 的主要目的是促使用户在提供商应用程序上执行某些操作。登录操作将用户引导至应用程序的登录页面，以便应用程序可以发布内容（或提供更个性化的内容）

具体见： #Sign In Card

WorkManager for cluster publishing

推荐使用 WorkManager 来发布集群，因为它是后台工作的推荐解决方案，执行必须是机会性的和有保证的。

• WorkManager 会尽快执行您的后台工作。
• WorkManager 处理在各种条件下开始工作的逻辑，即使用户离开您的应用程序也是如此。

当用户离开应用程序时，我们建议启动一个后台作业来发布延续集群和推荐集群。处理此逻辑的一个好地方是 Activity.onStop() ，当用户离开应用程序时调用它。

我们建议使用 PeriodicWorkRequest 安排一个每 24 小时发布一次集群的重复作业。通过使用 CANCEL_AND_REENQUEUE 策略来触发工作，开发人员可以确保 WorkManager 在用户每次离开应用程序时发送更新的数据。这有助于防止用户看到过时的数据。

// Define the PublishClusters Worker requiring input
public class PublishClusters extends Worker {

   public PublishClusters(Context appContext, WorkerParameters workerParams) {
       super(appContext, workerParams);
   }

   @NonNull
   @Override
   public Result doWork() {
       // publish clusters
   }
   ...
}

public static void schedulePublishClusters(Context appContext) {
// Create a PeriodicWorkRequest to schedule a recurring job to update
// clusters at a regular interval
PeriodicWorkRequest publishClustersEntertainmentSpace =
// Define the time for the periodic job
       new PeriodicWorkRequest.Builder(PublishClusters.class, 24, TimeUnit.HOURS)
// Set up a tag for the worker.
// Tags are Unique identifier, which can be used to identify that work
// later in order to cancel the work or observe its progress.
          .addTag("Publish Clusters to Entertainment Space")
          .build();

// Trigger Periodic Job, this will ensure that the periodic job is triggered
// only once since we have defined a uniqueWorkName
WorkManager.getInstance(appContext).enqueueUniquePeriodicWork(
// uniqueWorkName
     "publishClustersEntertainmentSpace",
// If a work with the uniqueWorkName is already running, it will cancel the
// existing running jobs and replace it with the new instance.
// ExistingPeriodicWorkPolicy#CANCEL_AND_REENQUEUE
     ExistingPeriodicWorkPolicy.CANCEL_AND_REENQUEUE,
// Recurring Work Request
publishClustersEntertainmentSpace);

}

处理广播 intent

除了通过作业发出发布内容 API 调用外，还需要设置 BroadcastReceiver 来接收内容发布请求。

但是，开发者必须格外小心，不要只依赖于广播，因为广播只有在特定情况（主要是指重新激活应用和强制同步数据的情况）下才会触发。**只有在 Engage Service 确定内容可能已过时的情况下，广播才会触发。**这样一来，即使用户已很长时间没有打开应用，系统也能更有效地保证用户获得新鲜的内容体验。

必须通过以下两种方式设置 BroadcastReceiver：

• 使用 Context.registerReceiver() 动态注册 BroadcastReceiver 类的实例。这样一来，仍位于内存中的应用即可进行通信。
• 在 AndroidManifest.xml 文件中使用 <receiver> 标记对实现进行静态声明。这样一来，应用便可以在未运行时接收广播 intent，并且也可以发布内容。

Engage SDK Cluster 发布指南  |  Android Developers

Engage SDK FAQ

publish FAQs

谁管理内容发布工作？

应用程序开发人员管理内容发布作业并向 Engage Service 发送请求。通过这种方式，开发者合作伙伴可以更好地控制何时以及如何向用户发布内容。这可以避免过于频繁地唤醒合作伙伴应用程序来发布内容。

开发者是否需要发布所有集群类型？

虽然从技术上讲，开发人员可以自由地仅发布一个集群，但我们强烈建议包括更多集群。否则，开发者就会错失提高内容互动度的机会。我们强烈建议发布每个垂直领域的所有集群类型。

在应用程序运行时，开发人员合作伙伴应该多久通过 WorkManager 发布数据？

这由开发合作伙伴决定。

Google 建议每天发布一次或两次一般 recommendation 内容，并对 shopping cart、reorder 和其他 continuation 内容使用事件驱动的方法（例如，启动工作线程作为用户将商品添加到购物车或用户中途停止电影）。

• Recommendation cluster，一天发布 1 次或 1 次
• Shopping cart 、 Reorder 和 Continuation 使用事件驱动时发布，如加入购物车

开发者应该什么时候调用删除 API？

仅当没有要发布的内容时才应调用删除 API。后续不要调用删除、发布接口替换内容；发布 API 会自动删除较早的内容。

Broadcast Intent FAQs

为什么 Android 应用开发者需要注册广播意图？

为了向用户提供新鲜内容，您应该在用户可能不经常使用应用程序的情况下使用广播意图来触发数据同步。

广播在每次 Cutes 页面启动会执行？

不允许后台执行

在注册广播意图时，您可能会遇到以下错误：

Background execution not allowed: receiving Intent
{ act=com.google.android.engage.action.PUBLISH_RECOMMENDATION .. }

您需要动态注册广播接收器。

class AppEngageBroadcastReceiver extends BroadcastReceiver {
	// Trigger recommendation cluster publish when PUBLISH_RECOMMENDATION 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));
	//...
}

疑问

Engage SDK 提供的广播 Action，能否在清单文件注册，是否受 Android 8.0 限制

建议的是同时注册，manifest 静态注册和 application context 动态 都注册一下

官方提供的 samples，两种方式都注册了，需要注意 receiver 的 onReceive 会执行两次

如何在 Google Play Store 上测试？对 Play 商店版本有什么需求吗？

测试的话，如果想在 Play store 测试的话，需要在 verify app 验证通过之后然后发 apk 到我们这里做一下初步的内部校验，然后我们会把你们的 account 加到我们的白名单里就可以了

最新版本的 Play 商店就好，最好是用海外版本的手机

校验需要个 2~3 天

APP 卸载后集群是否还在？

通过在 verify app 测试，APP 卸载后，集群发布状态就被移除了；

在 Google Play 上，如果 App 被卸载了，Google Play Cubes 也不会存在了

actionUri 能否用 onelink？

可以的，deeplink 和 onelink 都可以

登录后，SignInCardEntity 要移除吗？

登录后，通过 deleteUserManagementCluster 把 Sign in Card 移除掉

退出登录后，已发布的集群处理

退出登录后，涉及到需要登录才能发布的集群，应当 delete 掉；不需要登录的更新下数据就好了

Cubes 入口显示条件和命令

Cubes 入口显示条件

1. 美国 VPN
2. 不要挂抓包代理，如 Charles
3. Google Play 账号白名单
4. Google Play 最新的版本

Google Play Cubes 提供 Widget 有入口，

adb 命令启动 Cubes：
也可以用命令：adb shell am start -n com.android.vending/com.google.android.finsky.rubiks.cubes.activity.CubesActivity

访问不了 Cubes，一般是网络问题：

首次启动

接口调用时机，提供哪些数据，数据什么时候更新

接口调用时机？
在调用集群发布后，就需要调用接口；或者之前就要调用接口，把要发布集群所需要的数据准备好

提供哪些数据？

不同的集群提供的数据不一样，具体看上面不同集群所需要的数据

数据什么时候更新？

• 不同集群不一样
• 推荐的集群，数据不需要依赖登录，变更不大的数据，一天更新一次即可
• 像 Shopping Cart 集群，强依赖用户登录、加入移除购物车的操作的，在登录、加车操作后就需要更新数据

v1.5.1 sdk 问题

• v1.5.1 的 Shopping cart setActionText 还是不生效，设置后还是默认的 View cart。

前端同学把这个 feature 给漏掉了，所以现在默认都是 view cart。我们会在之后的版本里更新上

常见错误

发布的卡片加载不出来

Error while loading the image http://img.ltwebstatic.com/images3_pi/2024/02/20/dd/17083979518bfa684b0ee5d2264e922efd9dd0ce98_thumbnail_405x552_thumbnail_1200x1200.jpg 
java.net.UnknownServiceException: CLEARTEXT communication to img.ltwebstatic.com not permitted by network security policy

原因：Image 用了 http 协议

解决：用 https 协议

The input calling package name com.xxx is not installed by Play Store

问题描述： 通过系统 APK 安装器，发布 Cubes 时报错了：


或者是下面的报错：

SERVICE_CALL_INVALID_ARGUMENT - The request contains invalid data (e.g. more than allowed number of clusters (5)

通过 adb install 安装的没有报错：

分析： Google Play Cubes 对 Production 的包的限制，必须是 Google Play 下载安装的包，通过三方浏览器下载的包不能发布 Cubes。

解决： 未发布上线到 Google Play 前，只能通过 adb install 这种方式才能发布内容到 Cubes；上线后应该直接从 Google Play 安装就能发布了，通过扫码下载安装是看不到发布的内容

Ref

• Engage SDK  |  Android 开发者  |  Android Developers
• 企微文档 Google Play CUBES 调研
• 企微文档 Google Play CUBES