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

Google 正在构建一个设备上的界面，该界面按垂直领域组织用户的应用，并为个性化应用内容的消费和发现提供全新的沉浸式体验。此全屏体验为开发者合作伙伴提供了一个机会，可以在其应用之外的专用渠道中展示其最佳的丰富内容。

本文档包含开发者合作伙伴集成新内容（如预订、活动、住宿、景点、人员和其他内容）的说明，这些内容可能不属于这些类别中的任何一个，使用 Engage SDK 来填充此新的界面区域。

集成详情

术语

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

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

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

摘要

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

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

聚类类型	聚类限制	聚类中的最小实体限制	聚类中的最大实体限制
推荐聚类	最多 5 个	至少 5 个	最多 25 个（`ArticleEntity`、`EventEntity`、`LodgingEntity`、`StoreEntity`、`PointOfInterestEntity` 或 `PersonEntity`）
Continuation 聚类	最多 1 个	至少 1 个	最多 10 个（`ArticleEntity`、`EventReservationEntity`、`LodgingReservationEntity`、`TransportationReservationEntity` 或 `VehicleRentalReservationEntity`）
Featured 聚类	最多 1 个	至少 1 个	最多 10 个（`GenericFeaturedEntity`）

步骤 1：提供实体数据

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

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

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

`GenericFeaturedEntity`

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

`ArticleEntity`

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

`EventEntity`

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

`LodgingEntity`

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

`StoreEntity`

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

属性	要求	描述	格式
海报图片	必填	必须提供至少一张图片。	有关指南，请参阅图片规格。
Action Uri	必填	指向提供商应用中实体的深层链接。注意：您可以使用深层链接进行归因。请参阅此常见问题解答	Uri
标题	可选	商店的名称。	自由文本推荐文本大小：少于 45 个字符（过长的文本可能会显示省略号）
位置	可选	商店的位置。	自由文本推荐文本大小：少于 45 个字符（过长的文本可能会显示省略号）
宣传语	可选	如有，可使用宣传语来宣传商店的促销活动、活动或更新。	自由文本推荐文本大小：少于 45 个字符（过长的文本可能会显示省略号）
宣传语细则	可选	宣传语的细则文本。	自由文本推荐文本大小：少于 45 个字符（过长的文本可能会显示省略号）
描述	可选	商店的描述。	自由文本推荐文本大小：少于 90 个字符（过长的文本可能会显示省略号）
评分 - 最大值	可选	评分量表的最大值。如果也提供了评分的当前值，则必须提供。	数字 >= 0.0
评分 - 当前值	可选	评分量表的当前值。如果也提供了评分的最大值，则必须提供。	数字 >= 0.0
评分 - 计数	可选	住宿评分的计数。注意：如果您的应用想要控制如何向用户显示此信息，请提供此字段。提供可以显示给用户的简洁字符串。例如，如果计数为 1,000,000，请考虑使用 1M 之类的缩写，这样在较小的显示尺寸上就不会被截断。	字符串
评分 - 计数值	可选	住宿评分的计数。注意：如果您不想自己处理显示缩写逻辑，请提供此字段。如果同时存在 Count 和 Count Value，我们将使用 Count 显示给用户	长整型

`PointOfInterestEntity`

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

`PersonEntity`

