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

Google 正在构建一个设备上的界面，该界面按垂直方向组织用户的应用，并为个性化应用内容使用和发现提供新的沉浸式体验。此全屏体验为开发者合作伙伴提供了一个机会，让他们可以在其应用之外的专用渠道中展示其最佳的丰富内容。本指南包含开发者合作伙伴集成其旅行和活动内容的说明，使用 Engage SDK 来填充此新的界面区域。

集成详情

术语

此集成包括以下三种集群类型：**推荐**、**特色**和**续集**。

• **推荐**集群显示来自单个开发者合作伙伴的个性化旅行和活动建议。这些建议可以针对用户个性化或泛化（例如，趋势项目）。使用它们来显示文章、活动、住宿或兴趣点的推荐。

  • 推荐集群可以由ArticleEntity、EventEntity、LodgingEntity、PointOfInterestEntity或StoreEntity列表组成，但不能混合使用不同实体类型。

  您的推荐采用以下结构

  • **推荐集群：**包含来自同一开发者合作伙伴的一组推荐的 UI 视图。

  • **实体：**表示集群中单个项目的对象。此集成提供了一些实体，这些实体将使用推荐集群显示

    • **ArticleEntity**：ArticleEntity 代表与旅行和活动相关的基于文本内容的推荐。它可用于文章、博文、营销内容、新闻片段等。

      

    • **EventEntity**：EventEntity 代表未来发生的事件。事件开始时间是需要传达给用户的重要信息。

      

    • **LodgingEntity**：LodgingEntity 代表住宿，例如酒店、公寓、度假屋，用于短期和长期租赁。

      

    • **StoreEntity**：StoreEntity 代表商店、餐厅、咖啡馆等。它突出显示内容，其中餐饮场所或商店是需要传达给用户的关键信息。

      

    • **PointOfInterestEntity**：PointOfInterestEntity 代表一个兴趣点，例如加油站、活动场所、主题公园、博物馆、旅游景点、远足路线等。它突出显示内容，其中位置是需要传达给用户的关键信息。它不应用于住宿、商店或餐饮场所。

      

• **延续**集群在一个单一的UI分组中显示了来自多个开发者合作伙伴的用户最近参与的内容。每个开发者合作伙伴最多可以在延续集群中广播10个实体。

  您的延续内容可以采用以下结构

  • **ArticleEntity**：ArticleEntity表示对与旅行和活动相关内容的推荐。此实体可用于表示未完成的新闻文章或用户希望从上次离开的地方继续消费的其他内容。例如：关于旅行目的地或活动的新闻片段、博文片段。

    

  • **RestaurantReservationEntity**：RestaurantReservationEntity表示餐厅或咖啡馆的预订，并帮助用户跟踪即将到来的或正在进行的餐厅预订。

    

  • **EventReservationEntity**：EventReservationEntity表示活动的预订，并帮助用户跟踪即将到来的或正在进行的活动预订。活动可能包括但不限于以下内容

    • 体育赛事，例如足球比赛的预订
    • 游戏赛事，例如电子竞技的预订
    • 娱乐活动，例如电影院、音乐会、剧院、签售会的预订
    • 旅行或兴趣点的预订，例如导游、博物馆门票
    • 社交/研讨会/会议预订
    • 教育/培训课程预订

    

  • **LodgingReservationEntity**：LodgingEntityReservation表示旅行住宿的预订，并帮助用户跟踪即将到来的或正在进行的酒店或度假租赁预订。

    

  • **TransportationReservationEntity**：TransportationReservationEntity表示任何交通方式的预订，并帮助用户跟踪即将到来的或正在进行的航班、渡轮、火车、巴士、网约车或邮轮的预订。

    

  • **VehicleRentalReservationEntity**：VehicleRentalReservationEntity表示车辆租赁预订，并帮助用户跟踪即将到来的或正在进行的车辆租赁预订。

    

• **特色**集群是一个UI视图，在一个UI分组中展示了来自多个开发者合作伙伴的选定的英雄GenericFeaturedEntity。只有一个特色集群，它显示在UI的顶部附近，优先于所有推荐集群。每个开发者合作伙伴允许在特色中广播一个受支持类型的实体，特色集群中包含来自多个应用开发者的多个实体（可能是不同类型）。

  • **GenericFeaturedEntity**：GenericFeaturedEntity与推荐项目不同，特色项目应用于开发者的单个顶级内容，并应代表对用户最有趣和最相关的单个最重要内容。

    

预备工作

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

总结

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

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

步骤 1：提供实体数据

SDK已定义不同的实体来表示每种项目类型。我们支持以下旅行和活动类别的实体

