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

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

本指南包含开发者合作伙伴将旅行和活动内容分发到 Engage 内容界面的说明。

集成详情

术语

此集成包括以下集群类型：推荐、精选、预订和继续搜索。

推荐集群会显示来自单个开发者合作伙伴的个性化旅行与活动建议。这些推荐可以针对用户进行个性化设置，也可以是通用型推荐（例如，热门商品）。使用这些集群可展示文章、活动、住宿或兴趣点推荐。
- 推荐集群可以由 ArticleEntity、EventEntity、LodgingEntity、PointOfInterestEntity 或 StoreEntity 列表组成，但不能混合不同的实体类型。
您的推荐内容采用以下结构
- 推荐集群：一个 UI 视图，包含来自同一开发者合作伙伴的一组推荐内容。
- 实体：表示集群中单个项目的对象。此集成提供了一些可使用推荐集群展示的实体。
  - ArticleEntity：ArticleEntity 表示与旅行和活动相关的文本内容的推荐。它可用于文章、博文、营销内容、新闻片段等。
    
    图 1：在推荐集群中显示单个 ArticleEntity 的 UI。
  - EventEntity：EventEntity 表示将来发生的事件。事件开始时间是需要传达给用户的关键信息。
    
    图 2：在推荐集群中显示单个 EventEntity 的 UI。
  - LodgingEntity：LodgingEntity 表示住宿，例如酒店、公寓、短期和长期租赁度假屋。
    
    图 3：在推荐集群中显示单个 LodgingEntity 的 UI。
  - StoreEntity：StoreEntity 表示商店、餐厅、咖啡馆等。它突出显示餐饮场所或商店是需要传达给用户的关键信息的内容。
    
    图 4：在推荐集群中显示单个 StoreEntity 的 UI。
  - PointOfInterestEntity：PointOfInterestEntity 表示一个兴趣点，如加油站、活动场所、主题公园、博物馆、旅游景点、徒步路线等。它突出显示位置是需要传达给用户的关键信息的内容。它不应用于住宿、商店或餐饮场所。
    
    图 5：在推荐集群中显示单个 PointOfInterestEntity 的 UI。
预订集群在一个 UI 分组中显示了来自多个开发者合作伙伴的用户近期互动内容。每个开发者合作伙伴将被允许在预订集群中广播最多 10 个实体。

您的预订内容可以采用以下结构
- RestaurantReservationEntity：RestaurantReservationEntity 表示餐厅或咖啡馆的预订，帮助用户追踪即将到来或正在进行的餐厅预订。
  
  图 6：在预订集群中显示单个 RestaurantReservationEntity 的 UI。
- EventReservationEntity：EventReservationEntity 表示事件预订，帮助用户追踪即将到来或正在进行的事件预订。事件可以包括但不限于以下内容：
  - 体育赛事，如足球比赛预订
  - 游戏赛事，如电子竞技预订
  - 娱乐活动，如电影院电影预订、音乐会、戏剧、签售会
  - 旅行或兴趣点预订，如导游团、博物馆门票
  - 社交/研讨会/会议预订
  - 教育/培训课程预订
  图 7：在预订集群中显示单个 EventReservationEntity 的 UI。
- LodgingReservationEntity：LodgingEntityReservation 表示旅行住宿预订，帮助用户追踪即将到来或正在进行的酒店或度假租赁预订。
  
  图 8：在预订集群中显示单个 LodgingReservationEntity 的 UI。
- TransportationReservationEntity：TransportationReservationEntity 表示任何交通方式的预订，帮助用户追踪即将到来或正在进行的航班、渡轮、火车、公共汽车、网约车或游轮预订。
  
  图 9：在预订集群中显示单个 TransportationReservationEntity 的 UI。
- VehicleRentalReservationEntity：VehicleRentalReservationEntity 表示车辆租赁预订，帮助用户追踪即将到来或正在进行的车辆租赁预订。
  
  图 10：在预订集群中显示单个 VehicleRentalReservationEntity 的 UI。
精选集群在一个 UI 分组中展示了来自多个开发者合作伙伴的一系列实体。将只有一个精选集群，它将优先显示在 UI 顶部附近，位于所有推荐集群之上。每个开发者合作伙伴将被允许在精选集群中广播最多 10 个实体。
- GenericFeaturedEntity：GenericFeaturedEntity 与推荐项目不同之处在于，精选项目应来自开发者，用于展示单个顶部内容，并且应代表对用户来说最重要且最相关的内容。
  
  图 11：显示包含 GenericFeaturedEntity 列表的 FeaturedCluster 的 UI
继续搜索集群通过显示用户近期在所有旅行应用中搜索过的查询列表，帮助用户恢复之前的旅行搜索旅程。该集群将固定在第二位，位于预订集群之后、精选集群和推荐集群之前。每个开发者合作伙伴将被允许在“继续搜索”集群中广播最多 3 个实体。
- PointOfInterestEntity：PointOfInterestEntity 表示兴趣点，例如加油站、活动场地、主题公园、博物馆、旅游景点、徒步路线等。它突出显示用户之前搜索过的内容。

前期准备

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

摘要

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

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

集群类型	集群限制	集群中的最小实体限制	集群中的最大实体限制
推荐集群	最多 7 个	最少 1 个	最多 50 个（`ArticleEntity`、`EventEntity`、`LodgingEntity`、`StoreEntity` 或 `PointOfInterestEntity`）
预订集群	最多 1 个	最少 1 个	最多 20 个（`RestaurantReservationEntity`、`EventReservationEntity`、`LodgingReservationEntity`、`TransportationReservationEntity` 或 `VehicleRentalReservationEntity`）
精选集群	最多 1 个	最少 1 个	最多 20 个（`GenericFeaturedEntity`）
继续搜索集群	最多 1 个	最少 1 个	最多 3 个（`PointOfInterestEntity`）

第 1 步：提供实体数据

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

GenericFeaturedEntity
ArticleEntity
EventEntity
LodgingEntity
StoreEntity
PointOfInterestEntity
RestaurantReservationEntity
EventReservationEntity
LodgingReservationEntity
TransportationReservationEntity
VehicleRentalReservationEntity

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

`GenericFeaturedEntity`

属性	要求	说明	格式
操作 URI	必需	指向提供方应用中实体的深层链接。注意：您可以使用深层链接进行归因。参阅此常见问题解答	URI
海报图片	必需	当提供多张图片时，我们将仅显示 1 张图片。推荐的宽高比为 16:9。注意：如果提供了徽章，请确保图片顶部和底部有 24 dp 的安全空间。	请参阅图片规格以获取指导。
标题	可选	实体的标题。	自由文本建议文本大小：50 个字符
说明	可选	描述实体的单段文本。注意：向用户显示的是描述或副标题列表，而不是两者同时显示。	自由文本建议文本大小：180 个字符
副标题列表	可选	最多 3 个副标题，每个副标题一行文本。注意：向用户显示的是描述或副标题列表，而不是两者同时显示。	自由文本每个副标题的建议文本大小：最多 50 个字符
徽章	可选	每个徽章可以是自由文本（最多 15 个字符）或小图片。图片/视频顶部的特殊用户体验处理，例如，作为图片上的徽章叠加层 “实时更新” 文章阅读时长
徽章 - 文本	可选	徽章标题注意：徽章需要文本或图片。	自由文本建议文本大小：最多 15 个字符
徽章 - 图片	可选	小图片特殊用户体验处理，例如作为图片/视频缩略图上的徽章叠加层。注意：徽章需要文本或图片。	请参阅图片规格以获取指导。
内容类别	可选	描述实体中内容的类别。	枚举列表请参阅内容类别部分以获取指导。
DisplayTimeWindow（可选）- 设置内容在界面上显示的时间窗口
开始时间戳	可选	在此纪元时间戳之后，内容应在界面上显示。如果未设置，内容有资格在界面上显示。	以毫秒为单位的纪元时间戳
结束时间戳	可选	在此纪元时间戳之后，内容不再在界面上显示。如果未设置，内容有资格在界面上显示。	以毫秒为单位的纪元时间戳

