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

Google 将打造一种设备端 surface，该 surface 可按行业整理用户的应用，并且支持全新的沉浸式体验，使用户能够以个性化的方式消费和发现应用内容。这种全屏体验为开发者合作伙伴提供了机会，使其能够通过应用之外的专用渠道展示最优质的富媒体内容。本指南包含面向开发者合作伙伴的说明，介绍了如何集成其旅行和活动内容，以及如何使用 Engage SDK 填充这一新的 surface 区域。

集成详情

术语

此集成包括以下三种集群类型：推荐、精选和接续。

• 推荐集群用于显示来自单个开发者合作伙伴的个性化旅行和活动建议。这些推荐可以针对用户进行个性化设置，也可以泛化（例如，热门商品）。使用这些信息可以显示文章、活动、住宿或景点推荐。

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

  您的推荐将采用如下结构：

  • 推荐集群：一个界面视图，其中包含来自同一开发者合作伙伴的一组推荐。

  • 实体：代表集群中单个内容的对象。此集成提供了一些将使用推荐集群显示的实体：

    • ArticleEntity：ArticleEntity 表示针对与旅行和活动相关的文本内容的推荐。它可用于文章、博文、营销内容、新闻摘要等。

      

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

      

    • LodgingEntity：LodgingEntity 表示住宿，如酒店、公寓、度假屋（短期和长期租赁）。

      

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

      

    • PointOfInterestEntity：PointOfInterestEntity 表示感兴趣的地点，如加油站、活动场地、主题公园、博物馆、旅游景点、徒步小径等。它会突出显示位置是需要传达给用户的关键信息的内容。它不应用于住宿、商店或餐饮场所。

      

• 接续集群用于在单个界面分组中显示来自多个开发者合作伙伴的用户最近互动过的内容。每个开发者合作伙伴最多可以在接续集群中广播 10 个实体。

  接续内容可以采用以下格式：

  • ArticleEntity：ArticleEntity 表示推荐与旅行和活动相关的内容。此实体可用于表示未看完的新闻报道或其他用户想要从其离开时继续观看的内容。例如：��闻摘要 关于旅游目的地或事件的博文摘要

    

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

    

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

    • 体育赛事，例如足球赛预订
    • 电竞预订等游戏活动
    • 电影院预订、音乐会、剧院、签售等娱乐活动
    • 旅行或地图注点预订，如导游陪同参观、博物馆门票
    • 社交 / 研讨会 / 会议预订
    • 培训 / 培训课程预订

    

  • LodgingReservationEntity：LodgingEntityReservation 表示旅游住宿预订，可帮助用户跟踪即将到来或正在进行的酒店或民宿预订。

    

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

    

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

    

• 精选集群是一个界面视图，用于在一个界面分组中展示来自多个开发者合作伙伴的精选重点 GenericFeaturedEntity。精选集群只有一个，并将显示在界面顶部附近，其展示位置的优先级高于所有推荐集群。每个开发者合作伙伴都可以在精选中广播一个受支持类型的实体，因此精选集群中存在来自多个应用开发者的多个实体（可能属于不同类型的实体）。

  • GenericFeaturedEntity：GenericFeaturedEntity 与推荐项的不同之处在于，精选项应用于开发者提供的单个热门内容，并且应代表用户感兴趣的单个最重要的内容。

    

准备工作

最低 API 级别：19

将 com.google.android.play:engage 库添加到您的应用中：

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 数据。
• 系统会解析请求中的数据，并将其存储在经过更新的精选集群中。

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

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 数据。
• 系统会解析请求中的数据，并将其存储在经过更新的接续集群中。

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

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 用于删除推荐集群的内容。

client.deleteRecommendationClusters()

client.deleteRecommendationClusters();

当服务收到请求时，此 API 会从建议集群中移除现有数据。如果发生错误，系统将拒绝整个请求，并保留现有状态。

deleteFeaturedCluster

此 API 用于删除精选集群的内容。

client.deleteFeaturedCluster()

client.deleteFeaturedCluster();

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

deleteContinuationCluster

此 API 用于删除接续集群的内容。

client.deleteContinuationCluster()

client.deleteContinuationCluster();

当服务收到请求时，此 API 会从接续集群中移除现有数据。如果发生错误，系统将拒绝整个请求，并保留现有状态。

deleteUserManagementCluster

此 API 用于删除 UserAccountManagement 集群的内容。

client.deleteUserManagementCluster()

client.deleteUserManagementCluster();

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

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 会从所有与指定集群类型匹配的集群中移除现有数据。客户端可以选择传递一个或多个集群类型。如果发生错误，系统将拒绝整个请求，并保留现有状态。

错误处理

强烈建议开发者监听来自发布 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 步：处理广播 intent

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

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

必须通过以下两种方式设置 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> 标记静态声明实现。这样一来，应用便可以���未运行时接收广播 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.PUBLISH_CONTINUATION" />
      </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.PUBLISH_CONTINUATION 建议在收到此 intent 时启动 publishContinuationCluster 调用。

集成工作流

如需查看在集成完成后验证集成的分步指南，请参阅 Engage 开发者集成工作流程。

常见问题解答

如需查看常见问题解答，请参阅 Engage SDK 常见问题解答。

联系信息

如果在集成过程中有任何疑问，请与 engage-developers@google.com 联系。

后续步骤

完成此集成后，请执行下列后续步骤：

• 发送电子邮件至 engage-developers@google.com，并附上可供 Google 测试的集成 APK。
• Google 会执行验证，并在内部进行审核，以确保集成按预期运行。如果需要更改，Google 会与您联系，将所有必要的详细信息告知您。
• 测试完成后，如果无需进行任何更改，Google 会与您联系，向您说明您已可以开始将经过更新的集成 APK 发布到 Play 商店。
• 在 Google 确认经过更新的 APK 已发布到 Play 商店后，您的推荐、精选和接续集群便可被发布并向用户显示。