1. GenericFeaturedEntity
2. ArticleEntity
3. EventEntity
4. LodgingEntity
5. StoreEntity
6. PointOfInterestEntity
7. RestaurantReservationEntity
8. EventReservationEntity
9. LodgingReservationEntity
10. TransportationReservationEntity
11. VehicleRentalReservationEntity

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

GenericFeaturedEntity

ArticleEntity

EventEntity

LodgingEntity

StoreEntity

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

PointOfInterestEntity

RestaurantReservationEntity

EventReservationEntity

LodgingReservationEntity

TransportationReservationEntity

VehicleRentalReservationEntity

图片规格

此表列出了图像资源的必需规格

图像需要托管在公共 CDN 上，以便 Google 可以访问它们。

文件格式

PNG、JPG、静态 GIF、WebP

最大文件大小

5120 KB

其他建议

• 图像安全区域：将重要内容放在图像中心 80% 的区域。
• 使用透明背景，以便图像可以在深色和浅色主题设置中正确显示。

内容类别

内容类别允许应用发布属于多个类别的内容。这将内容与一些预定义的类别映射，即

• TYPE_EDUCATION
• TYPE_SPORTS
• TYPE_MOVIES_AND_TV_SHOWS
• TYPE_BOOKS
• TYPE_AUDIOBOOKS
• TYPE_MUSIC
• TYPE_DIGITAL_GAMES
• TYPE_TRAVEL_AND_LOCAL
• TYPE_HOME_AND_AUTO
• TYPE_BUSINESS
• TYPE_NEWS
• TYPE_FOOD_AND_DRINK
• TYPE_SHOPPING
• TYPE_HEALTH_AND_FITENESS
• TYPE_MEDICAL
• TYPE_PARENTING
• TYPE_DATING

图像需要托管在公共 CDN 上，以便 Google 可以访问它们。

使用内容类别的指南

1. 某些实体（如 ArticleEntity 和 GenericFeaturedEntity）可以使用任何内容类别。对于其他实体（如 EventEntity、EventReservationEntity、PointOfInterestEntity），只有这些类别的一部分是适用的。在填充列表之前，请查看实体类型适用的类别列表。

2. 对于某些内容类别，请使用特定的实体类型，而不是组合使用通用实体和 ContentCategory

   • TYPE_MOVIES_AND_TV_SHOWS - 在使用通用实体之前，请查看 观看集成指南 中的实体。
   • TYPE_BOOKS - 在使用通用实体之前，请查看 EbookEntity。
   • TYPE_AUDIOBOOKS - 在使用通用实体之前，请查看 AudiobookEntity。
   • TYPE_SHOPPING - 在使用通用实体之前，请查看 ShoppingEntity。
   • TYPE_FOOD_AND_DRINK - 在使用通用实体之前，请查看 食品集成指南 中的实体。

3. ContentCategory 字段是可选的，如果内容不属于前面提到的任何类别，则应将其留空。

4. 如果提供了多个内容类别，请按与内容的相关性顺序提供，并将最相关的内容类别放在列表的第一个位置。

步骤 2：提供集群数据

建议在后台执行内容发布作业（例如，使用 WorkManager）并定期或基于事件进行调度（例如，每次用户打开应用或用户将商品添加到购物车时）。

AppEngagePublishClient 负责发布集群。

客户端中以下 API 用于发布集群

• isServiceAvailable
• publishRecommendationClusters
• publishFeaturedCluster
• publishContinuationCluster
• publishUserAccountManagementRequest
• updatePublishStatus
• deleteRecommendationsClusters
• deleteFeaturedCluster
• deleteContinuationCluster
• 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.
    }
}

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

client.publishRecommendationClusters(
      PublishRecommendationClustersRequest.Builder()
        .addRecommendationCluster(
          RecommendationCluster.Builder()
            .addEntity(entity1)
            .addEntity(entity2)
            .setTitle("Top Picks For You")
            .build()
        )
        .build()
    )

client.publishRecommendationClusters(
            new PublishRecommendationClustersRequest.Builder()
                .addRecommendationCluster(
                    new RecommendationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .setTitle("Top Picks For You")
                        .build())
                .build());

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

• 删除开发合作伙伴的现有 RecommendationCluster 数据。
• 解析请求中的数据并将其存储在更新的推荐集群中。

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

publishFeaturedCluster

此 API 用于发布 FeaturedCluster 对象列表。

client.publishFeaturedCluster(
    PublishFeaturedClusterRequest.Builder()
      .setFeaturedCluster(
        FeaturedCluster.Builder()
          .addEntity(entity1)
          .addEntity(entity2)
          .build())
      .build())