`ArticleEntity`

属性	要求	说明	格式
操作 URI	必需	指向提供方应用中实体的深层链接。注意：您可以使用深层链接进行归因。参阅此常见问题解答	URI
标题	必需	实体的标题。	自由文本建议文本大小：最多 50 个字符
海报图片	可选	当提供多张图片时，我们将仅显示 1 张图片。推荐的宽高比为 16:9。注意：强烈建议提供图片。如果提供了徽章，请确保图片顶部和底部有 24 dp 的安全空间。	请参阅图片规格以获取指导。
来源 - 标题	可选	作者、组织或记者姓名	自由文本建议文本大小：25 个字符以下
来源 - 图片	可选	来源图片，例如作者、组织、记者	请参阅图片规格以获取指导。
说明	可选	描述实体的单段文本。注意：向用户显示的是描述或副标题列表，而不是两者同时显示。	自由文本建议文本大小：180 个字符
副标题列表	可选	最多 3 个副标题，每个副标题一行文本。注意：向用户显示的是描述或副标题列表，而不是两者同时显示。	自由文本每个副标题的建议文本大小：最多 50 个字符
徽章	可选	每个徽章可以是自由文本（最多 15 个字符）或小图片。图片/视频顶部的特殊用户体验处理，例如作为图片上的徽章叠加层 “实时更新” 文章阅读时长
徽章 - 文本	可选	徽章标题注意：徽章需要文本或图片。	自由文本建议文本大小：最多 15 个字符
徽章 - 图片	可选	小图片特殊用户体验处理，例如作为图片/视频缩略图上的徽章叠加层。注意：徽章需要文本或图片。	请参阅图片规格以获取指导。
内容发布时间	可选	这是内容在应用中发布/更新时的毫秒级纪元时间戳。	以毫秒为单位的纪元时间戳
上次互动时间	有条件地必需	用户上次与此实体互动时的毫秒级纪元时间戳。注意：如果此实体是预订集群的一部分，则此字段为必填项。	以毫秒为单位的纪元时间戳
进度百分比	有条件地必需	用户迄今为止已消费完整内容的百分比。注意：如果此实体是预订集群的一部分，则此字段为必填项。	一个介于 0~100 之间（含）的整数值。
内容类别	可选	描述实体中内容的类别。	枚举列表请参阅内容类别部分以获取指导。
DisplayTimeWindow（可选）- 设置内容在界面上显示的时间窗口
开始时间戳	可选	在此纪元时间戳之后，内容应在界面上显示。如果未设置，内容有资格在界面上显示。	以毫秒为单位的纪元时间戳
结束时间戳	可选	在此纪元时间戳之后，内容不再在界面上显示。如果未设置，内容有资格在界面上显示。	以毫秒为单位的纪元时间戳

`EventEntity`

属性	要求	说明	格式
操作 URI	必需	指向提供方应用中实体的深层链接。注意：您可以使用深层链接进行归因。参阅此常见问题解答	URI
标题	必需	实体的标题。	字符串建议文本大小：最多 50 个字符
本地化开始时间 - 时间戳	必需	事件预计开始的纪元时间戳。	Joda-Time Instant
本地化开始时间 - 时区	必需	事件预计开始的时区。	Joda-Time DateTimeZone 请参阅时区规格以获取指导。
活动模式	必需	指示活动是虚拟、现场还是两者兼有的字段。	枚举：VIRTUAL、IN_PERSON 或 HYBRID
海报图片	必需	当提供多张图片时，我们将仅显示 1 张图片。推荐的宽高比为 16:9。注意：强烈建议提供图片。如果提供了徽章，请确保图片顶部和底部有 24 dp 的安全空间。	请参阅图片规格以获取指导。
位置 - 国家/地区	有条件地必需	活动发生的国家/地区。注意：对于现场或混合模式的活动，此项为必填项。	自由文本建议文本大小：最多约 20 个字符
位置 - 城市	有条件地必需	活动发生的城市。注意：对于现场或混合模式的活动，此项为必填项。	自由文本建议文本大小：最多约 20 个字符
位置 - 显示地址	有条件地必需	活动举办的地址或场地名称，应显示给用户。注意：对于现场或混合模式的活动，此项为必填项。	自由文本建议文本大小：最多约 20 个字符
位置 - 街道地址	可选	活动举办地点的街道地址（如果适用）。	自由文本建议文本大小：最多约 20 个字符
位置 - 州/省	可选	活动举办的州或省（如果适用）。	自由文本建议文本大小：最多约 20 个字符
位置 - 邮政编码	可选	活动举办地点的邮政编码（如果适用）。	自由文本建议文本大小：最多约 20 个字符
位置 - 社区	可选	活动举办的社区（如果适用）。	自由文本建议文本大小：最多约 20 个字符
结束时间	可选	事件预计结束的纪元时间戳。注意：这将以毫秒表示。	以毫秒为单位的纪元时间戳
说明	可选	描述实体的单段文本。注意：向用户显示的是描述或副标题列表，而不是两者同时显示。	自由文本建议文本大小：180 个字符
副标题列表	可选	最多 3 个副标题，每个副标题一行文本。注意：向用户显示的是描述或副标题列表，而不是两者同时显示。	自由文本每个副标题的建议文本大小：最多 50 个字符
徽章	可选	每个徽章可以是自由文本（最多 15 个字符）或小图片。
徽章 - 文本	可选	徽章标题注意：徽章需要文本或图片。	自由文本建议文本大小：最多 15 个字符
徽章 - 图片	可选	小图片特殊用户体验处理，例如作为图片/视频缩略图上的徽章叠加层。注意：徽章需要文本或图片。	请参阅图片规格以获取指导。
价格 - 当前价格	有条件地必需	活动门票/通行证的当前价格。如果提供了划掉价格，则必须提供此项。	自由文本
价格 - 划掉价格	可选	活动门票/通行证的原始价格。	自由文本
价格标注	可选	价格标注用于显示促销、活动、会员折扣（如果可用）。	自由文本建议文本大小：45 个字符以下（过长的文本可能会显示省略号）
内容类别	可选	描述实体中内容的类别。	符合条件的枚举列表 TYPE_MOVIES_AND_TV_SHOWS（示例 - 电影院） TYPE_DIGITAL_GAMES（示例 - 电子竞技） TYPE_MUSIC（示例 - 音乐会） TYPE_TRAVEL_AND_LOCAL（示例 - 旅游、节日） TYPE_HEALTH_AND_FITNESS（示例 - 瑜伽课） TYPE_EDUCATION（示例 - 课程） TYPE_SPORTS（示例 - 足球比赛） TYPE_DATING（示例 - 聚会）请参阅内容类别部分以获取指导。
DisplayTimeWindow（可选）- 设置内容在界面上显示的时间窗口
开始时间戳	可选	在此纪元时间戳之后，内容应在界面上显示。如果未设置，内容有资格在界面上显示。	以毫秒为单位的纪元时间戳
结束时间戳	可选	在此纪元时间戳之后，内容不再在界面上显示。如果未设置，内容有资格在界面上显示。	以毫秒为单位的纪元时间戳

`LodgingEntity`