属性	要求	描述	格式
Action Uri	必填	指向提供商应用中实体的深层链接。注意：您可以使用深层链接进行归因。请参阅此常见问题解答	Uri
个人资料 - 名称	必填	个人资料名称或 ID 或句柄，例如“John Doe”、“@TeamPixel”等。	字符串推荐文本大小：最大 50 个字符
个人资料 - 头像	必填	用户的个人资料图片或头像图片。注意：必须是正方形 1:1 图片。	有关指南，请参阅图片规格。
个人资料 - 附加文本	可选	自由文本，例如个人资料句柄。	自由文本推荐文本大小：最多 15 个字符
个人资料 - 附加图片	可选	小图片，例如已验证徽章。	有关指南，请参阅图片规格。
标题图片	可选	提供多个图片时，我们只会显示 1 张图片。建议纵横比为 16:9 注意：强烈建议使用图片。如果提供了徽章，请确保图片顶部和底部各留出 24 dp 的安全空间	有关指南，请参阅图片规格。
受欢迎程度 - 计数	可选	表示标题图片。应与个人资料图片不同。如果存在其他图片可以帮助突出显示此人（例如他们的作品），则可以使用此图片。注意：必须是 16:9 图片。如果提供了徽章，请确保图像顶部和底部的安全空间为 24 dp	字符串推荐文本大小：计数 + 标签组合最多 20 个字符
受欢迎程度 - 计数值	可选	关注者数量或受欢迎程度值。注意：如果您的应用不想处理如何针对不同显示尺寸优化大数字的逻辑，请提供 Count Value。如果同时提供了 Count 和 Count Value，则将使用 Count。	长整型
受欢迎程度 - 标签	可选	指示受欢迎程度标签是什么。例如 -“点赞”。	字符串推荐文本大小：计数 + 标签组合最多 20 个字符
受欢迎程度 - 视觉效果	可选	指示交互的用途。例如 - 显示点赞图标的图片、表情符号。可以提供多个图片，但并非所有图片在所有外形规格上都可能显示。注意：必须是正方形 1:1 图片	有关指南，请参阅图片规格。
评分 - 最大值	必填	评分量表的最大值。如果也提供了评分的当前值，则必须提供。	数字 >= 0.0
评分 - 当前值	必填	评分量表的当前值。如果也提供了评分的最大值，则必须提供。	数字 >= 0.0
评分 - 计数	可选	实体评分的计数。注意：如果您的应用想要控制如何向用户显示此信息，请提供此字段。提供可以显示给用户的简洁字符串。例如，如果计数为 1,000,000，请考虑使用 1M 之类的缩写，这样在较小的显示尺寸上就不会被截断。	字符串
评分 - 计数值	可选	实体评分的计数。注意：如果您不想自己处理显示缩写逻辑，请提供此字段。如果同时存在 Count 和 Count Value，我们将使用 Count 显示给用户	长整型
位置 - 国家/地区	可选	此人所在或服务的国家/地区。	自由文本推荐文本大小：最大约 20 个字符
位置 - 城市	可选	此人所在或服务的城市。	自由文本推荐文本大小：最大约 20 个字符
位置 - 显示地址	可选	将显示给用户的此人所在或服务的地址。	自由文本推荐文本大小：最大约 20 个字符
位置 - 街道地址	可选	此人所在或服务的街道地址（如果适用）。	自由文本推荐文本大小：最大约 20 个字符
位置 - 州/省	可选	此人所在或服务的州（如果适用）。	自由文本推荐文本大小：最大约 20 个字符
位置 - 邮政编码	可选	此人所在或服务的邮政编码（如果适用）。	自由文本推荐文本大小：最大约 20 个字符
位置 - 街区	可选	此人所在或服务的街区（如果适用）。	自由文本推荐文本大小：最大约 20 个字符
徽章	可选	每个徽章都是自由文本（最多 15 个字符）或小图片。
徽章 - 文本	可选	徽章的标题注意：徽章需要文本或图片之一	自由文本推荐文本大小：最大 15 个字符
徽章 - 图片	可选	小图片特殊的 UX 处理，例如作为图片/视频缩略图上的徽章叠加层。注意：徽章需要文本或图片之一	有关指南，请参阅图片规格。
描述	可选	一段描述实体的文本。注意：将向用户显示描述或副标题列表，而不是两者都显示。	自由文本推荐文本大小：180 个字符
副标题列表	可选	最多 3 个副标题，每个副标题都是一行文本。注意：将向用户显示描述或副标题列表，而不是两者都显示。	自由文本每个副标题的推荐文本大小：最大 50 个字符
内容类别	可选	描述实体中内容的类别。	合格枚举列表 TYPE_HEALTH_AND_FITENESS（例如 - 瑜伽/健身教练） TYPE_HOME_AND_AUTO（例如 - 水管工） TYPE_SPORTS（例如 - 玩家） TYPE_DATING 有关指南，请参阅内容类别部分。

`RestaurantReservationEntity`

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

`EventReservationEntity`

