此页面由 Cloud Translation API 翻译。

Engage SDK 其他行业：第三方技术集成说明

Google 将打造一种设备端 surface，该 surface 可按行业整理用户的应用，并且支持全新的沉浸式体验，使用户能够以个性化的方式消费和发现应用内容。这种全屏体验使开发者合作伙伴有机会在其应用之外的专门频道中展示自己最棒的富媒体内容。

本文档包含面向开发者合作伙伴的说明，介绍了如何集成新的预订、活动、住宿、景点、人物等内容。使用 Engage SDK 时可能不属于上述任何类别填充这个新的 surface 区域。

集成详情

术语

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

推荐集群用于显示来自某人的个性化建议开发者合作伙伴它是一个界面视图，其中包含一组建议来自同一开发者合作伙伴
- ArticleEntity：表示基于文本的 ArticleEntity 与多个类别相关的内容推荐内容。ArticleEntity 项允许开发者提供使用更多元数据来阐明信息。例如：营销内容新闻摘要
  
  图 1：界面显示 Recommendations 中的单个 ArticleEntity 集群。
- EventEntity：EventEntity 表示事件中发生的事件。事件开始时间是都需要向用户传达
  
  图 2：显示中的单个 EventEntity 的界面推荐集群。
- LodgingEntity：LodgingEntity 代表住宿，例如例如酒店、公寓、度假屋（短期和长期）租金。
  
  图 3：显示单个 LodgingEntity 的界面。
- StoreEntity：StoreEntity 代表商店、餐馆、咖啡馆它突出显示了餐饮场所或商店您需要传达给用户。
  
  图 4：界面中显示了一个 StoreEntity 推荐集群。
- PointOfInterestEntity：PointOfInterestEntity 表示感兴趣的地点，如加油站、活动场地、主题公园例如博物馆、旅游景点、徒步小径等。而地理位置则是 Google Cloud 必须提供的传达给用户的信息它不能用于住宿、商店或餐饮场所。
  
  图 5：显示单个推荐集群内的 PointOfInterestEntity。
- PersonEntity：PersonEntity 代表人。建议可以按健康、健身、体育、约会等
  
  图 5：显示单个 PersonEntity 的界面推荐集群。
接续集群用于显示最近受以下受众群体互动过的内容：多个开发者合作伙伴。每个开发者合作伙伴最多只能在接续中广播 10 个实体集群。

接续内容可以采用以下格式：
- ArticleEntity：表示基于文本的 ArticleEntity 与多个类别相关的内容推荐内容。此实体可用于代表未看完的新闻文章或其他内容从上次停下的地方继续例如：营销内容、新闻摘要
  
  图 6. 界面中显示了一个接续集群
- RestaurantReservationEntity：RestaurantReservationEntity 表示预订餐厅或咖啡馆，并帮助用户跟踪持续的餐厅订位。
  
  图 7. 界面：显示单个餐馆预留实体位于接续集群中。
- Event 预留 Entity：EventReservationEntity 预订活动，并帮助用户跟踪即将到来或正在进行的活动预订。事件可能包括但不限于以下：
  - 体育赛事，例如足球赛预订
  - 电竞预订等游戏活动
  - 娱乐活动，例如电影院预订电影音乐会, 剧院, 署名
  - 旅行或地图注点预订，如导游陪同参观、博物馆票
  - 社交 / 研讨会 / 会议预订
  - 培训 / 培训课程预订
  。 <ph type="x-smartling-placeholder">
  </ph>
  图 8.界面：显示单个接续集群中的 EventReservationEntity。
- LodgingReservationEntity：LodgingEntityReserve 代表预订旅游住宿，并帮助用户跟踪即将到来的旅行或持续预订的酒店或民宿。
  
  图 9. 界面：显示单个接续集群中的 LodgingReservationEntity。
- TransportationReservationEntity：TransportationReservationEntity 表示预订各种交通方式的车辆，跟踪近期或正在进行的航班、轮渡、火车、公交车等预订信息，例如约车或游轮。
  
  图 10. 界面：显示单个 TransportationReservationEntity 控制在接续集群中。
- Vehicle 租预留 Entity：Vehicle 租预留实体代表车辆租赁预订，可帮助用户跟踪或持续的车辆租赁预订。
  
  图 11. 界面：显示单个接续集群中的 Vehicle 租预留实体。
精选集群是一个界面视图，用于展示所选主打图片一个界面分组中来自多个开发者合作伙伴的 GenericFeaturedEntity。精选集群只有一个，并将显示在界面，其中展示位置的优先级高于所有推荐集群。每个开发者合作伙伴可以广播支持的其中许多实体（可能属于不同的类型）在精选集群中添加多个应用开发者
- 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'
}