属性	要求	说明	格式
操作 URI	必需	指向提供方应用中实体的深层链接。注意：您可以使用深层链接进行归因。参阅此常见问题解答	URI
标题	必需	实体的标题。	字符串建议文本大小：最多 50 个字符
海报图片	必需	当提供多张图片时，我们将仅显示 1 张图片。推荐的宽高比为 16:9。注意：如果提供了徽章，请确保图片顶部和底部有 24 dp 的安全空间。	请参阅图片规格以获取指导。
位置 - 国家/地区	必需	住宿所在的国家/地区。	自由文本建议文本大小：最多约 20 个字符
位置 - 城市	必需	住宿所在的城市。	自由文本建议文本大小：最多约 20 个字符
位置 - 显示地址	必需	将显示给用户的地址。在大多数用例中，我们建议包含城市名称，并可能包含州或国家/地区。仅当用户靠近该地点、用户熟悉该地点或集群标题中包含城市时，才包含街道地址或社区。如果您包含街道地址，请提供简洁的地址，尽可能使用缩写（例如，“St”代表“Street”，“Ave”代表“Avenue”）。	自由文本建议文本大小：最多约 20 个字符
位置 - 街道地址	可选	住宿的街道地址（如果适用）。	自由文本建议文本大小：最多约 20 个字符
位置 - 州/省	可选	住宿所在的州或省（如果适用）。	自由文本建议文本大小：最多约 20 个字符
位置 - 邮政编码	可选	住宿的邮政编码（如果适用）。	自由文本建议文本大小：最多约 20 个字符
位置 - 社区	可选	住宿所在的社区（如果适用）。	自由文本建议文本大小：最多约 20 个字符
徽章	可选	每个徽章可以是自由文本（最多 15 个字符）或小图片。
徽章 - 文本	可选	徽章标题注意：徽章需要文本或图片。	自由文本建议文本大小：最多 15 个字符
徽章 - 图片	可选	小图片特殊用户体验处理，例如作为图片/视频缩略图上的徽章叠加层。注意：徽章需要文本或图片。	请参阅图片规格以获取指导。
说明	可选	描述实体的单段文本。注意：向用户显示的是描述或副标题列表，而不是两者同时显示。	自由文本建议文本大小：180 个字符
副标题列表	可选	最多 3 个副标题，每个副标题一行文本。注意：向用户显示的是描述或副标题列表，而不是两者同时显示。	自由文本每个副标题的建议文本大小：最多 50 个字符
AvailabilityTimeWindow - 本地化开始时间 - 时间戳	可选	住宿预计开放/可用的纪元时间戳。	Joda-Time Instant
AvailabilityTimeWindow - 本地化开始时间 - 时区	可选	住宿预计开放/可用的时区。	Joda-Time DateTimeZone 请参阅时区规格以获取指导。
AvailabilityTimeWindow - 本地化结束时间 - 时间戳	可选	住宿预计开放/可用的纪元时间戳。	Joda-Time Instant
AvailabilityTimeWindow - 本地化结束时间 - 时区	可选	住宿预计开放/可用的时区。	Joda-Time DateTimeZone 请参阅时区规格以获取指导。
评分 - 最大值	可选	评分量表的最大值。如果提供了评分的当前值，则必须提供此项。	数字 >= 0.0
评分 - 当前值	可选	评分量表的当前值。如果提供了评分的最大值，则必须提供此项。	数字 >= 0.0
评分 - 计数	可选	住宿的评分数量。注意：如果您的应用希望控制此字段的显示方式，请提供此字段。请提供可显示给用户的简洁字符串。例如，如果计数为 1,000,000，请考虑使用 1M 等缩写，以免在较小的显示尺寸上被截断。	字符串
评分 - 计数数值	可选	住宿的评分数量。注意：如果您不想自行处理显示缩写逻辑，请提供此字段。如果“计数”和“计数数值”都存在，我们将使用“计数”向用户显示。	长整型
价格 - 当前价格	有条件地必需	住宿的当前价格。如果提供了划掉价格，则必须提供此项。	自由文本
价格 - 划掉价格	可选	住宿的原始价格，将在 UI 中划掉。	自由文本
价格标注	可选	价格标注用于显示促销、活动、会员折扣（如果可用）。	自由文本建议文本大小：45 个字符以下（过长的文本可能会显示省略号）
DisplayTimeWindow（可选）- 设置内容在界面上显示的时间窗口
开始时间戳	可选	在此纪元时间戳之后，内容应在界面上显示。如果未设置，内容有资格在界面上显示。	以毫秒为单位的纪元时间戳
结束时间戳	可选	在此纪元时间戳之后，内容不再在界面上显示。如果未设置，内容有资格在界面上显示。	以毫秒为单位的纪元时间戳

`StoreEntity`

StoreEntity 对象代表开发者合作伙伴希望发布的单个商店，例如与旅行体验相关的热门餐厅或小吃店。

属性	要求	说明	格式
海报图片	必需	必须提供至少一张图片。	请参阅图片规格以获取指导。
操作 URI	必需	指向提供方应用中实体的深层链接。注意：您可以使用深层链接进行归因。参阅此常见问题解答	URI
标题	可选	商店名称。	自由文本建议文本大小：45 个字符以下（过长的文本可能会显示省略号）
位置	可选	商店位置。	自由文本建议文本大小：45 个字符以下（过长的文本可能会显示省略号）
标注	可选	标注用于突出显示商店的促销、活动或更新（如果可用）。	自由文本建议文本大小：45 个字符以下（过长的文本可能会显示省略号）
标注细则	可选	标注的细则文本。	自由文本建议文本大小：45 个字符以下（过长的文本可能会显示省略号）
说明	可选	商店描述。	自由文本建议文本大小：90 个字符以下（过长的文本可能会显示省略号）
类别	可选	商店类别，在餐饮场所的语境中，可以是“法式”、“新美式”、“拉面”、“高级餐厅”等菜系。	自由文本建议文本大小：45 个字符以下（过长的文本可能会显示省略号）
评分 - 最大值	可选	评分量表的最大值。如果提供了评分的当前值，则必须提供此项。	数字 >= 0.0
评分 - 当前值	可选	评分量表的当前值。如果提供了评分的最大值，则必须提供此项。	数字 >= 0.0
评分 - 计数	可选	住宿的评分数量。注意：如果您的应用希望控制此字段的显示方式，请提供此字段。请提供可显示给用户的简洁字符串。例如，如果计数为 1,000,000，请考虑使用 1M 等缩写，以免在较小的显示尺寸上被截断。	字符串
评分 - 计数数值	可选	住宿的评分数量。注意：如果您不想自行处理显示缩写逻辑，请提供此字段。如果“计数”和“计数数值”都存在，我们将使用“计数”向用户显示。	长整型
DisplayTimeWindow（可选）- 设置内容在界面上显示的时间窗口
开始时间戳	可选	在此纪元时间戳之后，内容应在界面上显示。如果未设置，内容有资格在界面上显示。	以毫秒为单位的纪元时间戳
结束时间戳	可选	在此纪元时间戳之后，内容不再在界面上显示。如果未设置，内容有资格在界面上显示。	以毫秒为单位的纪元时间戳

`PointOfInterestEntity`