属性	要求	描述	格式
Action 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 dp 的安全空间	有关指南，请参阅图片规格。
结束时间	可选	预期事件结束时的纪元时间戳。注意：这将以毫秒为单位表示。	以毫秒为单位的纪元时间戳
服务提供商 - 名称	可选	服务提供商的名称。注意：服务提供商需要文本或图片。	自由文本。例如，活动组织者/旅游的名称
服务提供商 - 图片	可选	服务提供商的徽标/图片。注意：服务提供商需要文本或图片。	有关指南，请参阅图片规格。
描述	可选	一段描述实体的文本。注意：将向用户显示描述或副标题列表，而不是两者都显示。	自由文本推荐文本大小：180 个字符
副标题列表	可选	最多 3 个副标题，每个副标题都是一行文本。注意：将向用户显示描述或副标题列表，而不是两者都显示。	自由文本每个副标题的推荐文本大小：最大 50 个字符
徽章	可选	每个徽章都是自由文本（最多 15 个字符）或小图片。
徽章 - 文本	可选	徽章的标题注意：徽章需要文本或图片之一	自由文本推荐文本大小：最大 15 个字符
徽章 - 图片	可选	小图片特殊的 UX 处理，例如作为图片/视频缩略图上的徽章叠加层。注意：徽章需要文本或图片之一	有关指南，请参阅图片规格。
预订 ID	可选	活动预订的预订 ID。	自由文本
价格 - 当前价格	有条件地必填	事件门票/通行证的当前价格。如果提供了删除线价格，则必须提供。	自由文本
价格 - 删除线价格	可选	事件门票/通行证的原始价格。	自由文本
价格标注	可选	价格标注，用于在可用时突出显示促销、活动、会员折扣等。	自由文本推荐文本大小：少于 45 个字符（过长的文本可能会显示省略号）
评分 - 最大值	可选	评分量表的最大值。如果也提供了评分的当前值，则必须提供。	数字 >= 0.0
评分 - 当前值	可选	评分量表的当前值。如果也提供了评分的最大值，则必须提供。	数字 >= 0.0
评分 - 计数	可选	活动的评分计数。注意：如果您的应用想要控制如何向用户显示此信息，请提供此字段。提供可以显示给用户的简洁字符串。例如，如果计数为 1,000,000，请考虑使用 1M 之类的缩写，这样在较小的显示尺寸上就不会被截断。	字符串
评分 - 计数值	可选	活动的评分计数。注意：如果您不想自己处理显示缩写逻辑，请提供此字段。如果同时存在 Count 和 Count Value，我们将使用 Count 显示给用户	长整型
内容类别	可选	描述实体中内容的类别。	合格枚举列表 TYPE_MOVIES_AND_TV_SHOWS（例如 - 影院） TYPE_DIGITAL_GAMES（例如 - 电子竞技） TYPE_MUSIC（例如 - 音乐会） TYPE_TRAVEL_AND_LOCAL（例如 - 旅游、节日） TYPE_HEALTH_AND_FITENESS（例如 - 瑜伽课） TYPE_EDUCATION（例如 - 课程） TYPE_SPORTS（例如 - 足球比赛） TYPE_DATING（例如 - 聚会）有关指南，请参阅内容类别部分。

`LodgingReservationEntity`

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

`TransportationReservationEntity`

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

`VehicleRentalReservationEntity`

属性	要求	描述	格式
Action 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。	自由文本
价格 - 当前价格	有条件地必填	预订的当前价格。如果提供了删除线价格，则必须提供。	自由文本
价格 - 删除线价格	可选	预订的原始价格，将在 UI 中以删除线显示。	自由文本
价格标注	可选	价格标注，用于在可用时突出显示促销、活动、会员折扣等。	自由文本推荐文本大小：少于 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_FITENESS
TYPE_MEDICAL
TYPE_PARENTING
TYPE_DATING

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

使用内容类别的指南

某些实体（如 ArticleEntity 和 GenericFeaturedEntity）可以使用任何内容类别。对于其他实体（如 EventEntity、EventReservationEntity、PointOfInterestEntity），只有一部分类别是适用的。在填充列表之前，请检查实体类型适用的类别列表。
对于某些内容类别，请使用特定的实体类型，而不是通用实体和 ContentCategory 的组合。
- TYPE_MOVIES_AND_TV_SHOWS - 在使用通用实体之前，请查看观看集成指南中的实体。
- 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 用于发布登录卡片。登录操作将用户引导至应用的登录页面，以便应用可以发布内容（或提供更多个性化内容）。

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

属性	要求	描述
Action Uri	必填	指向操作的深层链接（即导航到应用登录页面）
图像	可选 - 如果未提供，则必须提供标题	卡片上显示的图像 16x9 长宽比图像，分辨率为 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 用于删除用户帐户管理集群的内容。

Kotlin

client.deleteUserManagementCluster()

Java

client.deleteUserManagementCluster();

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

`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 返回。

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

步骤 3：处理广播意图

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

广播意图的主要目的是用于应用重新激活和强制数据同步。广播意图并非旨在非常频繁地发送。仅当 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> 标记静态声明一个实现。这允许应用程序在未运行时接收广播意图，并允许应用程序发布内容。

<application>
   <receiver
      android:name=".AppEngageBroadcastReceiver"
      android:exported="true"
      android:enabled="true">
      <intent-filter>
         <action android:name="com.google.android.engage.action.PUBLISH_RECOMMENDATION" />
      </intent-filter>
      <intent-filter>
         <action android:name="com.google.android.engage.action.PUBLISH_FEATURED" />
      </intent-filter>
      <intent-filter>
         <action android:name="com.google.android.engage.action.PUBLISH_CONTINUATION" />
      </intent-filter>
   </receiver>
</application>

服务发送以下意图

com.google.android.engage.action.PUBLISH_RECOMMENDATION 建议在收到此意图时启动 publishRecommendationClusters 调用。
com.google.android.engage.action.PUBLISH_FEATURED 建议在收到此意图时启动 publishFeaturedCluster 调用。
com.google.android.engage.action.PUBLISH_CONTINUATION 建议在收到此意图时启动 publishContinuationCluster 调用。

集成工作流程

有关在集成完成后验证集成的分步指南，请参阅 Engage 开发人员集成工作流程。

常见问题解答

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

联系方式

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

后续步骤

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

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