Engage SDK 其他垂直领域：第三方技术集成说明

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

本文档包含开发者合作伙伴集成预订、活动、住宿、名胜、人物以及可能不属于上述任何类别的其他内容的说明。

集成详情

术语

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

推荐集群显示来自单个开发者合作伙伴的个性化建议。它是一个 UI 视图，其中包含来自同一开发者合作伙伴的一组推荐内容。
- ArticleEntity：ArticleEntity 代表一种基于文本的内容推荐，此类内容与多个内容类别相关。ArticleEntity 项目允许开发者提供各种文本和图片内容，并附带更多元数据，与 GenericFeaturedEntity 相比，可以更清楚地向用户阐明信息。例如：营销内容、新闻片段
  
  图 1：在“推荐”集群中显示单个 ArticleEntity 的界面。
- EventEntity：EventEntity 代表将来发生的事件。事件开始时间是需要传达给用户的重要信息。
  
  图 2：在“推荐”集群中显示单个 EventEntity 的界面。
- LodgingEntity：LodgingEntity 代表一种住宿，例如酒店、公寓、短期和长期租赁的度假屋。
  
  图 3：在“推荐”集群中显示单个 LodgingEntity 的界面。
- StoreEntity：StoreEntity 代表商店、餐厅、咖啡馆等。它突出显示餐饮场所或商店作为需要传达给用户的重要信息的内容。
  
  图 4：在“推荐”集群中显示单个 StoreEntity 的界面。
- PointOfInterestEntity：PointOfInterestEntity 代表名胜古迹，例如加油站、活动场所、主题公园、博物馆、旅游景点、远足小径等。它突出显示位置作为需要传达给用户的重要信息的内容。它不应用于住宿、商店或餐饮场所。
  
  图 5：在“推荐”集群中显示单个 PointOfInterestEntity 的界面。
- PersonEntity：PersonEntity 代表一个人。推荐内容可以突出显示健康与健身、体育、约会等类别中的人物。
  
  图 5：在“推荐”集群中显示单个 PersonEntity 的界面。
续播集群在一个 UI 分组中显示了来自多个开发者合作伙伴的用户最近互动过的内容。每个开发者合作伙伴将获准在续播集群中广播最多 10 个实体。

您的续播内容可以采用以下结构
- ArticleEntity：ArticleEntity 代表一种基于文本的内容推荐，此类内容与多个内容类别相关。此实体可用于表示未完成的新闻文章或用户希望从上次离开的地方继续消费的其他内容。例如：营销内容、新闻片段
  
  图 6. 在“续播”集群中显示单个 ArticleEntity 的界面。
- RestaurantReservationEntity：RestaurantReservationEntity 代表餐厅或咖啡馆的预订，可帮助用户跟踪即将到来或正在进行的餐厅预订。
  
  图 7. 在“续播”集群中显示单个 RestaurantReservationEntity 的界面。
- EventReservationEntity：EventReservationEntity 代表事件的预订，并帮助用户跟踪即将到来或正在进行的事件预订。事件可以包括但不限于以下内容
  - 体育赛事，例如足球比赛预订
  - 游戏赛事，例如电竞预订
  - 娱乐活动，例如电影院、音乐会、剧院、图书签售会预订
  - 旅行或名胜古迹预订，例如导游、博物馆门票
  - 社交/研讨会/会议预订
  - 教育/培训课程预订
  图 8. 在“续播”集群中显示单个 EventReservationEntity 的界面。
- LodgingReservationEntity：LodgingEntityReservation 代表旅行住宿的预订，并帮助用户跟踪即将到来或正在进行的酒店或度假租赁预订。
  
  图 9. 在“续播”集群中显示单个 LodgingReservationEntity 的界面。
- TransportationReservationEntity：TransportationReservationEntity 代表任何交通方式的预订，可帮助用户跟踪即将到来或正在进行的航班、渡轮、火车、公共汽车、网约车或游轮预订。
  
  图 10. 在“续播”集群中显示单个 TransportationReservationEntity 的界面。
- VehicleRentalReservationEntity：VehicleRentalReservationEntity 代表车辆租赁预订，可帮助用户跟踪即将到来或正在进行的车辆租赁预订。
  
  图 11. 在“续播”集群中显示单个 VehicleRentalReservationEntity 的界面。
精选集群是一个 UI 视图，在一个 UI 分组中展示了来自许多开发者合作伙伴的所选英雄 GenericFeaturedEntity。只有一个精选集群，它显示在 UI 顶部附近，优先级高于所有推荐集群。每个开发者合作伙伴都可以在精选集群中广播受支持类型的单个实体，其中包含来自多个应用开发者的许多实体（可能是不同类型）。
- GenericFeaturedEntity：GenericFeaturedEntity 与推荐项目不同之处在于，精选项目应用于开发者提供的单个热门内容，并且应代表对用户最重要且最相关的内容。
  
  图 12：在“精选”集群中显示单个英雄 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'
}

摘要

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

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