摘要

该设计基于绑定服务。

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

集群类型	集群限制	集群中的实体数下限	集群中的实体数上限
推荐集群	最多 5 个	至少 5 个	最多 25 个（`ArticleEntity`、`EventEntity`、 `LodgingEntity`、`StoreEntity`、 `PointOfInterestEntity` 或 `PersonEntity`）
接续集群	最多 1 个	至少 1 个	最多 10 个（`ArticleEntity`、 `EventReservationEntity`, `LodgingReservationEntity`, `TransportationReservationEntity` 或 `VehicleRentalReservationEntity`）
精选集群	最多 1 个	至少 1 个	最多 10 个 (`GenericFeaturedEntity`)

第 1 步：提供实体数据

SDK 定义了不同的实体来代表每种内容类型。我们支持其他类别的以下实体：

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

下面的图表列出了每种类型的可用属性和相关要求。

`GenericFeaturedEntity`

属性	要求	说明	格式
操作 URI	必需	指向提供商应用中实体的深层链接。注意：您可以使用深层链接进行归因。请参阅此常见问题解答	URI
海报图片	必需	如果提供了多张图片，我们只会显示 1 张图片。建议的宽高比为 16:9 注意：如果提供了标记，请确保图片顶部和底部的距离均为 24 dp	如需相关指导，请参阅图片规范。
标题	可选	实体的标题。	自由文本建议的文本大小：50 个字符
说明	可选	一段用于描述实体的文本。注意：说明或副标题列表不能同时向用户显示	自由文本建议的文本大小：180 个字符
字幕列表	可选	最多 3 个字幕，每个字幕占一行文字。注意：说明或副标题列表不能同时向用户显示	自由文本每个副标题的建议文字字号：上限 50 个字符
徽章	可选	每个徽章可以是自由文本（最多 15 个字符）或小图片。在图片/视频之上进行特殊用户体验处理，例如作为徽章叠加在图像上 “实时动态” 文章阅读时长
徽章 - 文字	可选	徽章的标题注意：必须为徽章提供文字或图片	自由文本建议的文本大小：最多 15 个字符
徽章 - 图片	可选	小图片进行特殊用户体验处理，例如在图片/视频上叠加徽章缩略图。注意：必须为徽章提供文字或图片	如需相关指导，请参阅图片规范。
内容分类	可选	描述实体中内容的类别。	枚举列表请参阅“内容分类”部分获取指导。

`ArticleEntity`

属性	要求	说明	格式
操作 URI	必需	指向提供商应用中实体的深层链接。注意：您可以使用深层链接进行归因。请参阅此常见问题解答	URI
标题	必需	实体的标题。	自由文本建议的文本大小：最多 50 个字符
海报图片	可选	如果提供了多张图片，我们只会显示 1 张图片。建议的宽高比为 16:9 注意：强烈建议使用图片。如果徽章为请确保映像	如需相关指导，请参阅图片规范。
来源 - 标题	可选	作者、组织或报告者的姓名	自由文本建议的文本大小：少于 25 个字符
来源 - 图片	可选	来源的图片，例如作者、组织、记者	如需相关指导，请参阅图片规范。
说明	可选	一段用于描述实体的文本。注意：说明或副标题列表不能同时向用户显示	自由文本建议的文本大小：180 个字符
字幕列表	可选	最多 3 个字幕，每个字幕占一行文字。注意：说明或副标题列表不能同时向用户显示	自由文本每个副标题的建议文字字号：上限 50 个字符
徽章	可选	每个徽章可以是自由文本（最多 15 个字符）或小图片。在图片/视频基础上进行特殊用户体验处理，例如作为徽章叠加在图像上 “实时动态” 文章阅读时长
徽章 - 文字	可选	徽章的标题注意：必须为徽章提供文字或图片	自由文本建议的文本大小：最多 15 个字符
徽章 - 图片	可选	小图片进行特殊用户体验处理，例如在图片/视频上叠加徽章缩略图。注意：必须为徽章提供文字或图片	如需相关指导，请参阅图片规范。
内容发布时间	可选	这是内容。	纪元时间戳（以毫秒为单位）
上次互动时长	在特定条件下必需	用户与之互动的纪元时间戳（以毫秒为单位）该实体。注意：如果此实体属于接续集群	纪元时间戳（以毫秒为单位）
进度百分比	在特定条件下必需	迄今为止用户已观看完整内容所占的百分比。注意：如果此实体属于接续集群	介于 0 到 100（含）之间的整数值。
内容分类	可选	描述实体中内容的类别。	枚举列表请参阅“内容分类”部分获取指导。