属性	要求	说明	格式
操作 URI	必需	指向提供方应用中实体的深层链接。注意：您可以使用深层链接进行归因。参阅此常见问题解答	URI
标题	必需	实体的标题。	字符串建议文本大小：最多 50 个字符
海报图片	有条件地必需	当提供多张图片时，我们将仅显示 1 张图片。推荐的宽高比为 16:9。注意：如果实体是推荐集群的一部分，则需要图片。如果提供了徽章，请确保图片顶部和底部有 24 dp 的安全空间。	请参阅图片规格以获取指导。
上次互动时间	有条件地必需	用户上次与此实体互动时的纪元时间戳。注意：如果实体是“继续搜索”集群的一部分，则此字段为必填项。	Joda-Time Instant
位置 - 国家/地区	有条件地必需	兴趣点所在的国家/地区。注意：如果实体是推荐集群的一部分，则此字段为必填项。	自由文本建议文本大小：最多约 20 个字符
位置 - 城市	有条件地必需	兴趣点所在的城市。注意：如果实体是推荐集群的一部分，则此字段为必填项。	自由文本建议文本大小：最多约 20 个字符
位置 - 显示地址	有条件地必需	将显示给用户的地址。提供简洁的地址，尽可能使用缩写（例如，“St”代表“Street”，“Ave”代表“Avenue”）。此字符串可能会根据用户的设备和设置被截断。包含城市名称以便清晰识别。注意：如果实体是推荐集群的一部分，则此字段为必填项。	自由文本建议文本大小：最多约 35 个字符
位置 - 街道地址	可选	兴趣点的街道地址（如果适用）。	自由文本建议文本大小：最多约 20 个字符
位置 - 州/省	可选	兴趣点所在的州或省（如果适用）。	自由文本建议文本大小：最多约 20 个字符
位置 - 邮政编码	可选	兴趣点的邮政编码（如果适用）。	自由文本建议文本大小：最多约 20 个字符
位置 - 社区	可选	兴趣点所在的社区（如果适用）。	自由文本建议文本大小：最多约 20 个字符
AvailabilityTimeWindow - 本地化开始时间 - 时间戳	可选	兴趣点预计开放/可用的纪元时间戳。	Joda-Time Instant
AvailabilityTimeWindow - 本地化开始时间 - 时区	可选	兴趣点预计开放/可用的时区。	Joda-Time DateTimeZone 请参阅时区规格以获取指导。
AvailabilityTimeWindow - 本地化结束时间 - 时间戳	可选	兴趣点预计开放/可用的纪元时间戳。	Joda-Time Instant
AvailabilityTimeWindow - 本地化结束时间 - 时区	可选	兴趣点预计开放/可用的时区。	Joda-Time DateTimeZone 请参阅时区规格以获取指导。
徽章	可选	每个徽章可以是自由文本（最多 15 个字符）或小图片。
徽章 - 文本	可选	徽章标题注意：徽章需要文本或图片。	自由文本建议文本大小：最多 15 个字符
徽章 - 图片	可选	小图片特殊用户体验处理，例如作为图片/视频缩略图上的徽章叠加层。注意：徽章需要文本或图片。	请参阅图片规格以获取指导。
说明	可选	描述实体的单段文本。注意：向用户显示的是描述或副标题列表，而不是两者同时显示。	自由文本建议文本大小：180 个字符
副标题列表	可选	最多 3 个副标题，每个副标题一行文本。注意：向用户显示的是描述或副标题列表，而不是两者同时显示。	自由文本每个副标题的建议文本大小：最多 50 个字符
评分 - 最大值	可选	评分量表的最大值。如果提供了评分的当前值，则必须提供此项。	数字 >= 0.0
评分 - 当前值	可选	评分量表的当前值。如果提供了评分的最大值，则必须提供此项。	数字 >= 0.0
评分 - 计数	可选	兴趣点的评分数量。注意：如果您的应用希望控制此字段的显示方式，请提供此字段。请提供可显示给用户的简洁字符串。例如，如果计数为 1,000,000，请考虑使用 1M 等缩写，以免在较小的显示尺寸上被截断。	字符串
评分 - 计数数值	可选	兴趣点的评分数量。注意：如果您不想自行处理显示缩写逻辑，请提供此字段。如果“计数”和“计数数值”都存在，我们将使用“计数”向用户显示。	长整型
价格 - 当前价格	有条件地必需	兴趣点门票/入场券的当前价格。如果提供了划掉价格，则必须提供此项。	自由文本
价格 - 划掉价格	可选	兴趣点门票/入场券的原始价格。	自由文本
价格标注	可选	价格标注用于显示促销、活动、会员折扣（如果可用）。	自由文本建议文本大小：45 个字符以下（过长的文本可能会显示省略号）
内容类别	可选	描述实体中内容的类别。	符合条件的枚举列表 TYPE_TRAVEL_AND_LOCAL TYPE_MOVIES_AND_TV_SHOWS（示例 - 剧院） TYPE_MEDICAL（示例 - 医院） TYPE_EDUCATION（示例 - 学校） TYPE_SPORTS（示例 - 体育场）请参阅内容类别部分以获取指导。
DisplayTimeWindow（可选）- 设置内容在界面上显示的时间窗口
开始时间戳	可选	在此纪元时间戳之后，内容应在界面上显示。如果未设置，内容有资格在界面上显示。	以毫秒为单位的纪元时间戳
结束时间戳	可选	在此纪元时间戳之后，内容不再在界面上显示。如果未设置，内容有资格在界面上显示。	以毫秒为单位的纪元时间戳

`RestaurantReservationEntity`

属性	要求	说明	格式
操作 URI	必需	指向提供方应用中实体的深层链接。注意：您可以使用深层链接进行归因。参阅此常见问题解答	URI
标题	必需	实体的标题。	字符串建议文本大小：最多 50 个字符
本地化预订开始时间 - 时间戳	必需	预订预计开始的纪元时间戳。	Joda-Time Instant
本地化预订开始时间 - 时区	必需	预订预计开始的时区。	Joda-Time DateTimeZone 请参阅时区规格以获取指导。
位置 - 国家/地区	必需	餐厅所在的国家/地区。	自由文本建议文本大小：最多约 20 个字符
位置 - 城市	必需	餐厅所在的城市。	自由文本建议文本大小：最多约 20 个字符
位置 - 显示地址	必需	将显示给用户的餐厅地址。	自由文本建议文本大小：最多约 20 个字符
位置 - 街道地址	可选	餐厅的街道地址（如果适用）。	自由文本建议文本大小：最多约 20 个字符
位置 - 州/省	可选	餐厅所在的州或省（如果适用）。	自由文本建议文本大小：最多约 20 个字符
位置 - 邮政编码	可选	餐厅的邮政编码（如果适用）。	自由文本建议文本大小：最多约 20 个字符
位置 - 社区	可选	餐厅所在的社区（如果适用）。	自由文本建议文本大小：最多约 20 个字符
海报图片	可选	当提供多张图片时，我们将仅显示 1 张图片。推荐的宽高比为 16:9。	请参阅图片规格以获取指导。
说明	可选	描述实体的单段文本。注意：向用户显示的是描述或副标题列表，而不是两者同时显示。	自由文本建议文本大小：180 个字符
副标题列表	可选	最多 3 个副标题，每个副标题一行文本。注意：向用户显示的是描述或副标题列表，而不是两者同时显示。	自由文本每个副标题的建议文本大小：最多 50 个字符
餐桌人数	可选	预订组中的人数	整数 > 0
DisplayTimeWindow（可选）- 设置内容在界面上显示的时间窗口
开始时间戳	可选	在此纪元时间戳之后，内容应在界面上显示。如果未设置，内容有资格在界面上显示。	以毫秒为单位的纪元时间戳
结束时间戳	可选	在此纪元时间戳之后，内容不再在界面上显示。如果未设置，内容有资格在界面上显示。	以毫秒为单位的纪元时间戳

`EventReservationEntity`