集群类型	集群限制	集群中实体的最小数量限制	集群中实体的最大数量限制
推荐集群	最多 7 个	最少 1 个	最多 50 个 (`ArticleEntity`、`EventEntity`、`LodgingEntity`、`StoreEntity`、`PointOfInterestEntity` 或 `PersonEntity`)
续播集群	最多 1 个	最少 1 个	最多 20 个 (`ArticleEntity`、`EventReservationEntity`、`LodgingReservationEntity`、`TransportationReservationEntity` 或 `VehicleRentalReservationEntity`)
精选集群	最多 1 个	最少 1 个	最多 20 个 (`GenericFeaturedEntity`)

第 1 步：提供实体数据

SDK 定义了不同的实体来表示每种项目类型。我们支持以下用于“其他”类别的实体

GenericFeaturedEntity
ArticleEntity
EventEntity
LodgingEntity
StoreEntity
PointOfInterestEntity
PersonEntity
RestaurantReservationEntity
EventReservationEntity
LodgingReservationEntity
TransportationReservationEntity
VehicleRentalReservationEntity

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

`GenericFeaturedEntity`

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

`ArticleEntity`

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

`EventEntity`

属性	要求	说明	格式
操作 URI	必需	指向提供方应用中实体的深层链接。注意：您可以将深层链接用于归因。请参阅此常见问题解答	URI
标题	必需	实体的标题。	字符串推荐文本大小：最多 50 个字符
开始时间	必需	事件预计开始时的纪元时间戳。注意：这将以毫秒为单位表示。	纪元时间戳，以毫秒为单位
事件模式	必需	指示事件是虚拟、现场还是两者的字段。	枚举：VIRTUAL、IN_PERSON 或 HYBRID
海报图片	必需	当提供多张图片时，我们只会显示 1 张。推荐的宽高比为 16:9 注意：强烈建议使用图片。如果提供了徽章，请确保图片顶部和底部有 24 dps 的安全空间	请参阅图片规格以获取指导。
位置 - 国家/地区	有条件地必需	事件发生的国家/地区。注意：IN_PERSON 或 HYBRID 事件需要此项。	自由文本推荐文本大小：最多约 20 个字符
位置 - 城市	有条件地必需	事件发生的城市。注意：IN_PERSON 或 HYBRID 事件需要此项。	自由文本推荐文本大小：最多约 20 个字符
位置 - 显示地址	有条件地必需	应向用户显示的事件发生地址或场地名称。注意：IN_PERSON 或 HYBRID 事件需要此项。	自由文本推荐文本大小：最多约 20 个字符
位置 - 街道地址	可选	事件举办地点的街道地址（如果适用）。	自由文本推荐文本大小：最多约 20 个字符
位置 - 州/省	可选	事件举办地点的州或省（如果适用）。	自由文本推荐文本大小：最多约 20 个字符
位置 - 邮政编码	可选	事件举办地点的邮政编码（如果适用）。	自由文本推荐文本大小：最多约 20 个字符
位置 - 社区	可选	事件举办地点的社区（如果适用）。	自由文本推荐文本大小：最多约 20 个字符
结束时间	可选	事件预计结束时的纪元时间戳。注意：这将以毫秒为单位表示。	纪元时间戳，以毫秒为单位
说明	可选	一段描述实体的文本。注意：将向用户显示说明或副标题列表中的一个，而不是两者都显示。	自由文本推荐文本大小：180 个字符
副标题列表	可选	最多 3 个副标题，每个副标题一行文本。注意：将向用户显示说明或副标题列表中的一个，而不是两者都显示。	自由文本每个副标题的推荐文本大小：最多 50 个字符
徽章	可选	每个徽章可以是自由文本（最多 15 个字符）或小图片。
徽章 - 文本	可选	徽章标题注意：徽章需要文本或图片	自由文本推荐文本大小：最多 15 个字符
徽章 - 图片	可选	小图片特殊 UX 处理，例如作为图片/视频缩略图上的徽章叠加层。注意：徽章需要文本或图片	请参阅图片规格以获取指导。
价格 - CurrentPrice	有条件地必需	事件门票/通行证的当前价格。如果提供了删除线价格，则必须提供此项。	自由文本
价格 - StrikethroughPrice	可选	事件门票/通行证的原始价格。	自由文本
价格标注	可选	价格标注，用于突出显示促销、活动、会员折扣（如果可用）。	自由文本推荐文本大小：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（示例 - 聚会）请参阅内容类别部分以获取指导。

`LodgingEntity`