`EventEntity`

属性	要求	说明	格式
操作 URI	必需	指向提供商应用中实体的深层链接。注意：您可以使用深层链接进行归因。请参阅此常见问题解答	URI
标题	必需	实体的标题。	字符串建议的文本大小：最多 50 个字符
开始时间	必需	事件预计开始的纪元时间戳。注意：此值以毫秒为单位。	纪元时间戳（以毫秒为单位）
事件模式	必需	用于指明活动是线上、线下还是线上的字段两者都有。	枚举值：VIRTUAL、IN_PERSON 或 HYBRID
海报图片	必需	如果提供了多张图片，我们只会显示 1 张图片。建议的宽高比为 16:9 注意：强烈建议使用图片。如果徽章为请确保映像	如需相关指导，请参阅图片规范。
地理位置 - 国家/地区	在特定条件下必需	活动进行的国家/地区。注意：对于 IN_PERSON 或混合	自由文本建议的文本大小：最多约 20 个字符
位置 - 城市	在特定条件下必需	事件发生的城市。注意：对于 IN_PERSON 或混合	自由文本建议的文本大小：最多约 20 个字符
地理位置 - 显示地址	在特定条件下必需	举办活动的地址或场地名称向用户显示的内容注意：对于 IN_PERSON 或混合	自由文本建议的文本大小：最多约 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_FITENESS（示例 - 瑜伽课） TYPE_EDUCATION（示例 - 类） TYPE_SPORTS（示例 - 橄榄球游戏） TYPE_DATING（示例 - 聚会）请参阅“内容分类”部分获取指导。

`LodgingEntity`

属性	要求	说明	格式
操作 URI	必需	指向提供商应用中实体的深层链接。注意：您可以使用深层链接进行归因。请参阅此常见问题解答	URI
标题	必需	实体的标题。	字符串建议的文本大小：最多 50 个字符
海报图片	必需	如果提供了多张图片，我们只会显示 1 张图片。推荐宽高比为 16:9 注意：如果提供了标记，请确保图片顶部和底部的距离均为 24 dp	如需相关指导，请参阅图片规范。
地理位置 - 国家/地区	必需	住宿地点所在的国家/地区。	自由文本建议的文本大小：最多约 20 个字符
位置 - 城市	必需	住宿所在的城市。	自由文本建议的文本大小：最多约 20 个字符
地理位置 - 显示地址	必需	将向用户显示的住宿地址。	自由文本建议的文本大小：最多约 20 个字符
位置 - 街道地址	可选	住宿地点的街道地址（如适用）。	自由文本建议的文本大小：最多约 20 个字符
地理位置 - 省/自治区/直辖市	可选	住宿地点所在的州或省/直辖市/自治区（如适用）。	自由文本建议的文本大小：最多约 20 个字符
地理位置 - 邮政编码	可选	住宿地点的邮政编码（如适用）。	自由文本建议的文本大小：最多约 20 个字符
位置 - 社区	可选	住宿地点的社区（如适用）。	自由文本建议的文本大小：最多约 20 个字符
徽章	可选	每个徽章可以是自由文本（最多 15 个字符）或小图片。
徽章 - 文字	可选	徽章的标题注意：必须为徽章提供文字或图片	自由文本建议的文本大小：最多 15 个字符
徽章 - 图片	可选	小图片进行特殊用户体验处理，例如在图片/视频上叠加徽章缩略图。注意：必须为徽章提供文字或图片	如需相关指导，请参阅图片规范。
说明	可选	一段用于描述实体的文本。注意：说明或副标题列表不能同时向用户显示	自由文本建议的文本大小：180 个字符
字幕列表	可选	最多 3 个字幕，每个字幕占一行文字。注意：说明或副标题列表不能同时向用户显示	自由文本每个副标题的建议文字字号：上限 50 个字符
AvailabilityTimeWindow - 开始时间	可选	预计住宿的纪元时间戳（以毫秒为单位）开放/可用。	纪元时间戳（以毫秒为单位）
AvailabilityTimeWindow - 结束时间	可选	预计住宿的周期时间戳（以毫秒为单位）开放/可用	纪元时间戳（以毫秒为单位）
评分 - 最大值	可选	评分量表的最大值。如果同时提供当前评分值，则必须提供。	数值 >= 0.0
评分 - 当前值	可选	评分量表的当前值。如果同时提供最大评分值，则必须提供。	数值 >= 0.0
评分 - 数量	可选	酒店的评分数量。注意：如果您的应用是这样，请提供此字段控制如何向用户显示计数。使用简洁的字符串。例如，如果计数为 1,000,000，请考虑使用缩写例如 1M，这样在尺寸较小的显示屏上，该计数就不会被截断。	字符串
评分 - 数量值	可选	酒店的评分数量。注意：如果您没有进行处理，请提供此字段自行显示缩写逻辑如果同时设置了 Count 和 Count 值计数，则向用户显示计数。	长
价格 - 当前价格	在特定条件下必需	住宿地点的当前价格。如果提供带删除线的价格，则必须提供。	自由文本
价格 - 删除线价格	可选	住宿原价，即在界面。	自由文本
价格宣传信息	可选	用于宣传促销、活动、会员折扣（如果有）的价格宣传信息。	自由文本建议的文本大小：少于 45 个字符（文本过长）可能会显示省略号）