属性	要求	说明	格式
操作 URI	必需	指向提供方应用中实体的深层链接。注意：您可以使用深层链接进行归因。参阅此常见问题解答	URI
标题	必需	实体的标题。	字符串建议文本大小：最多 50 个字符
本地化开始时间 - 时间戳	必需	事件预计开始的纪元时间戳。	Joda-Time Instant
本地化开始时间 - 时区	必需	事件预计开始的时区。	Joda-Time DateTimeZone 请参阅时区规格以获取指导。
活动模式	必需	指示活动是虚拟、现场还是两者兼有的字段。	枚举：VIRTUAL、IN_PERSON 或 HYBRID
位置 - 国家/地区	有条件地必需	活动发生的国家/地区。注意：对于现场或混合模式的活动，此项为必填项。	自由文本建议文本大小：最多约 20 个字符
位置 - 城市	有条件地必需	活动发生的城市。注意：对于现场或混合模式的活动，此项为必填项。	自由文本建议文本大小：最多约 20 个字符
位置 - 显示地址	有条件地必需	活动举办的地址或场地名称，应显示给用户。注意：对于现场或混合模式的活动，此项为必填项。	自由文本建议文本大小：最多约 20 个字符
位置 - 街道地址	可选	活动举办地点的街道地址（如果适用）。	自由文本建议文本大小：最多约 20 个字符
位置 - 州/省	可选	活动举办的州或省（如果适用）。	自由文本建议文本大小：最多约 20 个字符
位置 - 邮政编码	可选	活动举办地点的邮政编码（如果适用）。	自由文本建议文本大小：最多约 20 个字符
位置 - 社区	可选	活动举办的社区（如果适用）。	自由文本建议文本大小：最多约 20 个字符
海报图片	可选	当提供多张图片时，我们将仅显示 1 张图片。推荐的宽高比为 16:9。注意：强烈建议提供图片。如果提供了徽章，请确保图片顶部和底部有 24 dp 的安全空间。	请参阅图片规格以获取指导。
本地化结束时间 - 时间戳	可选	事件预计结束的纪元时间戳。	Joda-Time Instant
本地化结束时间 - 时区	可选	事件预计结束的时区。	Joda-Time DateTimeZone 请参阅时区规格以获取指导。
服务提供商 - 名称	可选	服务提供商的名称。注意：服务提供商需要文本或图片。	自由文本。例如，活动组织者/旅行团的名称
服务提供商 - 图片	可选	服务提供商的徽标/图片。注意：服务提供商需要文本或图片。	请参阅图片规格以获取指导。
说明	可选	描述实体的单段文本。注意：向用户显示的是描述或副标题列表，而不是两者同时显示。	自由文本建议文本大小：180 个字符
副标题列表	可选	最多 3 个副标题，每个副标题一行文本。注意：向用户显示的是描述或副标题列表，而不是两者同时显示。	自由文本每个副标题的建议文本大小：最多 50 个字符
徽章	可选	每个徽章可以是自由文本（最多 15 个字符）或小图片。
徽章 - 文本	可选	徽章标题注意：徽章需要文本或图片。	自由文本建议文本大小：最多 15 个字符
徽章 - 图片	可选	小图片特殊用户体验处理，例如作为图片/视频缩略图上的徽章叠加层。注意：徽章需要文本或图片。	请参阅图片规格以获取指导。
预订 ID	可选	事件预订的预订 ID。	自由文本
价格 - 当前价格	有条件地必需	活动门票/通行证的当前价格。如果提供了划掉价格，则必须提供此项。	自由文本
价格 - 划掉价格	可选	活动门票/通行证的原始价格。	自由文本
价格标注	可选	价格标注用于显示促销、活动、会员折扣（如果可用）。	自由文本建议文本大小：45 个字符以下（过长的文本可能会显示省略号）
评分 - 最大值	可选	评分量表的最大值。如果提供了评分的当前值，则必须提供此项。	数字 >= 0.0
评分 - 当前值	可选	评分量表的当前值。如果提供了评分的最大值，则必须提供此项。	数字 >= 0.0
评分 - 计数	可选	事件的评分数量。注意：如果您的应用希望控制此字段的显示方式，请提供此字段。请提供可显示给用户的简洁字符串。例如，如果计数为 1,000,000，请考虑使用 1M 等缩写，以免在较小的显示尺寸上被截断。	字符串
评分 - 计数数值	可选	事件的评分数量。注意：如果您不想自行处理显示缩写逻辑，请提供此字段。如果“计数”和“计数数值”都存在，我们将使用“计数”向用户显示。	长整型
内容类别	可选	描述实体中内容的类别。	符合条件的枚举列表 TYPE_MOVIES_AND_TV_SHOWS（示例 - 电影院） TYPE_DIGITAL_GAMES（示例 - 电子竞技） TYPE_MUSIC（示例 - 音乐会） TYPE_TRAVEL_AND_LOCAL（示例 - 旅游、节日） TYPE_HEALTH_AND_FITNESS（示例 - 瑜伽课） TYPE_EDUCATION（示例 - 课程） TYPE_SPORTS（示例 - 足球比赛） TYPE_DATING（示例 - 聚会）请参阅内容类别部分以获取指导。
DisplayTimeWindow（可选）- 设置内容在界面上显示的时间窗口
开始时间戳	可选	在此纪元时间戳之后，内容应在界面上显示。如果未设置，内容有资格在界面上显示。	以毫秒为单位的纪元时间戳
结束时间戳	可选	在此纪元时间戳之后，内容不再在界面上显示。如果未设置，内容有资格在界面上显示。	以毫秒为单位的纪元时间戳

`LodgingReservationEntity`

属性	要求	说明	格式
操作 URI	必需	指向提供方应用中实体的深层链接。注意：您可以使用深层链接进行归因。参阅此常见问题解答	URI
标题	必需	实体的标题。	自由文本。例如，“您的住宿：12 月 12 日起” 建议文本大小：最多 50 个字符
本地化入住时间 - 时间戳	必需	表示预订入住时间的纪元时间戳。	Joda-Time Instant
本地化入住时间 - 时区	必需	预订入住时间所在的时区。	Joda-Time DateTimeZone 请参阅时区规格以获取指导。
本地化退房时间 - 时间戳	必需	表示预订退房时间的纪元时间戳。	Joda-Time Instant
本地化退房时间 - 时区	必需	预订退房时间所在的时区。	Joda-Time DateTimeZone 请参阅时区规格以获取指导。
位置 - 国家/地区	必需	住宿所在的国家/地区。	自由文本建议文本大小：最多约 20 个字符
位置 - 城市	必需	住宿所在的城市。	自由文本建议文本大小：最多约 20 个字符
位置 - 显示地址	必需	将显示给用户的地址。提供简洁的地址，尽可能使用缩写（例如，“St”代表“Street”，“Ave”代表“Avenue”）。此字符串可能会根据用户的设备和设置被截断。包含城市名称以便清晰识别。	自由文本建议文本大小：最多约 35 个字符
位置 - 街道地址	可选	住宿的街道地址（如果适用）。	自由文本建议文本大小：最多约 20 个字符
位置 - 州/省	可选	住宿所在的州或省（如果适用）。	自由文本建议文本大小：最多约 20 个字符
位置 - 邮政编码	可选	住宿的邮政编码（如果适用）。	自由文本建议文本大小：最多约 20 个字符
位置 - 社区	可选	住宿所在的社区（如果适用）。	自由文本建议文本大小：最多约 20 个字符
海报图片	可选	当提供多张图片时，我们将仅显示 1 张图片。推荐的宽高比为 16:9。注意：如果提供了徽章，请确保图片顶部和底部有 24 dp 的安全空间。	请参阅图片规格以获取指导。
说明	可选	描述实体的单段文本。注意：向用户显示的是描述或副标题列表，而不是两者同时显示。	自由文本建议文本大小：180 个字符
副标题列表	可选	最多 3 个副标题，每个副标题一行文本。注意：向用户显示的是描述或副标题列表，而不是两者同时显示。	自由文本每个副标题的建议文本大小：最多 50 个字符
预订 ID	可选	住宿预订的预订 ID。	自由文本
评分 - 最大值	可选	评分量表的最大值。如果提供了评分的当前值，则必须提供此项。	数字 >= 0.0
评分 - 当前值	可选	评分量表的当前值。如果提供了评分的最大值，则必须提供此项。	数字 >= 0.0
评分 - 计数	可选	住宿的评分数量。注意：如果您的应用希望控制此字段的显示方式，请提供此字段。请提供可显示给用户的简洁字符串。例如，如果计数为 1,000,000，请考虑使用 1M 等缩写，以免在较小的显示尺寸上被截断。	字符串
评分 - 计数数值	可选	住宿的评分数量。注意：如果您不想自行处理显示缩写逻辑，请提供此字段。如果“计数”和“计数数值”都存在，我们将使用“计数”向用户显示。	长整型
价格 - 当前价格	有条件地必需	住宿的当前价格。如果提供了划掉价格，则必须提供此项。	自由文本
价格 - 划掉价格	可选	住宿的原始价格，将在 UI 中划掉。	自由文本
价格标注	可选	价格标注用于显示促销、活动、会员折扣（如果可用）。	自由文本建议文本大小：45 个字符以下（过长的文本可能会显示省略号）
DisplayTimeWindow（可选）- 设置内容在界面上显示的时间窗口
开始时间戳	可选	在此纪元时间戳之后，内容应在界面上显示。如果未设置，内容有资格在界面上显示。	以毫秒为单位的纪元时间戳
结束时间戳	可选	在此纪元时间戳之后，内容不再在界面上显示。如果未设置，内容有资格在界面上显示。	以毫秒为单位的纪元时间戳