属性	要求	说明	格式
操作 URI	必需	指向提供方应用中实体的深层链接。注意：您可以将深层链接用于归因。请参阅此常见问题解答	URI
标题	必需	实体的标题。	字符串推荐文本大小：最多 50 个字符
海报图片	必需	当提供多张图片时，我们只会显示 1 张。推荐的宽高比为 16:9 注意：如果提供了徽章，请确保图片顶部和底部有 24 dps 的安全空间	请参阅图片规格以获取指导。
位置 - 国家/地区	必需	住宿所在的国家/地区。	自由文本推荐文本大小：最多约 20 个字符
位置 - 城市	必需	住宿所在的城市。	自由文本推荐文本大小：最多约 20 个字符
位置 - 显示地址	必需	将向用户显示的住宿地址。	自由文本推荐文本大小：最多约 20 个字符
位置 - 街道地址	可选	住宿的街道地址（如果适用）。	自由文本推荐文本大小：最多约 20 个字符
位置 - 州/省	可选	住宿所在的州或省（如果适用）。	自由文本推荐文本大小：最多约 20 个字符
位置 - 邮政编码	可选	住宿的邮政编码（如果适用）。	自由文本推荐文本大小：最多约 20 个字符
位置 - 社区	可选	住宿所在的社区（如果适用）。	自由文本推荐文本大小：最多约 20 个字符
徽章	可选	每个徽章可以是自由文本（最多 15 个字符）或小图片。
徽章 - 文本	可选	徽章标题注意：徽章需要文本或图片	自由文本推荐文本大小：最多 15 个字符
徽章 - 图片	可选	小图片特殊 UX 处理，例如作为图片/视频缩略图上的徽章叠加层。注意：徽章需要文本或图片	请参阅图片规格以获取指导。
说明	可选	一段描述实体的文本。注意：将向用户显示说明或副标题列表中的一个，而不是两者都显示。	自由文本推荐文本大小：180 个字符
副标题列表	可选	最多 3 个副标题，每个副标题一行文本。注意：将向用户显示说明或副标题列表中的一个，而不是两者都显示。	自由文本每个副标题的推荐文本大小：最多 50 个字符
可用时间窗口 - 开始时间	可选	住宿预计开放/可用时的纪元时间戳，以毫秒为单位。	纪元时间戳，以毫秒为单位
可用时间窗口 - 结束时间	可选	住宿预计开放/可用截止时的纪元时间戳，以毫秒为单位。	纪元时间戳，以毫秒为单位
评分 - 最大值	可选	评分等级的最大值。如果也提供了评分的当前值，则必须提供此项。	数字 >= 0.0
评分 - 当前值	可选	评分等级的当前值。如果也提供了评分的最大值，则必须提供此项。	数字 >= 0.0
评分 - 计数	可选	住宿的评分数量。注意：如果您的应用控制计数如何向用户显示，请提供此字段。使用简洁的字符串。例如，如果计数为 1,000,000，请考虑使用 1M 等缩写，以免在较小的显示尺寸上截断计数。	字符串
评分 - 计数值	可选	住宿的评分数量。注意：如果您不自行处理显示缩写逻辑，请提供此字段。如果“计数”和“计数值”都存在，则向用户显示“计数”。	长整型
价格 - CurrentPrice	有条件地必需	住宿的当前价格。如果提供了删除线价格，则必须提供此项。	自由文本
价格 - StrikethroughPrice	可选	住宿的原始价格，将在界面中显示为删除线。	自由文本
价格标注	可选	价格标注，用于突出显示促销、活动、会员折扣（如果可用）。	自由文本推荐文本大小：45 个字符以内（文本过长可能会显示省略号）

`StoreEntity`

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

属性	要求	说明	格式
海报图片	必需	必须提供至少一张图片。	请参阅图片规格以获取指导。
操作 URI	必需	指向提供方应用中实体的深层链接。注意：您可以将深层链接用于归因。请参阅此常见问题解答	URI
标题	可选	商店名称。	自由文本推荐文本大小：45 个字符以内（文本过长可能会显示省略号）
位置	可选	商店位置。	自由文本推荐文本大小：45 个字符以内（文本过长可能会显示省略号）
标注	可选	标注，用于突出显示商店的促销、活动或更新（如果可用）。	自由文本推荐文本大小：45 个字符以内（文本过长可能会显示省略号）
标注细则	可选	标注的细则文本。	自由文本推荐文本大小：45 个字符以内（文本过长可能会显示省略号）
说明	可选	商店描述。	自由文本推荐文本大小：90 个字符以内（文本过长可能会显示省略号）
评分 - 最大值	可选	评分等级的最大值。如果也提供了评分的当前值，则必须提供此项。	数字 >= 0.0
评分 - 当前值	可选	评分等级的当前值。如果也提供了评分的最大值，则必须提供此项。	数字 >= 0.0
评分 - 计数	可选	住宿的评分数量。注意：如果您的应用希望控制此项如何向用户显示，请提供此字段。提供可向用户显示的简洁字符串。例如，如果计数为 1,000,000，请考虑使用 1M 等缩写，以免在较小的显示尺寸上截断。	字符串
评分 - 计数值	可选	住宿的评分数量。注意：如果您不想自行处理显示缩写逻辑，请提供此字段。如果“计数”和“计数值”都存在，我们将使用“计数”向用户显示。	长整型

`PointOfInterestEntity`