`StoreEntity`

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

属性	要求	说明	格式
海报图片	必需	必须提供至少一张图片。	如需相关指导，请参阅图片规范。
操作 URI	必需	指向提供商应用中实体的深层链接。注意：您可以使用深层链接进行归因。请参阅此常见问题解答	URI
标题	可选	商店的名称。	自由文本建议的文本大小：少于 45 个字符（如果文本过长，可能会显示省略号）
位置	可选	商店的位置信息。	自由文本建议的文本大小：少于 45 个字符（如果文本过长，可能会显示省略号）
宣传信息	可选	用于展示商店的促销、活动或最新动态的宣传信息（如果有）。	自由文本建议的文本大小：少于 45 个字符（如果文本过长，可能会显示省略号）
宣传信息附属细则	可选	宣传信息的附属细则文本。	自由文本建议的文本大小：少于 45 个字符（如果文本过长，可能会显示省略号）
说明	可选	商店的说明。	自由文本建议的文本大小：少于 90 个字符（如果文本过长，可能会显示省略号）
评分 - 最大值	可选	评分量表的最大值。如果同时提供当前评分值，则必须提供。	数值 >= 0.0
评分 - 当前值	可选	评分量表的当前值。如果同时提供最大评分值，则必须提供。	数值 >= 0.0
评分 - 数量	可选	酒店的评分数量。注意：如果您的应用需要控制如何向用户显示此内容提供简洁的字符串可以向用户显示的内容例如，如果计数为 1,000,000，则可以考虑使用 1M 等缩写，在较小的显示尺寸上被截断。	字符串
评分 - 数量值	可选	酒店的评分数量。注意：如果您不想处理，请提供此字段自行显示缩写逻辑如果同时设置了 Count 和 Count 值我们会使用“计数”向用户显示	长

`PointOfInterestEntity`