`TransportationReservationEntity`

属性	要求	说明	格式
操作 URI	必需	指向提供方应用中实体的深层链接。注意：您可以使用深层链接进行归因。参阅此常见问题解答	URI
标题	必需	实体的标题。	自由文本。例如，“旧金山到圣安东尼奥” 建议文本大小：最多 50 个字符
交通类型	必需	预订的交通模式/类型。	枚举：FLIGHT、TRAIN、BUS 或 FERRY
本地化出发时间 - 时间戳	必需	表示出发时间的纪元时间戳。	Joda-Time Instant
本地化出发时间 - 时区	必需	出发时间所在的时区。	Joda-Time DateTimeZone 请参阅时区规格以获取指导。
本地化抵达时间 - 时间戳	必需	表示抵达时间的纪元时间戳。	Joda-Time Instant
本地化抵达时间 - 时区	必需	抵达时间所在的时区。	Joda-Time DateTimeZone 请参阅时区规格以获取指导。
交通班次	必需	航班号、公共汽车号、火车号或渡轮/游轮号。	自由文本
本地化登机/登车时间 - 时间戳	必需	表示预订登机/登车时间的纪元时间戳（如果适用）	Joda-Time Instant
本地化登机/登车时间 - 时区	必需	预订登机/登车时间所在的时区（如果适用）	Joda-Time DateTimeZone 请参阅时区规格以获取指导。
出发地点 - 国家/地区	可选	出发国家/地区。	自由文本建议文本大小：最多约 20 个字符
出发地点 - 城市	可选	出发城市。	自由文本建议文本大小：最多约 20 个字符
出发地点 - 显示地址	可选	将显示给用户的出发地点。	自由文本建议文本大小：最多约 20 个字符
出发地点 - 街道地址	可选	出发地点的街道地址（如果适用）。	自由文本建议文本大小：最多约 20 个字符
出发地点 - 州/省	可选	出发地点的州或省（如果适用）。	自由文本建议文本大小：最多约 20 个字符
出发地点 - 邮政编码	可选	出发地点的邮政编码（如果适用）。	自由文本建议文本大小：最多约 20 个字符
出发地点 - 社区	可选	出发地点的社区（如果适用）。	自由文本建议文本大小：最多约 20 个字符
抵达地点 - 国家/地区	可选	抵达国家/地区。	自由文本建议文本大小：最多约 20 个字符
抵达地点 - 城市	可选	抵达城市。	自由文本建议文本大小：最多约 20 个字符
抵达地点 - 显示地址	可选	将显示给用户的抵达地点。	自由文本建议文本大小：最多约 20 个字符
抵达地点 - 街道地址	可选	抵达地点的街道地址（如果适用）。	自由文本建议文本大小：最多约 20 个字符
抵达地点 - 州/省	可选	抵达地点的州或省（如果适用）。	自由文本建议文本大小：最多约 20 个字符
抵达地点 - 邮政编码	可选	抵达地点的邮政编码（如果适用）。	自由文本建议文本大小：最多约 20 个字符
抵达地点 - 社区	可选	抵达地点的社区（如果适用）。	自由文本建议文本大小：最多约 20 个字符
服务提供商 - 名称	可选	服务提供商的名称。注意：服务提供商需要文本或图片。	自由文本。例如，航空公司名称
服务提供商 - 图片	可选	服务提供商的徽标/图片。注意：服务提供商需要文本或图片。	请参阅图片规格以获取指导。
海报图片	可选	当提供多张图片时，我们将仅显示 1 张图片。推荐的宽高比为 16:9。	请参阅图片规格以获取指导。
说明	可选	描述实体的单段文本。注意：向用户显示的是描述或副标题列表，而不是两者同时显示。	自由文本建议文本大小：180 个字符
副标题列表	可选	最多 3 个副标题，每个副标题一行文本。注意：向用户显示的是描述或副标题列表，而不是两者同时显示。	自由文本每个副标题的建议文本大小：最多 50 个字符
预订 ID	可选	交通预订的预订 ID。	自由文本
价格 - 当前价格	有条件地必需	预订的当前价格。如果提供了划掉价格，则必须提供此项。	自由文本
价格 - 划掉价格	可选	预订的原始价格，将在 UI 中划掉。	自由文本
价格标注	可选	价格标注用于显示促销、活动、会员折扣（如果可用）。	自由文本建议文本大小：45 个字符以下（过长的文本可能会显示省略号）
DisplayTimeWindow（可选）- 设置内容在界面上显示的时间窗口
开始时间戳	可选	在此纪元时间戳之后，内容应在界面上显示。如果未设置，内容有资格在界面上显示。	以毫秒为单位的纪元时间戳
结束时间戳	可选	在此纪元时间戳之后，内容不再在界面上显示。如果未设置，内容有资格在界面上显示。	以毫秒为单位的纪元时间戳

`VehicleRentalReservationEntity`