属性	要求	说明	格式
操作 URI	必需	指向提供方应用中实体的深层链接。注意：您可以将深层链接用于归因。请参阅此常见问题解答	URI
标题	必需	实体的标题。	字符串推荐文本大小：最多 50 个字符
海报图片	必需	当提供多张图片时，我们只会显示 1 张。推荐的宽高比为 16:9 注意：强烈建议使用图片。如果提供了徽章，请确保图片顶部和底部有 24 dps 的安全空间	请参阅图片规格以获取指导。
位置 - 国家/地区	必需	名胜古迹所在的国家/地区。	自由文本推荐文本大小：最多约 20 个字符
位置 - 城市	必需	名胜古迹所在的城市。	自由文本推荐文本大小：最多约 20 个字符
位置 - 显示地址	必需	将向用户显示的名胜古迹地址。	自由文本推荐文本大小：最多约 20 个字符
位置 - 街道地址	可选	名胜古迹的街道地址（如果适用）。	自由文本推荐文本大小：最多约 20 个字符
位置 - 州/省	可选	名胜古迹所在的州或省（如果适用）。	自由文本推荐文本大小：最多约 20 个字符
位置 - 邮政编码	可选	名胜古迹的邮政编码（如果适用）。	自由文本推荐文本大小：最多约 20 个字符
位置 - 社区	可选	名胜古迹所在的社区（如果适用）。	自由文本推荐文本大小：最多约 20 个字符
可用时间窗口 - 开始时间	可选	名胜古迹预计开放/可用时的纪元时间戳，以毫秒为单位。	纪元时间戳，以毫秒为单位
可用时间窗口 - 结束时间	可选	名胜古迹预计开放/可用截止时的纪元时间戳，以毫秒为单位。	纪元时间戳，以毫秒为单位
徽章	可选	每个徽章可以是自由文本（最多 15 个字符）或小图片。
徽章 - 文本	可选	徽章标题注意：徽章需要文本或图片	自由文本推荐文本大小：最多 15 个字符
徽章 - 图片	可选	小图片特殊 UX 处理，例如作为图片/视频缩略图上的徽章叠加层。注意：徽章需要文本或图片	请参阅图片规格以获取指导。
说明	可选	一段描述实体的文本。注意：将向用户显示说明或副标题列表中的一个，而不是两者都显示。	自由文本推荐文本大小：180 个字符
副标题列表	可选	最多 3 个副标题，每个副标题一行文本。注意：将向用户显示说明或副标题列表中的一个，而不是两者都显示。	自由文本每个副标题的推荐文本大小：最多 50 个字符
评分 - 最大值	可选	评分等级的最大值。如果也提供了评分的当前值，则必须提供此项。	数字 >= 0.0
评分 - 当前值	可选	评分等级的当前值。如果也提供了评分的最大值，则必须提供此项。	数字 >= 0.0
评分 - 计数	可选	名胜古迹的评分数量。注意：如果您的应用控制计数如何向用户显示，请提供此字段。使用简洁的字符串。例如，如果计数为 1,000,000，请考虑使用 1M 等缩写，以免在较小的显示尺寸上截断计数。	字符串
评分 - 计数值	可选	名胜古迹的评分数量。注意：如果您不自行处理显示缩写逻辑，请提供此字段。如果“计数”和“计数值”都存在，则向用户显示“计数”。	长整型
价格 - CurrentPrice	有条件地必需	名胜古迹门票/通行证的当前价格。如果提供了删除线价格，则必须提供此项。	自由文本
价格 - StrikethroughPrice	可选	名胜古迹门票/通行证的原始价格。	自由文本
价格标注	可选	价格标注，用于突出显示促销、活动、会员折扣（如果可用）。	自由文本推荐文本大小：45 个字符以内（文本过长可能会显示省略号）
内容类别	可选	描述实体中内容的类别。	符合条件的枚举列表 TYPE_TRAVEL_AND_LOCAL TYPE_MOVIES_AND_TV_SHOWS（示例 - 剧院） TYPE_MEDICAL（示例 - 医院） TYPE_EDUCATION（示例 - 学校） TYPE_SPORTS（示例 - 体育场）请参阅内容类别部分以获取指导。

`PersonEntity`