属性	要求	说明	格式
操作 URI	必需	指向提供商应用中实体的深层链接。注意：您可以使用深层链接进行归因。请参阅此常见问题解答	URI
标题	必需	实体的标题。	字符串建议的文本大小：最多 50 个字符
海报图片	必需	如果提供了多张图片，我们只会显示 1 张图片。建议的宽高比为 16:9 注意：强烈建议使用图片。如果徽章为请确保映像	如需相关指导，请参阅图片规范。
地理位置 - 国家/地区	必需	感兴趣的地点所在的国家/地区。	自由文本建议的文本大小：最多约 20 个字符
位置 - 城市	必需	地图注点所在的城市。	自由文本建议的文本大小：最多约 20 个字符
地理位置 - 显示地址	必需	将向用户。	自由文本建议的文本大小：最多约 20 个字符
位置 - 街道地址	可选	地图注点的街道地址（如果适用）。	自由文本建议的文本大小：最多约 20 个字符
地理位置 - 省/自治区/直辖市	可选	感兴趣的地点所在的州或省/直辖市/自治区（如果有）。	自由文本建议的文本大小：最多约 20 个字符
地理位置 - 邮政编码	可选	地图注点的邮政编码（如果适用）。	自由文本建议的文本大小：最多约 20 个字符
位置 - 社区	可选	地图注点的社区（如果适用）。	自由文本建议的文本大小：最多约 20 个字符
AvailabilityTimeWindow - 开始时间	可选	兴趣点所在的纪元时间戳（以毫秒为单位）预计开放/可用。	纪元时间戳（以毫秒为单位）
AvailabilityTimeWindow - 结束时间	可选	兴趣点到达的纪元时间戳（以毫秒为单位）预计开放/可用。	纪元时间戳（以毫秒为单位）
徽章	可选	每个徽章可以是自由文本（最多 15 个字符）或小图片。
徽章 - 文字	可选	徽章的标题注意：必须为徽章提供文字或图片	自由文本建议的文本大小：最多 15 个字符
徽章 - 图片	可选	小图片进行特殊用户体验处理，例如在图片/视频上叠加徽章缩略图。注意：必须为徽章提供文字或图片	如需相关指导，请参阅图片规范。
说明	可选	一段用于描述实体的文本。注意：说明或副标题列表不能同时向用户显示	自由文本建议的文本大小：180 个字符
字幕列表	可选	最多 3 个字幕，每个字幕占一行文字。注意：说明或副标题列表不能同时向用户显示	自由文本每个副标题的建议文字字号：上限 50 个字符
评分 - 最大值	可选	评分量表的最大值。如果同时提供当前评分值，则必须提供。	数值 >= 0.0
评分 - 当前值	可选	评分量表的当前值。如果同时提供最大评分值，则必须提供。	数值 >= 0.0
评分 - 数量	可选	地图注点的评分数量。注意：如果您的应用是这样，请提供此字段控制如何向用户显示计数。使用简洁的字符串。例如，如果计数为 1,000,000，请考虑使用缩写例如 1M，这样在尺寸较小的显示屏上，该计数就不会被截断。	字符串
评分 - 数量值	可选	地图注点的评分数量。注意：如果您没有进行处理，请提供此字段自行显示缩写逻辑如果同时设置了 Count 和 Count 值计数，则会向用户显示	长
价格 - 当前价格	在特定条件下必需	以下地点的门票/入场券的当前价格：。如果提供了带删除线的价格，则必须提供。	自由文本
价格 - 删除线价格	可选	地图注点的门票/入场券原价。	自由文本
价格宣传信息	可选	用于宣传促销、活动、会员折扣（如果有）的价格宣传信息。	自由文本建议的文本大小：少于 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 注意：强烈建议使用图片。如果徽章为请确保映像	如需相关指导，请参阅图片规范。
热门程度 - 数量	可选	表示标题图片。不得与个人资料图片相同。如果有其他图片有助于突出显示人们喜欢自己的工作注意：必须是 16:9 的图片。如果提供了标记确保图像的顶部和底部均有 24 dps 的安全空间	字符串建议的文本大小：计数 + 标签最多为 20 个字符组合
热门程度 - 计数值	可选	关注者数量或热门程度值。注意：如果您的应用不需要“Count Value”，请提供处理如何针对大数字进行优化的逻辑不同的显示尺寸如果同时提供了“计数”和“计数值”，将使用计数。	长
热门程度 - 标签	可选	指明热门程度标签。例如，“点赞”。	字符串建议的文本大小：计数 + 标签最多为 20 个字符组合
热门程度 - 视觉	可选	表明互动的目的，例如 - 显示的图片 “赞”图标、表情符号。可以提供多张图片，但部分图片可能不会全部显示设备规格。注意：必须是 1:1 的方形图片	如需相关指导，请参阅图片规范。
评分 - 最大值	必需	评分量表的最大值。如果同时提供当前评分值，则必须提供。	数值 >= 0.0
评分 - 当前值	必需	评分量表的当前值。如果同时提供最大评分值，则必须提供。	数值 >= 0.0
评分 - 数量	可选	实体评分的计数。注意：如果您的应用需要控制如何向用户显示此内容提供简洁的字符串可以向用户显示的内容例如，如果计数为 1,000,000，则可以考虑使用 1M 等缩写，在较小的显示尺寸上被截断。	字符串
评分 - 数量值	可选	实体评分的计数。注意：如果您不想处理，请提供此字段自行显示缩写逻辑如果同时设置了 Count 和 Count 值我们会使用“计数”向用户显示	长
地理位置 - 国家/地区	可选	用户所在的国家/地区或提供服务的国家/地区。	自由文本建议的文本大小：最多约 20 个字符
位置 - 城市	可选	用户所在或提供服务的城市。	自由文本建议的文本大小：最多约 20 个字符
地理位置 - 显示地址	可选	显示用户所在或提供服务的地址用户。	自由文本建议的文本大小：最多约 20 个字符
位置 - 街道地址	可选	此人所在的街道地址（如适用）或。	自由文本建议的文本大小：最多约 20 个字符
地理位置 - 省/自治区/直辖市	可选	用户所在的州或省/直辖市/自治区（如适用）。	自由文本建议的文本大小：最多约 20 个字符
地理位置 - 邮政编码	可选	用户所在或提供服务的邮政编码（如适用）。	自由文本建议的文本大小：最多约 20 个字符
位置 - 社区	可选	用户所在或提供服务的社区（如适用）。	自由文本建议的文本大小：最多约 20 个字符
徽章	可选	每个徽章可以是自由文本（最多 15 个字符）或小图片。
徽章 - 文字	可选	徽章的标题注意：必须为徽章提供文字或图片	自由文本建议的文本大小：最多 15 个字符
徽章 - 图片	可选	小图片进行特殊用户体验处理，例如在图片/视频上叠加徽章缩略图。注意：必须为徽章提供文字或图片	如需相关指导，请参阅图片规范。
说明	可选	一段用于描述实体的文本。注意：说明或副标题列表不能同时向用户显示	自由文本建议的文本大小：180 个字符
字幕列表	可选	最多 3 个字幕，每个字幕占一行文字。注意：说明或副标题列表不能同时向用户显示	自由文本每个副标题的建议文字字号：上限 50 个字符
内容分类	可选	描述实体中内容的类别。	符合条件的枚举列表 TYPE_HEALTH_AND_FITENESS（例如：瑜伽/健身教练） TYPE_HOME_AND_AUTO（示例 - 管道工） TYPE_SPORTS（示例 - 运动员）类型：约会请参阅“内容分类”部分获取指导。