属性	要求	说明	格式
操作 URI	必需	指向提供方应用中实体的深层链接。注意：您可以使用深层链接进行归因。参阅此常见问题解答	URI
标题	必需	实体的标题。	自由文本。例如，“安飞士联合广场旧金山” 建议文本大小：最多 50 个字符
本地化取车时间 - 时间戳	必需	表示预订取车时间的纪元时间戳。	Joda-Time Instant
本地化取车时间 - 时区	必需	预订取车时间所在的时区。	Joda-Time DateTimeZone 请参阅时区规格以获取指导。
本地化还车时间 - 时间戳	可选	表示预订退房时间的纪元时间戳。	Joda-Time Instant
本地化还车时间 - 时区	可选	预订还车时间所在的时区。	Joda-Time DateTimeZone 请参阅时区规格以获取指导。
取车地址 - 国家/地区	可选	取车地点的国家/地区。	自由文本建议文本大小：最多约 20 个字符
取车地址 - 城市	可选	取车地点的城市。	自由文本建议文本大小：最多约 20 个字符
取车地址 - 显示地址	可选	将显示给用户的取车地点。	自由文本建议文本大小：最多约 20 个字符
取车地址 - 街道地址	可选	取车地点的街道地址（如果适用）。	自由文本建议文本大小：最多约 20 个字符
取车地址 - 州/省	可选	取车地点的州或省（如果适用）。	自由文本建议文本大小：最多约 20 个字符
取车地址 - 邮政编码	可选	取车地点的邮政编码（如果适用）。	自由文本建议文本大小：最多约 20 个字符
取车地址 - 社区	可选	取车地点的社区（如果适用）。	自由文本建议文本大小：最多约 20 个字符
还车地址 - 国家/地区	可选	还车地点的国家/地区。	自由文本建议文本大小：最多约 20 个字符
还车地址 - 城市	可选	还车地点的城市。	自由文本建议文本大小：最多约 20 个字符
还车地址 - 显示地址	可选	将显示给用户的还车地点。	自由文本建议文本大小：最多约 20 个字符
还车地址 - 街道地址	可选	还车地点的街道地址（如果适用）。	自由文本建议文本大小：最多约 20 个字符
还车地址 - 州/省	可选	还车地点的州或省（如果适用）。	自由文本建议文本大小：最多约 20 个字符
还车地址 - 邮政编码	可选	还车地点的邮政编码（如果适用）。	自由文本建议文本大小：最多约 20 个字符
还车地址 - 社区	可选	还车地点的社区（如果适用）。	自由文本建议文本大小：最多约 20 个字符
服务提供商 - 名称	可选	服务提供商的名称。注意：服务提供商需要文本或图片。	自由文本。例如，“安飞士租车”
服务提供商 - 图片	可选	服务提供商的徽标/图片。注意：服务提供商需要文本或图片。	请参阅图片规格以获取指导。
海报图片	可选	当提供多张图片时，我们将仅显示 1 张图片。推荐的宽高比为 16:9。	请参阅图片规格以获取指导。
说明	可选	描述实体的单段文本。注意：向用户显示的是描述或副标题列表，而不是两者同时显示。	自由文本建议文本大小：180 个字符
副标题列表	可选	最多 3 个副标题，每个副标题一行文本。注意：向用户显示的是描述或副标题列表，而不是两者同时显示。	自由文本每个副标题的建议文本大小：最多 50 个字符
确认 ID	可选	车辆租赁预订的确认 ID。	自由文本
价格 - 当前价格	有条件地必需	预订的当前价格。如果提供了划掉价格，则必须提供此项。	自由文本
价格 - 划掉价格	可选	预订的原始价格，将在 UI 中划掉。	自由文本
价格标注	可选	价格标注用于显示促销、活动、会员折扣（如果可用）。	自由文本建议文本大小：45 个字符以下（过长的文本可能会显示省略号）
DisplayTimeWindow（可选）- 设置内容在界面上显示的时间窗口
开始时间戳	可选	在此纪元时间戳之后，内容应在界面上显示。如果未设置，内容有资格在界面上显示。	以毫秒为单位的纪元时间戳
结束时间戳	可选	在此纪元时间戳之后，内容不再在界面上显示。如果未设置，内容有资格在界面上显示。	以毫秒为单位的纪元时间戳

图片规格

图片素材的所需规格如下表所示

宽高比	最小像素	建议像素
方形 (1x1) 首选	300x300	1200x1200
横向 (1.91x1)	600x314	1200x628
纵向 (4x5)	480x600	960x1200

宽高比

最小像素

建议像素

方形 (1x1)

首选

300x300

1200x1200

横向 (1.91x1)

600x314

1200x628

纵向 (4x5)

480x600

960x1200

图片必须托管在公共 CDN 上，以便 Google 能够访问它们。

文件格式

PNG、JPG、静态 GIF、WebP

最大文件大小

5120 KB

其他建议

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

时区规格

优先使用 ID（例如，“America/Los_Angeles”）而不是偏移量（例如，“-07:00”）。

用法示例：DateTimeZone.forID("America/Los_Angeles")

内容类别

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

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_FITNESS
TYPE_MEDICAL
TYPE_PARENTING
TYPE_DATING

图片必须托管在公共 CDN 上，以便 Google 能够访问它们。

内容类别使用指南

某些实体，如 ArticleEntity 和 GenericFeaturedEntity，可以使用任何内容类别。对于其他实体，如 EventEntity、EventReservationEntity、PointOfInterestEntity，只有这些类别中的子集符合条件。在填充列表之前，请检查实体类型适用的类别列表。
对于某些内容类别，请使用特定的实体类型，而不是通用实体和内容类别的组合。
- TYPE_MOVIES_AND_TV_SHOWS - 在使用通用实体之前，请查看Watch 集成指南中的实体。
- TYPE_BOOKS - 在使用通用实体之前，请查看EbookEntity。
- TYPE_AUDIOBOOKS - 在使用通用实体之前，请查看AudiobookEntity。
- TYPE_SHOPPING - 在使用通用实体之前，请查看ShoppingEntity。
- TYPE_FOOD_AND_DRINK - 在使用通用实体之前，请查看美食集成指南中的实体。
ContentCategory 字段是可选的，如果内容不属于前面提到的任何类别，则应留空。
如果提供了多个内容类别，请按照与内容的相关性顺序提供，最相关的内容类别放在列表中的第一位。

第 2 步：提供集群数据

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

AppEngageTravelClient 负责发布集群。

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

isServiceAvailable
publishRecommendationClusters
publishFeaturedCluster
publishReservationCluster
publishContinueSearchCluster
publishUserAccountManagementRequest
updatePublishStatus
deleteRecommendationsClusters
deleteFeaturedCluster
deleteReservationCluster
deleteContinueSearchCluster
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 对象的列表。

Kotlin

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

Java

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

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

来自开发者合作伙伴的现有 RecommendationCluster 数据被移除。
请求中的数据被解析并存储在更新的推荐集群中。

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

`publishFeaturedCluster`

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

Kotlin

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

Java

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

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

来自开发者合作伙伴的现有 FeaturedCluster 数据被移除。
请求中的数据被解析并存储在更新的精选集群中。

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

`publishReservationCluster`

此 API 用于发布 ReservationCluster 对象。

Kotlin

client.publishReservationCluster(
    PublishReservationClusterRequest.Builder()
      .setReservationCluster(
        ReservationCluster.Builder()
          .addLodgingReservationEntity(lodgingReservationEntity)
          .addVehicleRentalReservationEntity(vehicleRentalReservationEntity)
          .addTransportationReservationEntity(transportationReservationEntity)
          .addEventReservationEntity(eventReservationEntity)
          .addRestaurantReservationEntity(restaurantReservationEntity)
          .build())
      .build())

Java

client.publishReservationCluster(
            new PublishReservationClusterRequest.Builder()
                .setReservationCluster(
                    new ReservationCluster.Builder()
                        .addLodgingReservationEntity(lodgingReservationEntity)
                        .addVehicleRentalReservationEntity(vehicleRentalReservationEntity)
                        .addTransportationReservationEntity(transportationReservationEntity)
                        .addEventReservationEntity(eventReservationEntity)
                        .addRestaurantReservationEntity(restaurantReservationEntity)
                        .build())
                .build());

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

来自开发者合作伙伴的现有 ReservationCluster 数据被移除。
请求中的数据被解析并存储在更新的预订集群中。

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