属性	要求	说明	格式
操作 URI	必需	指向提供方应用中实体的深层链接。注意：您可以将深层链接用于归因。请参阅此常见问题解答	URI
个人资料 - 姓名	必需	个人资料姓名或 ID 或句柄，例如“John Doe”、“@TeamPixel”等。	字符串推荐文本大小：最多 50 个字符
个人资料 - 头像	必需	用户的个人资料图片或头像。注意：必须是 1:1 的方形图片。	请参阅图片规格以获取指导。
个人资料 - 附加文本	可选	自由文本，例如个人资料句柄。	自由文本推荐文本大小：最多 15 个字符
个人资料 - 附加图片	可选	小图片，例如验证徽章。	请参阅图片规格以获取指导。
标题图片	可选	当提供多张图片时，我们只会显示 1 张。推荐的宽高比为 16:9 注意：强烈建议使用图片。如果提供了徽章，请确保图片顶部和底部有 24 dps 的安全空间	请参阅图片规格以获取指导。
人气 - 计数	可选	表示关注者数量或人气值，例如“3.7 M”。注意：如果同时提供了“计数”和“计数值”，将使用“计数”	字符串推荐文本大小：计数 + 标签组合后最多 20 个字符
人气 - 计数值	可选	关注者数量或人气值。注意：如果您的应用不想处理如何针对不同显示尺寸优化大数字的逻辑，请提供“计数值”。如果同时提供了“计数”和“计数值”，将使用“计数”。	长整型
人气 - 标签	可选	指示人气标签是什么。例如“喜欢”。	字符串推荐文本大小：计数 + 标签组合后最多 20 个字符
人气 - 视觉	可选	指示互动内容是什么。例如 - 显示“喜欢”图标、表情符号的图片。可以提供多张图片，但并非所有图片都可能在所有外形规格上显示。注意：必须是 1:1 的方形图片	请参阅图片规格以获取指导。
评分 - 最大值	必需	评分等级的最大值。如果也提供了评分的当前值，则必须提供此项。	数字 >= 0.0
评分 - 当前值	必需	评分等级的当前值。如果也提供了评分的最大值，则必须提供此项。	数字 >= 0.0
评分 - 计数	可选	实体的评分数量。注意：如果您的应用希望控制此项如何向用户显示，请提供此字段。提供可向用户显示的简洁字符串。例如，如果计数为 1,000,000，请考虑使用 1M 等缩写，以免在较小的显示尺寸上截断。	字符串
评分 - 计数值	可选	实体的评分数量。注意：如果您不想自行处理显示缩写逻辑，请提供此字段。如果“计数”和“计数值”都存在，我们将使用“计数”向用户显示。	长整型
位置 - 国家/地区	可选	该人物所在或服务的国家/地区。	自由文本推荐文本大小：最多约 20 个字符
位置 - 城市	可选	该人物所在或服务的城市。	自由文本推荐文本大小：最多约 20 个字符
位置 - 显示地址	可选	该人物所在或服务的地址将显示给用户。	自由文本推荐文本大小：最多约 20 个字符
位置 - 街道地址	可选	该人物所在或服务的街道地址（如果适用）。	自由文本推荐文本大小：最多约 20 个字符
位置 - 州/省	可选	该人物所在或服务的州/省（如果适用）。	自由文本推荐文本大小：最多约 20 个字符
位置 - 邮政编码	可选	该人物所在或服务的邮政编码（如果适用）。	自由文本推荐文本大小：最多约 20 个字符
位置 - 社区	可选	该人物所在或服务的社区（如果适用）。	自由文本推荐文本大小：最多约 20 个字符
徽章	可选	每个徽章可以是自由文本（最多 15 个字符）或小图片。
徽章 - 文本	可选	徽章标题注意：徽章需要文本或图片	自由文本推荐文本大小：最多 15 个字符
徽章 - 图片	可选	小图片特殊 UX 处理，例如作为图片/视频缩略图上的徽章叠加层。注意：徽章需要文本或图片	请参阅图片规格以获取指导。
说明	可选	一段描述实体的文本。注意：将向用户显示说明或副标题列表中的一个，而不是两者都显示。	自由文本推荐文本大小：180 个字符
副标题列表	可选	最多 3 个副标题，每个副标题一行文本。注意：将向用户显示说明或副标题列表中的一个，而不是两者都显示。	自由文本每个副标题的推荐文本大小：最多 50 个字符
内容类别	可选	描述实体中内容的类别。	符合条件的枚举列表 TYPE_HEALTH_AND_FITNESS（示例 - 瑜伽/健身教练） TYPE_HOME_AND_AUTO（示例 - 水管工） TYPE_SPORTS（示例 - 运动员） TYPE_DATING 请参阅内容类别部分以获取指导。

`RestaurantReservationEntity`

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

`EventReservationEntity`

属性	要求	说明	格式
操作 URI	必需	指向提供方应用中实体的深层链接。注意：您可以将深层链接用于归因。请参阅此常见问题解答	URI
标题	必需	实体的标题。	字符串推荐文本大小：最多 50 个字符
开始时间	必需	事件预计开始时的纪元时间戳。注意：这将以毫秒为单位表示。	纪元时间戳，以毫秒为单位
事件模式	必需	指示事件是虚拟、现场还是两者的字段。	枚举：VIRTUAL、IN_PERSON 或 HYBRID
位置 - 国家/地区	有条件地必需	事件发生的国家/地区。注意：IN_PERSON 或 HYBRID 事件需要此项。	自由文本推荐文本大小：最多约 20 个字符
位置 - 城市	有条件地必需	事件发生的城市。注意：IN_PERSON 或 HYBRID 事件需要此项。	自由文本推荐文本大小：最多约 20 个字符
位置 - 显示地址	有条件地必需	应向用户显示的事件发生地址或场地名称。注意：IN_PERSON 或 HYBRID 事件需要此项。	自由文本推荐文本大小：最多约 20 个字符
位置 - 街道地址	可选	事件举办地点的街道地址（如果适用）。	自由文本推荐文本大小：最多约 20 个字符
位置 - 州/省	可选	事件举办地点的州或省（如果适用）。	自由文本推荐文本大小：最多约 20 个字符
位置 - 邮政编码	可选	事件举办地点的邮政编码（如果适用）。	自由文本推荐文本大小：最多约 20 个字符
位置 - 社区	可选	事件举办地点的社区（如果适用）。	自由文本推荐文本大小：最多约 20 个字符
海报图片	可选	当提供多张图片时，我们只会显示 1 张。推荐的宽高比为 16:9 注意：强烈建议使用图片。如果提供了徽章，请确保图片顶部和底部有 24 dps 的安全空间	请参阅图片规格以获取指导。
结束时间	可选	事件预计结束时的纪元时间戳。注意：这将以毫秒为单位表示。	纪元时间戳，以毫秒为单位
服务提供商 - 姓名	可选	服务提供商的名称。注意：服务提供商需要文本或图片。	自由文本。例如，活动组织者/旅行团的名称
服务提供商 - 图片	可选	服务提供商的徽标/图片。注意：服务提供商需要文本或图片。	请参阅图片规格以获取指导。
说明	可选	一段描述实体的文本。注意：将向用户显示说明或副标题列表中的一个，而不是两者都显示。	自由文本推荐文本大小：180 个字符
副标题列表	可选	最多 3 个副标题，每个副标题一行文本。注意：将向用户显示说明或副标题列表中的一个，而不是两者都显示。	自由文本每个副标题的推荐文本大小：最多 50 个字符
徽章	可选	每个徽章可以是自由文本（最多 15 个字符）或小图片。
徽章 - 文本	可选	徽章标题注意：徽章需要文本或图片	自由文本推荐文本大小：最多 15 个字符
徽章 - 图片	可选	小图片特殊 UX 处理，例如作为图片/视频缩略图上的徽章叠加层。注意：徽章需要文本或图片	请参阅图片规格以获取指导。
预订 ID	可选	事件预订的预订 ID。	自由文本
价格 - CurrentPrice	有条件地必需	事件门票/通行证的当前价格。如果提供了删除线价格，则必须提供此项。	自由文本
价格 - StrikethroughPrice	可选	事件门票/通行证的原始价格。	自由文本
价格标注	可选	价格标注，用于突出显示促销、活动、会员折扣（如果可用）。	自由文本推荐文本大小：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（示例 - 聚会）请参阅内容类别部分以获取指导。