`RestaurantReservationEntity`

属性	要求	说明	格式
操作 URI	必需	指向提供商应用中实体的深层链接。注意：您可以使用深层链接进行归因。请参阅此常见问题解答	URI
标题	必需	实体的标题。	字符串建议的文本大小：最多 50 个字符
预定开始时间	必需	预计预留将进行的纪元时间戳（以毫秒为单位） start 的值。	纪元时间戳（以毫秒为单位）
地理位置 - 国家/地区	必需	餐馆所在的国家/地区。	自由文本建议的文本大小：最多约 20 个字符
位置 - 城市	必需	餐馆所在的城市。	自由文本建议的文本大小：最多约 20 个字符
地理位置 - 显示地址	必需	向用户。	自由文本建议的文本大小：最多约 20 个字符
位置 - 街道地址	可选	餐馆的街道地址（如适用）。	自由文本建议的文本大小：最多约 20 个字符
地理位置 - 省/自治区/直辖市	可选	餐馆所在的州或省/直辖市/自治区（如适用）。	自由文本建议的文本大小：最多约 20 个字符
地理位置 - 邮政编码	可选	餐馆的邮政编码（如果适用）。	自由文本建议的文本大小：最多约 20 个字符
位置 - 社区	可选	餐馆的街区（如适用）。	自由文本建议的文本大小：最多约 20 个字符
海报图片	可选	如果提供了多张图片，我们只会显示 1 张图片。推荐宽高比为 16:9	如需相关指导，请参阅图片规范。
说明	可选	一段用于描述实体的文本。注意：说明或副标题列表不能同时向用户显示	自由文本建议的文本大小：180 个字符
字幕列表	可选	最多 3 个字幕，每个字幕占一行文字。注意：说明或副标题列表不能同时向用户显示	自由文本每个副标题的建议文字字号：上限 50 个字符
表大小	可选	预订群组中的用户数量	整数 >0 次

`EventReservationEntity`