`publishContinueSearchCluster`

此 API 用于发布 ContinueSearchCluster 对象的列表。

Kotlin

client.publishContinueSearchCluster(
    PublishContinueSearchClusterRequest.Builder()
      .setContinueSearchCluster(
        ContinueSearchCluster.Builder()
          .addPointOfInterestEntity(entity1)
          .addPointOfInterestEntity(entity2)
          .build())
      .build())

Java

client.publishContinueSearchCluster(
            new PublishContinueSearchClusterRequest.Builder()
                .setContinueSearchCluster(
                    new ContinueSearchCluster.Builder()
                        .addPointOfInterestEntity(entity1)
                        .addPointOfInterestEntity(entity2)
                        .build())
                .build());

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

来自开发者合作伙伴的现有 ContinueSearchCluster 数据被移除。
请求中的数据被解析并存储在更新的“继续搜索”集群中。

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

`publishUserAccountManagementRequest`

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

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

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

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

`deleteReservationCluster`

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

Kotlin

client.deleteReservationCluster()

Java

client.deleteReservationCluster();

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

`deleteUserManagementCluster`

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

Kotlin

client.deleteUserManagementCluster()

Java

client.deleteUserManagementCluster();

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

`deleteContinueSearchCluster`

此 API 用于删除“继续搜索”集群的内容。

Kotlin

client.deleteContinueSearchCluster()

Java

client.deleteContinueSearchCluster();

当服务收到请求时，它会从“继续搜索”集群中删除现有数据。如果发生错误，整个请求将被拒绝，并保留现有状态。

`deleteClusters`

此 API 用于删除给定集群类型的内容。

Kotlin

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

Java

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

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

错误处理

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

Kotlin

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

Java

client.publishRecommendationClusters(
              new PublishRecommendationClustersRequest.Builder()
                  .addRecommendationCluster(...)
                  .build())
          .addOnCompleteListener(
              task -> {
                if (task.isSuccessful()) {
                  // do something
                } else {
                  Exception exception = task.getException();
                  if (exception instanceof AppEngageException) {
                    @AppEngageErrorCode
                    int errorCode = ((AppEngageException) exception).getErrorCode();
                    if (errorCode == AppEngageErrorCode.SERVICE_NOT_FOUND) {
                      // do something
                    }
                  }
                }
              });

错误作为 AppEngageException 返回，其原因包含在错误代码中。

错误代码	错误名称	注意
`1`	`SERVICE_NOT_FOUND`	给定设备上服务不可用。
`2`	`SERVICE_NOT_AVAILABLE`	给定设备上服务可用，但在调用时不可用（例如，它已被明确禁用）。
`3`	`SERVICE_CALL_EXECUTION_FAILURE`	由于线程问题，任务执行失败。在这种情况下，可以重试。
`4`	`SERVICE_CALL_PERMISSION_DENIED`	调用者不允许进行服务调用。
`5`	`SERVICE_CALL_INVALID_ARGUMENT`	请求包含无效数据（例如，超过允许的集群数量）。
`6`	`SERVICE_CALL_INTERNAL`	服务侧出现错误。
`7`	`SERVICE_CALL_RESOURCE_EXHAUSTED`	服务调用过于频繁。

第 3 步：处理广播 intent

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

广播 intent 的目的主要是用于应用重新激活和强制数据同步。广播 intent 不设计为频繁发送。它仅在 Engage 服务确定内容可能已过时（例如，已过时一周）时触发。这样，即使应用长时间未执行，也能更有信心让用户获得新鲜的内容体验。

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

使用 Context.registerReceiver() 动态注册 BroadcastReceiver 类的一个实例。这使得仍在内存中运行的应用能够进行通信。

Kotlin

class AppEngageBroadcastReceiver : BroadcastReceiver(){
  // Trigger recommendation cluster publish when PUBLISH_RECOMMENDATION broadcast
  // is received
  // Trigger featured cluster publish when PUBLISH_FEATURED broadcast is received
  // Trigger continue search cluster publish when PUBLISH_CONTINUE_SEARCH
  // broadcast is received
  // Trigger reservation cluster publish when PUBLISH_RESERVATION broadcast is
  // received
}

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

// Register Recommendation Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(com.google.android.engage.service.Intents.ACTION_PUBLISH_RECOMMENDATION))

// Register Featured Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(com.google.android.engage.service.Intents.ACTION_PUBLISH_FEATURED))

// Register Continue Search Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(com.google.android.engage.travel.service.Intents.ACTION_PUBLISH_CONTINUE_SEARCH))

// Register Reservation Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(com.google.android.engage.travel.service.Intents.ACTION_PUBLISH_RESERVATION))
}

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 continue search cluster publish when PUBLISH_CONTINUE_SEARCH
// broadcast is received

// Trigger reservation cluster publish when PUBLISH_RESERVATION 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 Continue Search Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
new IntentFilter(com.google.android.engage.travel.service.Intents.ACTION_PUBLISH_CONTINUE_SEARCH));

// Register Reservation Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
new IntentFilter(com.google.android.engage.travel.service.Intents.ACTION_PUBLISH_RESERVATION));

}

在您的 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.travel.PUBLISH_CONTINUE_SEARCH" />
      </intent-filter>
      <intent-filter>
         <action android:name="com.google.android.engage.action.travel.PUBLISH_RESERVATION" />
      </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.travel.PUBLISH_CONTINUE_SEARCH 收到此 intent 时，建议启动 publishContinueSearchCluster 调用。
com.google.android.engage.action.travel.PUBLISH_RESERVATION 收到此 intent 时，建议启动 publishReservationCluster 调用。

集成工作流程

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

常见问题解答

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

联系方式

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

后续步骤

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

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

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

集成详情

术语

前期准备

摘要

第 1 步：提供实体数据

GenericFeaturedEntity

ArticleEntity

EventEntity

LodgingEntity

StoreEntity

PointOfInterestEntity

RestaurantReservationEntity

EventReservationEntity

LodgingReservationEntity

TransportationReservationEntity

VehicleRentalReservationEntity

图片规格

时区规格

内容类别

第 2 步：提供集群数据

isServiceAvailable

Kotlin

Java

publishRecommendationClusters

Kotlin

Java

publishFeaturedCluster

Kotlin

Java

publishReservationCluster

Kotlin

Java

publishContinueSearchCluster

Kotlin

Java

publishUserAccountManagementRequest

Kotlin

Java

updatePublishStatus

Kotlin

Java

deleteRecommendationClusters

Kotlin

Java

deleteFeaturedCluster

Kotlin

Java

deleteReservationCluster

Kotlin

Java

deleteUserManagementCluster

Kotlin

Java

deleteContinueSearchCluster

Kotlin

Java

deleteClusters

Kotlin

Java

错误处理

Kotlin

Java

第 3 步：处理广播 intent

Kotlin

Java

集成工作流程

常见问题解答

联系方式

后续步骤

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

`GenericFeaturedEntity`

`ArticleEntity`

`EventEntity`

`LodgingEntity`

`StoreEntity`

`PointOfInterestEntity`

`RestaurantReservationEntity`

`EventReservationEntity`

`LodgingReservationEntity`

`TransportationReservationEntity`

`VehicleRentalReservationEntity`

`isServiceAvailable`

`publishRecommendationClusters`

`publishFeaturedCluster`

`publishReservationCluster`

`publishContinueSearchCluster`

`publishUserAccountManagementRequest`

`updatePublishStatus`

`deleteRecommendationClusters`

`deleteFeaturedCluster`

`deleteReservationCluster`

`deleteUserManagementCluster`

`deleteContinueSearchCluster`

`deleteClusters`