`LodgingReservationEntity`

属性	要求	说明	格式
操作 URI	必需	指向提供方应用中实体的深层链接。注意：您可以将深层链接用于归因。请参阅此常见问题解答	URI
标题	必需	实体的标题。	自由文本。例如，“您的住宿从 12 月 12 日开始” 推荐文本大小：最多 50 个字符
入住时间	必需	预订入住时间的纪元时间戳，以毫秒为单位。	纪元时间戳，以毫秒为单位
退房时间	必需	预订退房时间的纪元时间戳，以毫秒为单位。	纪元时间戳，以毫秒为单位
位置 - 国家/地区	必需	住宿所在的国家/地区。	自由文本推荐文本大小：最多约 20 个字符
位置 - 城市	必需	住宿所在的城市。	自由文本推荐文本大小：最多约 20 个字符
位置 - 显示地址	必需	将向用户显示的住宿地址。	自由文本推荐文本大小：最多约 20 个字符
位置 - 街道地址	可选	住宿的街道地址（如果适用）。	自由文本推荐文本大小：最多约 20 个字符
位置 - 州/省	可选	住宿所在的州或省（如果适用）。	自由文本推荐文本大小：最多约 20 个字符
位置 - 邮政编码	可选	住宿的邮政编码（如果适用）。	自由文本推荐文本大小：最多约 20 个字符
位置 - 社区	可选	住宿所在的社区（如果适用）。	自由文本推荐文本大小：最多约 20 个字符
海报图片	可选	当提供多张图片时，我们只会显示 1 张。推荐的宽高比为 16:9 注意：如果提供了徽章，请确保图片顶部和底部有 24 dps 的安全空间	请参阅图片规格以获取指导。
说明	可选	一段描述实体的文本。注意：将向用户显示说明或副标题列表中的一个，而不是两者都显示。	自由文本推荐文本大小：180 个字符
副标题列表	可选	最多 3 个副标题，每个副标题一行文本。注意：将向用户显示说明或副标题列表中的一个，而不是两者都显示。	自由文本每个副标题的推荐文本大小：最多 50 个字符
预订 ID	可选	住宿预订的预订 ID。	自由文本
评分 - 最大值	可选	评分等级的最大值。如果也提供了评分的当前值，则必须提供此项。	数字 >= 0.0
评分 - 当前值	可选	评分等级的当前值。如果也提供了评分的最大值，则必须提供此项。	数字 >= 0.0
评分 - 计数	可选	住宿的评分数量。注意：如果您的应用希望控制此项如何向用户显示，请提供此字段。提供可向用户显示的简洁字符串。例如，如果计数为 1,000,000，请考虑使用 1M 等缩写，以免在较小的显示尺寸上截断。	字符串
评分 - 计数值	可选	住宿的评分数量。注意：如果您不想自行处理显示缩写逻辑，请提供此字段。如果“计数”和“计数值”都存在，我们将使用“计数”向用户显示。	长整型
价格 - CurrentPrice	有条件地必需	住宿的当前价格。如果提供了删除线价格，则必须提供此项。	自由文本
价格 - StrikethroughPrice	可选	住宿的原始价格，将在界面中显示为删除线。	自由文本
价格标注	可选	价格标注，用于突出显示促销、活动、会员折扣（如果可用）。	自由文本推荐文本大小：45 个字符以内（文本过长可能会显示省略号）

`TransportationReservationEntity`