client.publishFeaturedCluster(
            new PublishFeaturedClustersRequest.Builder()
                .addFeaturedCluster(
                    new FeaturedCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .build())
                .build());

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

• 开发者合作伙伴提供的现有 FeaturedCluster 数据将被移除。
• 请求中的数据将被解析并存储到更新后的特色聚合 (Featured Cluster) 中。

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

publishContinuationCluster

此 API 用于发布 ContinuationCluster 对象。

client.publishContinuationCluster(
    PublishContinuationClusterRequest.Builder()
      .setContinuationCluster(
        ContinuationCluster.Builder()
          .addEntity(entity1)
          .addEntity(entity2)
          .build())
      .build())

client.publishContinuationCluster(
            new PublishContinuationClusterRequest.Builder()
                .setContinuationCluster(
                    new ContinuationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .build())
                .build());

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

• 开发者合作伙伴提供的现有 ContinuationCluster 数据将被移除。
• 请求中的数据将被解析并存储到更新后的续集聚合 (Continuation Cluster) 中。

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

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

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。

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

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

deleteRecommendationClusters

此 API 用于删除推荐聚合 (Recommendation Clusters) 的内容。

client.deleteRecommendationClusters()

client.deleteRecommendationClusters();

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

deleteFeaturedCluster

此 API 用于删除特色聚合 (Featured Cluster) 的内容。

client.deleteFeaturedCluster()

client.deleteFeaturedCluster();

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

deleteContinuationCluster

此 API 用于删除续集聚合 (Continuation Cluster) 的内容。

client.deleteContinuationCluster()

client.deleteContinuationCluster();

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

deleteUserManagementCluster

此 API 用于删除用户账户管理聚合 (UserAccountManagement Cluster) 的内容。

client.deleteUserManagementCluster()

client.deleteUserManagementCluster();

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

deleteClusters

此 API 用于删除给定聚合类型的內容。

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

client.deleteClusters(
            new DeleteClustersRequest.Builder()
                .addClusterType(ClusterType.TYPE_CONTINUATION)
                .addClusterType(ClusterType.TYPE_FEATURED)
                .addClusterType(ClusterType.TYPE_RECOMMENDATION)
                .build());

当服务收到请求时，它会从与指定聚合类型匹配的所有聚合中删除现有数据。客户端可以选择传递一个或多个聚合类型。如果发生错误，则整个请求将被拒绝，并保持现有状态。

错误处理

强烈建议监听发布 API 的任务结果，以便可以采取后续操作来恢复并重新提交成功的任务。

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

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 返回，其中包含错误代码作为原因。

步骤 3：处理广播意图

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

广播意图的主要目的是应用重新激活和强制数据同步。广播意图并非设计为非常频繁地发送。仅当 Engage 服务确定内容可能已过期（例如，一周前）时才会触发它。这样，即使应用程序长时间未执行，也可以更有把握地确保用户获得最新的内容体验。

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

• 使用 Context.registerReceiver() 动态注册 BroadcastReceiver 类的实例。这使得来自仍在内存中运行的应用程序的通信成为可能。

class AppEngageBroadcastReceiver : BroadcastReceiver(){
  // Trigger recommendation cluster publish when PUBLISH_RECOMMENDATION broadcast
  // is received
  // Trigger featured cluster publish when PUBLISH_FEATURED broadcast is received
  // Trigger continuation cluster publish when PUBLISH_CONTINUATION 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 Continuation Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(Intents.ACTION_PUBLISH_CONTINUATION))
}

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 continuation cluster publish when PUBLISH_CONTINUATION 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 Continuation Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
new IntentFilter(com.google.android.engage.service.Intents.ACTION_PUBLISH_CONTINUATION));

}

• 在 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.PUBLISH_CONTINUATION" />
      </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.PUBLISH_CONTINUATION 建议在收到此意图时启动 publishContinuationCluster 调用。

集成工作流程

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

常见问题

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

联系方式

如果在集成过程中有任何疑问，请联系 [email protected]。

后续步骤

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

• 发送电子邮件至 [email protected] 并附上您已准备好供 Google 测试的集成 APK。
• Google 会进行验证并在内部审查，以确保集成按预期工作。如果需要更改，Google 会与您联系并提供任何必要的详细信息。
• 测试完成后且无需进行任何更改时，Google 会与您联系，通知您可以开始将更新的集成 APK 发布到 Play 商店。
• Google 确认您已将更新的 APK 发布到 Play 商店后，您的**推荐**、**特色**和**续集**聚合可能会发布并对用户可见。