属性	要求	说明	格式
操作 URI	必需	指向提供商应用中实体的深层链接。注意：您可以使用深层链接进行归因。请参阅此常见问题解答	URI
标题	必需	实体的标题。	字符串建议的文本大小：最多 50 个字符
开始时间	必需	事件预计开始的纪元时间戳。注意：此值以毫秒为单位。	纪元时间戳（以毫秒为单位）
事件模式	必需	用于指明活动是线上、线下还是线上的字段两者都有。	枚举值：VIRTUAL、IN_PERSON 或 HYBRID
地理位置 - 国家/地区	在特定条件下必需	活动进行的国家/地区。注意：对于 IN_PERSON 或混合	自由文本建议的文本大小：最多约 20 个字符
位置 - 城市	在特定条件下必需	事件发生的城市。注意：对于 IN_PERSON 或混合	自由文本建议的文本大小：最多约 20 个字符
地理位置 - 显示地址	在特定条件下必需	举办活动的地址或场地名称向用户显示的内容注意：对于 IN_PERSON 或混合	自由文本建议的文本大小：最多约 20 个字符
位置 - 街道地址	可选	活动举办地点的街道地址（如适用）托管对象	自由文本建议的文本大小：最多约 20 个字符
地理位置 - 省/自治区/直辖市	可选	举办活动的州或省（如果适用）托管。	自由文本建议的文本大小：最多约 20 个字符
地理位置 - 邮政编码	可选	活动举办地点的邮政编码（如适用）托管。	自由文本建议的文本大小：最多约 20 个字符
位置 - 社区	可选	举办活动的社区（如适用）。	自由文本建议的文本大小：最多约 20 个字符
海报图片	可选	如果提供了多张图片，我们只会显示 1 张图片。建议的宽高比为 16:9 注意：强烈建议使用图片。如果徽章为请确保映像	如需相关指导，请参阅图片规范。
结束时间	可选	预计事件结束的纪元时间戳。注意：此值以毫秒为单位。	纪元时间戳（以毫秒为单位）
服务提供商 - 名称	可选	服务提供商的名称。注意：该服务需要文字或图片提供商。	自由文本。例如活动主办方/巡回演出的名称
服务提供商 - 图片	可选	服务提供商的徽标/图片。注意：该服务需要文字或图片提供商。	如需相关指导，请参阅图片规范。
说明	可选	一段用于描述实体的文本。注意：说明或副标题列表不能同时向用户显示	自由文本建议的文本大小：180 个字符
字幕列表	可选	最多 3 个字幕，每个字幕占一行文字。注意：说明或副标题列表不能同时向用户显示	自由文本每个副标题的建议文字字号：上限 50 个字符
徽章	可选	每个徽章可以是自由文本（最多 15 个字符）或小图片。
徽章 - 文字	可选	徽章的标题注意：必须为徽章提供文字或图片	自由文本建议的文本大小：最多 15 个字符
徽章 - 图片	可选	小图片进行特殊用户体验处理，例如在图片/视频上叠加徽章缩略图。注意：必须为徽章提供文字或图片	如需相关指导，请参阅图片规范。
预留 ID	可选	活动预订的预订 ID。	自由文本
价格 - 当前价格	在特定条件下必需	活动门票/通行证的当前价格。如果提供了带删除线的价格，则必须提供。	自由文本
价格 - 删除线价格	可选	活动门票/通行证的原价。	自由文本
价格宣传信息	可选	用于宣传促销、活动、会员折扣（如果有）的价格宣传信息。	自由文本建议的文本大小：少于 45 个字符（文本过长）可能会显示省略号）
评分 - 最大值	可选	评分量表的最大值。如果同时提供当前评分值，则必须提供。	数值 >= 0.0
评分 - 当前值	可选	评分量表的当前值。如果同时提供最大评分值，则必须提供。	数值 >= 0.0
评分 - 数量	可选	事件评分的计数。注意：如果您的应用需要控制如何向用户显示此内容提供简洁的字符串可以向用户显示的内容例如，如果计数为 1,000,000，则可以考虑使用 1M 等缩写，在较小的显示尺寸上被截断。	字符串
评分 - 数量值	可选	事件评分的计数。注意：如果您不想处理，请提供此字段自行显示缩写逻辑如果同时设置了 Count 和 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`

属性	要求	说明	格式
操作 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 等缩写，在较小的显示尺寸上被截断。	字符串
评分 - 数量值	可选	酒店的评分数量。注意：如果您不想处理，请提供此字段自行显示缩写逻辑如果同时设置了 Count 和 Count 值我们会使用“计数”向用户显示	长
价格 - 当前价格	在特定条件下必需	住宿地点的当前价格。如果提供带删除线的价格，则必须提供。	自由文本
价格 - 删除线价格	可选	住宿原价，即在界面。	自由文本
价格宣传信息	可选	用于宣传促销、活动、会员折扣（如果有）的价格宣传信息。	自由文本建议的文本大小：少于 45 个字符（文本过长）可能会显示省略号）

`TransportationReservationEntity`

属性	要求	说明	格式
操作 URI	必需	指向提供商应用中实体的深层链接。注意：您可以使用深层链接进行归因。请参阅此常见问题解答	URI
标题	必需	实体的标题。	自由文本。例如：“SFO to 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。	自由文本
价格 - 当前价格	在特定条件下必需	预订的当前价格。如果提供带删除线的价格，则必须提供。	自由文本
价格 - 删除线价格	可选	预留的原始价格，该价格在界面。	自由文本
价格宣传信息	可选	用于宣传促销、活动、会员折扣（如果有）的价格宣传信息。	自由文本建议的文本大小：少于 45 个字符（文本过长）可能会显示省略号）
运输编号	必需	航班号、公交车号、列车号或轮渡/邮轮号。	自由文本
登机时间	必需	表示预订登机时间的纪元时间戳（如果有）	纪元时间戳（以毫秒为单位）

`VehicleRentalReservationEntity`

属性	要求	说明	格式
操作 URI	必需	指向提供商应用中实体的深层链接。注意：您可以使用深层链接进行归因。请参阅此常见问题解答	URI
标题	必需	实体的标题。	自由文本。例如，“上海市南京东路” 建议的文本大小：最多 50 个字符
取车时间	必需	表示预留的开始时间的纪元时间戳。	纪元时间戳（以毫秒为单位）
返程时间	可选	表示预留签出时间的纪元时间戳。	纪元时间戳（以毫秒为单位）
取货地址 - 国家/地区	可选	自提地点所在的国家/地区。	自由文本建议的文本大小：最多约 20 个字符
取货地址 - 城市	可选	上车点所在的城市。	自由文本建议的文本大小：最多约 20 个字符
取件地址 - 显示地址	可选	将向用户显示的自提地点。	自由文本建议的文本大小：最多约 20 个字符
取车地址 - 街道地址	可选	上车地点的街道地址（如适用）。	自由文本建议的文本大小：最多约 20 个字符
取货地址 - 州/省/自治区/直辖市	可选	自提地点所在的州或省（如适用）。	自由文本建议的文本大小：最多约 20 个字符
取货地址 - 邮政编码	可选	自提地点的邮政编码（如适用）。	自由文本建议的文本大小：最多约 20 个字符
取货地址 - 社区	可选	上车点所在的社区（如适用）。	自由文本建议的文本大小：最多约 20 个字符
退货地址 - 国家/地区	可选	退货地址所在的国家/地区。	自由文本建议的文本大小：最多约 20 个字符
退货地址 - 城市	可选	返回地点的城市。	自由文本建议的文本大小：最多约 20 个字符
退货地址 - 显示地址	可选	将向用户显示的退货地址。	自由文本建议的文本大小：最多约 20 个字符
退货地址 - 街道地址	可选	退货地点的街道地址（如适用）。	自由文本建议的文本大小：最多约 20 个字符
退货地址 - 州	可选	退货地址所在的州或省（如适用）。	自由文本建议的文本大小：最多约 20 个字符
退货地址 - 邮政编码	可选	退货地址的邮政编码（如适用）。	自由文本建议的文本大小：最多约 20 个字符
退货地址 - 社区	可选	退货地址的社区（如适用）。	自由文本建议的文本大小：最多约 20 个字符
服务提供商 - 名称	可选	服务提供商的名称。注意：该服务需要文字或图片提供商。	自由文本。例如：“Avis 租车”
服务提供商 - 图片	可选	服务提供商的徽标/图片。注意：该服务需要文字或图片提供商。	如需相关指导，请参阅图片规范。
海报图片	可选	如果提供了多张图片，我们只会显示 1 张图片。推荐宽高比为 16:9	如需相关指导，请参阅图片规范。
说明	可选	一段用于描述实体的文本。注意：说明或副标题列表不能同时向用户显示	自由文本建议的文本大小：180 个字符
字幕列表	可选	最多 3 个字幕，每个字幕占一行文字。注意：说明或副标题列表不能同时向用户显示	自由文本每个副标题的建议文字字号：上限 50 个字符
确认 ID	可选	车辆租赁预订的确认 ID。	自由文本
价格 - 当前价格	在特定条件下必需	预订的当前价格。如果提供带删除线的价格，则必须提供。	自由文本
价格 - 删除线价格	可选	预留的原始价格，该价格在界面。	自由文本
价格宣传信息	可选	用于宣传促销、活动、会员折扣（如果有）的价格宣传信息。	自由文本建议的文本大小：少于 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 用于发布登录卡片。登录操作会将用户定向到应用的登录页面，以便应用能够发布内容（或提供更个性化的内容）。

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

属性	要求	说明
操作 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 会建议您发布登录卡片如果提供商出于任何原因发布登录卡片，那么我们建议您调用带有状态代码的 updatePublishStatus API NOT_PUBLISHED_REQUIRES_SIGN_IN

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

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

`deleteFeaturedCluster`

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

Kotlin


client.deleteFeaturedCluster()

Java


client.deleteFeaturedCluster();

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

`deleteContinuationCluster`

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

Kotlin


client.deleteContinuationCluster()

Java


client.deleteContinuationCluster();

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

`deleteUserManagementCluster`

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

Kotlin


client.deleteUserManagementCluster()

Java


client.deleteUserManagementCluster();

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

错误处理

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

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

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

必须通过以下两种方式设置 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 商店后，您的推荐、精选和接续集群便可被发布并向用户显示。