属性	要求	说明	格式
操作 URI	必需	指向提供方应用中实体的深层链接。注意：您可以将深层链接用于归因。请参阅此常见问题解答	URI
标题	必需	实体的标题。	自由文本。例如，“SFO 到 SAN” 推荐文本大小：最多 50 个字符
交通类型	必需	预订的交通方式/类型。	枚举：航班、火车、公共汽车或渡轮
出发时间	必需	出发时间的纪元时间戳，以毫秒为单位。	纪元时间戳，以毫秒为单位
到达时间	必需	到达时间的纪元时间戳，以毫秒为单位。	纪元时间戳，以毫秒为单位
出发地点 - 国家/地区	可选	出发国家/地区。	自由文本推荐文本大小：最多约 20 个字符
出发地点 - 城市	可选	出发城市。	自由文本推荐文本大小：最多约 20 个字符
出发地点 - 显示地址	可选	将向用户显示的出发地点。	自由文本推荐文本大小：最多约 20 个字符
出发地点 - 街道地址	可选	出发地点的街道地址（如果适用）。	自由文本推荐文本大小：最多约 20 个字符
出发地点 - 州/省	可选	出发地点的州或省（如果适用）。	自由文本推荐文本大小：最多约 20 个字符
出发地点 - 邮政编码	可选	出发地点的邮政编码（如果适用）。	自由文本推荐文本大小：最多约 20 个字符
出发地点 - 社区	可选	出发地点的社区（如果适用）。	自由文本推荐文本大小：最多约 20 个字符
到达地点 - 国家/地区	可选	到达国家/地区。	自由文本推荐文本大小：最多约 20 个字符
到达地点 - 城市	可选	到达城市。	自由文本推荐文本大小：最多约 20 个字符
到达地点 - 显示地址	可选	将向用户显示的到达地点。	自由文本推荐文本大小：最多约 20 个字符
到达地点 - 街道地址	可选	到达地点的街道地址（如果适用）。	自由文本推荐文本大小：最多约 20 个字符
到达地点 - 州/省	可选	到达地点的州或省（如果适用）。	自由文本推荐文本大小：最多约 20 个字符
到达地点 - 邮政编码	可选	到达地点的邮政编码（如果适用）。	自由文本推荐文本大小：最多约 20 个字符
到达地点 - 社区	可选	到达地点的社区（如果适用）。	自由文本推荐文本大小：最多约 20 个字符
服务提供商 - 姓名	可选	服务提供商的名称。注意：服务提供商需要文本或图片。	自由文本。例如，航空公司名称
服务提供商 - 图片	可选	服务提供商的徽标/图片。注意：服务提供商需要文本或图片。	请参阅图片规格以获取指导。
海报图片	可选	当提供多张图片时，我们只会显示 1 张。推荐的宽高比为 16:9	请参阅图片规格以获取指导。
说明	可选	一段描述实体的文本。注意：将向用户显示说明或副标题列表中的一个，而不是两者都显示。	自由文本推荐文本大小：180 个字符
副标题列表	可选	最多 3 个副标题，每个副标题一行文本。注意：将向用户显示说明或副标题列表中的一个，而不是两者都显示。	自由文本每个副标题的推荐文本大小：最多 50 个字符
预订 ID	可选	交通预订的预订 ID。	自由文本
价格 - CurrentPrice	有条件地必需	预订的当前价格。如果提供了删除线价格，则必须提供此项。	自由文本
价格 - StrikethroughPrice	可选	预订的原始价格，将在界面中显示为删除线。	自由文本
价格标注	可选	价格标注，用于突出显示促销、活动、会员折扣（如果可用）。	自由文本推荐文本大小：45 个字符以内（文本过长可能会显示省略号）
交通编号	必需	航班号、公共汽车号、火车号或渡轮/游轮号。	自由文本
登机时间	必需	预订登机时间的纪元时间戳（如果适用）	纪元时间戳，以毫秒为单位

`VehicleRentalReservationEntity`

属性	要求	说明	格式
操作 URI	必需	指向提供方应用中实体的深层链接。注意：您可以将深层链接用于归因。请参阅此常见问题解答	URI
标题	必需	实体的标题。	自由文本。例如，“Avis Union Square SF” 推荐文本大小：最多 50 个字符
取车时间	必需	预订取车时间的纪元时间戳。	纪元时间戳，以毫秒为单位
还车时间	可选	预订还车时间的纪元时间戳。	纪元时间戳，以毫秒为单位
取车地址 - 国家/地区	可选	取车地点的国家/地区。	自由文本推荐文本大小：最多约 20 个字符
取车地址 - 城市	可选	取车地点的城市。	自由文本推荐文本大小：最多约 20 个字符
取车地址 - 显示地址	可选	将向用户显示的取车地点。	自由文本推荐文本大小：最多约 20 个字符
取车地址 - 街道地址	可选	取车地点的街道地址（如果适用）。	自由文本推荐文本大小：最多约 20 个字符
取车地址 - 州/省	可选	取车地点的州或省（如果适用）。	自由文本推荐文本大小：最多约 20 个字符
取车地址 - 邮政编码	可选	取车地点的邮政编码（如果适用）。	自由文本推荐文本大小：最多约 20 个字符
取车地址 - 社区	可选	取车地点的社区（如果适用）。	自由文本推荐文本大小：最多约 20 个字符
还车地址 - 国家/地区	可选	还车地点的国家/地区。	自由文本推荐文本大小：最多约 20 个字符
还车地址 - 城市	可选	还车地点的城市。	自由文本推荐文本大小：最多约 20 个字符
还车地址 - 显示地址	可选	将向用户显示的还车地点。	自由文本推荐文本大小：最多约 20 个字符
还车地址 - 街道地址	可选	还车地点的街道地址（如果适用）。	自由文本推荐文本大小：最多约 20 个字符
还车地址 - 州/省	可选	还车地点的州或省（如果适用）。	自由文本推荐文本大小：最多约 20 个字符
还车地址 - 邮政编码	可选	还车地点的邮政编码（如果适用）。	自由文本推荐文本大小：最多约 20 个字符
还车地址 - 社区	可选	还车地点的社区（如果适用）。	自由文本推荐文本大小：最多约 20 个字符
服务提供商 - 姓名	可选	服务提供商的名称。注意：服务提供商需要文本或图片。	自由文本。例如，“Avis 租车”
服务提供商 - 图片	可选	服务提供商的徽标/图片。注意：服务提供商需要文本或图片。	请参阅图片规格以获取指导。
海报图片	可选	当提供多张图片时，我们只会显示 1 张。推荐的宽高比为 16:9	请参阅图片规格以获取指导。
说明	可选	一段描述实体的文本。注意：将向用户显示说明或副标题列表中的一个，而不是两者都显示。	自由文本推荐文本大小：180 个字符
副标题列表	可选	最多 3 个副标题，每个副标题一行文本。注意：将向用户显示说明或副标题列表中的一个，而不是两者都显示。	自由文本每个副标题的推荐文本大小：最多 50 个字符
确认 ID	可选	车辆租赁预订的确认 ID。	自由文本
价格 - CurrentPrice	有条件地必需	预订的当前价格。如果提供了删除线价格，则必须提供此项。	自由文本
价格 - StrikethroughPrice	可选	预订的原始价格，将在界面中显示为删除线。	自由文本
价格标注	可选	价格标注，用于突出显示促销、活动、会员折扣（如果可用）。	自由文本推荐文本大小：45 个字符以内（文本过长可能会显示省略号）

图片规格

图片资源所需规格如下表所示

宽高比	最小像素	推荐像素
方形 (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% 的区域。
使用透明背景，以便图片可以在深色和浅色主题设置中正确显示。

内容类别

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

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），并定期或按事件（例如，每次用户打开应用或用户刚将某物添加到购物车时）调度。

AppEngagePublishClient 负责发布集群。

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

isServiceAvailable
publishRecommendationClusters
publishFeaturedCluster
publishContinuationCluster
publishUserAccountManagementRequest
updatePublishStatus
deleteRecommendationsClusters
deleteFeaturedCluster
deleteContinuationCluster
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 数据将被移除。
请求中的数据将被解析并存储在更新的精选集群中。

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

`publishContinuationCluster`

此 API 用于发布 ContinuationCluster 对象。

Kotlin

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

Java

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

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

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

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

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

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

`deleteContinuationCluster`

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

Kotlin

client.deleteContinuationCluster()

Java

client.deleteContinuationCluster();

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

`deleteUserManagementCluster`

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

Kotlin

client.deleteUserManagementCluster()

Java

client.deleteUserManagementCluster();

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

`deleteClusters`

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

Kotlin

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

Java

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

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

错误处理

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

Kotlin

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

Java

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

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

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

第 3 步：处理广播 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 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))
}

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 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 商店后，您的推荐、精选和续播集群可能会发布并向用户显示。

Engage SDK 其他垂直领域：第三方技术集成说明 使用收藏集保持井然有序 根据您的偏好保存和分类内容。

集成详情

术语

准备工作

摘要

第 1 步：提供实体数据

GenericFeaturedEntity

ArticleEntity

EventEntity

LodgingEntity

StoreEntity

PointOfInterestEntity

PersonEntity

RestaurantReservationEntity

EventReservationEntity

LodgingReservationEntity

TransportationReservationEntity

VehicleRentalReservationEntity

图片规格

内容类别

第 2 步：提供集群数据

isServiceAvailable

Kotlin

Java

publishRecommendationClusters

Kotlin

Java

publishFeaturedCluster

Kotlin

Java

publishContinuationCluster

Kotlin

Java

publishUserAccountManagementRequest

Kotlin

Java

updatePublishStatus

Kotlin

Java

deleteRecommendationClusters

Kotlin

Java

deleteFeaturedCluster

Kotlin

Java

deleteContinuationCluster

Kotlin

Java

deleteUserManagementCluster

Kotlin

Java

deleteClusters

Kotlin

Java

错误处理

Kotlin

Java

第 3 步：处理广播 Intent

Kotlin

Java

集成工作流

常见问题解答

联系方式

后续步骤

Engage SDK 其他垂直领域：第三方技术集成说明

`GenericFeaturedEntity`

`ArticleEntity`

`EventEntity`

`LodgingEntity`

`StoreEntity`

`PointOfInterestEntity`

`PersonEntity`

`RestaurantReservationEntity`

`EventReservationEntity`

`LodgingReservationEntity`

`TransportationReservationEntity`

`VehicleRentalReservationEntity`

`isServiceAvailable`

`publishRecommendationClusters`

`publishFeaturedCluster`

`publishContinuationCluster`

`publishUserAccountManagementRequest`

`updatePublishStatus`

`deleteRecommendationClusters`

`deleteFeaturedCluster`

`deleteContinuationCluster`

`deleteUserManagementCluster`

`deleteClusters`