Google 将打造一种设备端 surface，该 surface 可按行业整理用户的应用，并且支持全新的沉浸式体验，使用户能够以个性化的方式消费和发现应用内容。这种全屏体验让开发者合作伙伴有机会在其应用之外的专用频道中展示最优质的富媒体内容。本指南包含面向开发者合作伙伴的说明，介绍了如何使用 Engage SDK 填充这个新的 surface 区域，以便集成约会内容。
集成详情
术语
此集成包含以下三种集群类型：推荐、精选和接续。
推荐集群用于显示来自单个开发者合作伙伴的个性化约会建议。用户可针对这些推荐进行个性化设置。
- 推荐集群可以由
ArticleEntity、PersonEntity或EventEntity组成，但不能由不同实体类型混合组成。
您的推荐将采用如下结构：
推荐集群：一个界面视图，其中包含来自同一开发者合作伙伴的一组推荐。
实体：代表集群中单个内容的对象。此集成提供了一些可通过推荐集群显示的实体：
ArticleEntity：ArticleEntity 表示推荐与约会相关的文字内容。借助 ArticleEntity 项，开发者可以提供各种文本和图片内容以及更多元数据，以便向用户清晰阐明信息。
图 1：显示 Recommendations 集群内单个 ArticleEntity 的界面。 PersonEntity：PersonEntity 表示个人。具体建议可能是突出显示约会对象中的一个人。
图 2：显示 Recommendations 集群内单个 PersonEntity 的界面。 EventEntity：EventEntity 表示未来发生的事件。事件开始时间是需要传达给用户的重要信息。
图 3：显示 Recommendations 集群内单个 EventEntity 的界面。
- 推荐集群可以由
接续集群用于在单个界面分组中显示来自多个开发者合作伙伴的最近与用户互动的内容。每个开发者合作伙伴最多可以在接续集群中广播 10 个实体。
接续内容可以采用以下结构：
ArticleEntity：文章实体表示推荐与约会相关的文字内容。此实体可用于表示用户想要继续浏览的未看完新闻报道或其他内容。
图 6. 显示接续集群内的单个 ArticleEntity 的界面。 EventReservationEntity：EventReservationEntity 表示活动预订，可帮助用户跟踪即将开始或正在进行的约会和聚会活动预订。
图 8. 显示接续集群内单个 EventReservationEntity 的界面。
精选集群是一个界面视图，用于在一个界面分组中展示来自多个开发者合作伙伴的精选主打
GenericFeaturedEntity。精选集群只有一个，并将显示在界面顶部附近，其展示位置的优先级高于所有推荐集群。每个开发者合作伙伴都可以在精选中广播一个受支持类型的实体，因此精选集群中存在来自多个应用开发者的多个实体（可能分属不同类型）。GenericFeaturedEntity（常规精选实体）与推荐项的不同之处在于，精选项应用于开发者提供的单个热门内容，并且应代表用户感兴趣的且与用户相关的最重要的单个内容。
图 12：显示包含 GenericFeaturedEntity 列表的 FeaturedCluster 的界面
准备工作
最低 API 级别：19
将 com.google.android.play:engage 库添加到您的应用中：
dependencies {
// Make sure you also include that repository in your project's build.gradle file.
implementation 'com.google.android.engage:engage-core:1.4.1'
}
摘要
设计基于绑定服务的实现。
对于不同的集群类型，客户端可以发布的数据受以下限制：
| 集群类型 | 集群限制 | 集群中的实体数下限 | 集群中的实体数上限 |
|---|---|---|---|
| 推荐集群 | 最多 5 个 | 至少 5 个 | 最多 25 个（ArticleEntity、PersonEntity 或 EventEntity） |
| 接续集群 | 最多 1 个 | 至少 1 个 | 最多 10 个（ArticleEntity 或 EventReservationEntity） |
| 精选集群 | 最多 1 个 | 至少 1 个 | 最多 10 个 (GenericFeaturedEntity) |
第 1 步：提供实体数据
SDK 定义了不同的实体来代表每种内容类型。对于“约会”类别，我们支持下列实体：
GenericFeaturedEntityArticleEntityPersonEntityEventEntityEventReservationEntity
下表列出了每种类型的可用属性和相关要求。
GenericFeaturedEntity
| 属性 | 要求 | 说明 | 格式 |
|---|---|---|---|
| 操作 URI | 是否必需 |
指向提供商应用中实体的深层链接。 注意：您可以使用深层链接进行归因。 参阅此常见问题解答 |
URI |
| 海报图片 | 是否必需 | 如果提供了多张图片，我们只会显示 1 张图片。 建议的宽高比为 16:9 注意：如果提供了标记，请确保图片顶部和底部都有 24 dp 的安全空间 |
如需相关指导，请参阅图片规范。 |
| 标题 | 可选 | 实体的标题。 | 自由文本 建议的文本大小：50 个字符 |
| 说明 | 可选 | 用于描述实体的单段文本。 注意：系统将向用户显示说明或字幕列表，不能同时显示两者。 |
自由文本 建议的文本大小：180 个字符 |
| 字幕列表 | 可选 | 最多 3 个字幕，每个字幕一行文字。 注意：系统将向用户显示说明或字幕列表，不能同时显示两者。 |
自由文本 每条副标题建议的文字大小：最多 50 个字符 |
| 徽章 | 可选 | 每个标志要么是自由文本（最多 15 个字符），要么是小图片。 在图片/视频之上进行特殊用户体验处理，例如在图片上叠加显示标志
|
|
| 标记 - 文本 | 可选 | 徽章的标题 注意：徽章必须提供文字或图片 |
自由文本 建议的文本大小：不超过 15 个字符 |
| 徽章 - 图片 | 可选 | 小图片 特殊的用户体验处理，例如，在图片/视频缩略图上叠加显示徽章。 注意：徽章必须提供文字或图片 |
如需相关指导，请参阅图片规范。 |
| 内容分类 | 可选 | 描述实体中内容的类别。 | 枚举列表 如需指导，请参阅“内容类别”部分。 |
ArticleEntity
| 属性 | 要求 | 说明 | 格式 |
|---|---|---|---|
| 操作 URI | 是否必需 |
指向提供商应用中实体的深层链接。 注意：您可以使用深层链接进行归因。 参阅此常见问题解答 |
URI |
| 标题 | 是否必需 | 实体的标题。 | 自由文本 建议的文本大小：不超过 50 个字符 |
| 海报图片 | 可选 | 如果提供了多张图片，我们只会显示 1 张图片。 建议的宽高比为 16:9 注意：强烈建议提供图片。如果提供了标记，请确保图片顶部和底部留出 24 dp 的安全空间 |
如需相关指导，请参阅图片规范。 |
| 来源 - 标题 | 可选 | 作者、组织或举报者的姓名 | 自由文本 建议的文本大小：少于 25 个字符 |
| 来源 - 图片 | 可选 | 信息来源的图片，例如作者、组织、记者 | 如需相关指导，请参阅图片规范。 |
| 说明 | 可选 | 用于描述实体的单段文本。 注意：系统将向用户显示说明或字幕列表，不能同时显示两者。 |
自由文本 建议的文本大小：180 个字符 |
| 字幕列表 | 可选 | 最多 3 个字幕，每个字幕一行文字。 注意：系统将向用户显示说明或字幕列表，不能同时显示两者。 |
自由文本 每条副标题建议的文字大小：最多 50 个字符 |
| 徽章 | 可选 | 每个标志要么是自由文本（最多 15 个字符），要么是小图片。 在图片/视频之上进行特殊用户体验处理，例如在图片上叠加显示标志
|
|
| 标记 - 文本 | 可选 | 徽章的标题 注意：徽章必须提供文字或图片 |
自由文本 建议的文本大小：不超过 15 个字符 |
| 徽章 - 图片 | 可选 | 小图片 特殊的用户体验处理，例如，在图片/视频缩略图上叠加显示徽章。 注意：徽章必须提供文字或图片 |
如需相关指导，请参阅图片规范。 |
| 内容发布时间 | 可选 | 这是内容在应用中发布 / 更新的纪元时间戳（以毫秒为单位）。 | 纪元时间戳（以毫秒为单位） |
| 上次互动时长 | 必需（有条件） | 用户上次与此实体互动时的纪元时间戳（以毫秒为单位）。 注意：如果此实体是接续集群的一部分，则此字段为必填字段。 |
纪元时间戳（以毫秒为单位） |
| 进度百分比 | 必需（有条件） | 用户迄今为止使用的全部内容所占的百分比。 注意：如果此实体是接续集群的一部分，则此字段为必填字段。 |
介于 0 到 100 之间（包括 0 和 100）的整型值。 |
| 内容分类 | 可选 | 描述实体中内容的类别。 | 枚举列表 如需指导，请参阅“内容类别”部分。 |
PersonEntity
| 属性 | 要求 | 说明 | 格式 |
|---|---|---|---|
| 操作 URI | 是否必需 |
指向提供商应用中实体的深层链接。 注意：您可以使用深层链接进行归因。 参阅此常见问题解答 |
URI |
| 个人资料 - 姓名 | 是否必需 | 个人资料名称、ID 或标识名（例如“John Doe”“@TeamPixel”等）。 | 字符串 建议的文本大小：不超过 50 个字符 |
| 个人资料 - 头像 | 是否必需 |
用户的个人资料照片或头像图片。 注意：必须是 1:1 的方形图片。 |
如需相关指导，请参阅图片规范。 |
| 个人资料 - 附加文字 | 可选 | 个人资料标识名等自由文本。 | 自由文本 建议的文本大小：不超过 15 个字符 |
| 个人资料 - 附加图片 | 可选 | 小图片，例如经过验证的徽章。 | 如需相关指导，请参阅图片规范。 |
| 标题图片 | 可选 | 如果提供了多张图片，我们只会显示 1 张图片。 建议的宽高比为 16:9 注意：强烈建议提供图片。如果提供了标记，请确保图片顶部和底部留出 24 dp 的安全空间 |
如需相关指导，请参阅图片规范。 |
| 热门程度 - 计数 | 可选 |
表示标题图片。应与个人资料照片不同。 如果有其他有助于突显此人喜欢其作品的附加图，则可以使用此方式。 注意：图片必须为 16:9。如果提供了标记，请确保图片顶部和底部都留出 24 dp 的安全空间 |
字符串 建议的文本大小：计数 + 标签总计不超过 20 个字符 |
| 热门程度 - 计数值 | 可选 | 关注者人数或热门程度值。 注意：如果您的应用不想处理有关如何针对不同显示大小优化大数字的逻辑，请提供计数值。如果同时提供了“计数”和“计数值”，系统将会使用“计数”。 |
长 |
| 热门程度 - 标签 | 可选 | 指明热门程度标签，例如“赞过的视频”。 | 字符串 建议的文本大小：计数 + 标签总计不超过 20 个字符 |
| 热门程度 - 视觉内容 | 可选 |
表明互动的目的，例如，显示“赞”图标的图片、表情符号。 可以提供多张图片，但部分图片可能不会显示在所有外形规格的设备上。 注意：必须为 1:1 的方形图片 |
如需相关指导，请参阅图片规范。 |
| 评分 - 最大值 | 必需 | 评分量表的最大值。 如果同时提供当前评分值，则必须提供。 |
数值 >= 0.0 |
| 评分 - 当前值 | 必需 | 评分量表的当前值。 如果同时提供最大评分值，则必须提供。 |
数值 >= 0.0 |
| 评分 - 计数 | 可选 | 实体评分的计数。 注意：如果您的应用想要控制如何向用户显示此字段，请提供此字段。请提供可向用户显示的简洁字符串。例如，如果计数为 1,000,000，请考虑使用 1M 等缩写，以免在较小的显示屏上被截断。 |
字符串 |
| 评分 - 计数值 | 可选 | 实体评分的计数。 注意：如果您不想自行处理显示缩写逻辑，请提供此字段。如果“计数”和“计数值”均存在，我们将使用向用户显示的“计数” |
长 |
| 位置 - 国家/地区 | 可选 | 用户所在的国家/地区或提供服务的国家/地区。 | 自由文本 建议的文本大小：最多约 20 个字符 |
| 位置 - 城市 | 可选 | 用户所在或提供服务的城市。 | 自由文本 建议的文本大小：最多约 20 个字符 |
| 位置 - 显示地址 | 可选 | 系统会向用户显示该用户所在的或提供服务的地址。 | 自由文本 建议的文本大小：最多约 20 个字符 |
| 位置 - 街道地址 | 可选 | 用户所在地或提供服务的街道地址（如果适用）。 | 自由文本 建议的文本大小：最多约 20 个字符 |
| 位置 - 州/省 | 可选 | 此人所在的或提供服务的州（如果适用）。 | 自由文本 建议的文本大小：最多约 20 个字符 |
| 位置 - 邮政编码 | 可选 | 用户所在地或提供服务的邮政编码（如适用）。 | 自由文本 建议的文本大小：最多约 20 个字符 |
| 位置 - 街区 | 可选 | 用户所在地或提供服务的社区（如适用）。 | 自由文本 建议的文本大小：最多约 20 个字符 |
| 徽章 | 可选 |
每个标志要么是自由文本（最多 15 个字符），要么是小图片。 |
|
| 标记 - 文本 | 可选 | 徽章的标题 注意：徽章必须提供文字或图片 |
自由文本 建议的文本大小：不超过 15 个字符 |
| 徽章 - 图片 | 可选 | 小图片 特殊的用户体验处理，例如，在图片/视频缩略图上叠加显示徽章。 注意：徽章必须提供文字或图片 |
如需相关指导，请参阅图片规范。 |
| 说明 | 可选 | 用于描述实体的单段文本。 注意：系统将向用户显示说明或字幕列表，不能同时显示两者。 |
自由文本 建议的文本大小：180 个字符 |
| 字幕列表 | 可选 | 最多 3 个字幕，每个字幕一行文字。 注意：系统将向用户显示说明或字幕列表，不能同时显示两者。 |
自由文本 每条副标题建议的文字大小：最多 50 个字符 |
| 内容分类 | 可选 | 描述实体中内容的类别。 | 符合条件的枚举列表
如需指导，请参阅“内容类别”部分。 |
EventEntity
| 属性 | 要求 | 说明 | 格式 |
|---|---|---|---|
| 操作 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 个字符 |
| 徽章 - 图片 | 可选 | 小图片 特殊的用户体验处理，例如，在图片/视频缩略图上叠加显示徽章。 注意：徽章必须提供文字或图片 |
如需相关指导，请参阅图片规范。 |
| 价格 - 当前价格 | 在特定条件下必需 |
活动门票/通行证的当前价格。 如果提供了带删除线的价格，则必须提供。 |
自由文本 |
| 价格 - 删除线 | 可选 | 活动门票/通行证的原价。 | 自由文本 |
| 价格宣传信息 | 可选 | 用于展示促销、活动、会员折扣（如果有）的价格宣传信息。 | 自由文本 建议的文本大小：少于 45 个字符（如果文本过长，可能会显示省略号） |
| 内容分类 | 可选 | 描述实体中内容的类别。 | 符合条件的枚举列表
如需指导，请参阅“内容类别”部分。 |
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 dp 的安全空间 |
如需相关指导，请参阅图片规范。 |
| 结束时间 | 可选 |
事件预计结束的纪元时间戳。 注意：这将以毫秒为单位。 |
纪元时间戳（以毫秒为单位） |
| 服务提供商 - 姓名 | 可选 |
服务提供商的名称。 注意：服务提供商需要输入文字或图片。 |
自由文本。例如，活动组织者/游览项目的姓名 |
| 服务提供商 - 图片 | 可选 |
服务提供商的徽标/图片。 注意：服务提供商需要输入文字或图片。 |
如需相关指导，请参阅图片规范。 |
| 说明 | 可选 | 用于描述实体的单段文本。 注意：系统将向用户显示说明或字幕列表，不能同时显示两者。 |
自由文本 建议的文本大小：180 个字符 |
| 字幕列表 | 可选 | 最多 3 个字幕，每个字幕一行文字。 注意：系统将向用户显示说明或字幕列表，不能同时显示两者。 |
自由文本 每条副标题建议的文字大小：最多 50 个字符 |
| 徽章 | 可选 |
每个标志要么是自由文本（最多 15 个字符），要么是小图片。 |
|
| 标记 - 文本 | 可选 | 徽章的标题 注意：徽章必须提供文字或图片 |
自由文本 建议的文本大小：不超过 15 个字符 |
| 徽章 - 图片 | 可选 | 小图片 特殊的用户体验处理，例如，在图片/视频缩略图上叠加显示徽章。 注意：徽章必须提供文字或图片 |
如需相关指导，请参阅图片规范。 |
| 预留 ID | 可选 | 事件预留的预留 ID。 | 自由文本 |
| 价格 - 当前价格 | 在特定条件下必需 |
活动门票/通行证的当前价格。 如果提供了带删除线的价格，则必须提供。 |
自由文本 |
| 价格 - 删除线 | 可选 | 活动门票/通行证的原价。 | 自由文本 |
| 价格宣传信息 | 可选 | 用于展示促销、活动、会员折扣（如果有）的价格宣传信息。 | 自由文本 建议的文本大小：少于 45 个字符（如果文本过长，可能会显示省略号） |
| 评分 - 最大值 | 可选 | 评分量表的最大值。 如果同时提供当前评分值，则必须提供。 |
数值 >= 0.0 |
| 评分 - 当前值 | 可选 | 评分量表的当前值。 如果同时提供最大评分值，则必须提供。 |
数值 >= 0.0 |
| 评分 - 计数 | 可选 | 事件的评分计数。 注意：如果您的应用想要控制如何向用户显示此字段，请提供此字段。请提供可向用户显示的简洁字符串。例如，如果计数为 1,000,000，请考虑使用 1M 等缩写，以免在较小的显示屏上被截断。 |
字符串 |
| 评分 - 计数值 | 可选 | 事件的评分计数。 注意：如果您不想自行处理显示缩写逻辑，请提供此字段。如果“计数”和“计数值”均存在，我们将使用向用户显示的“计数” |
长 |
| 内容分类 | 可选 | 描述实体中内容的类别。 | 符合条件的枚举列表
如需指导，请参阅“内容类别”部分。 |
图片规范
下表列出了图片素材资源必须遵循的规范：
| 宽高比 | 最小像素 | 建议的像素 |
|---|---|---|
方形 (1x1) 首选 |
300x300 | 1200x1200 |
| 横向 (1.91x1) | 600x314 | 1200x628 |
| 纵向 (4x5) | 480x600 | 960x1200 |
图片必须托管在公共 CDN 上，以便 Google 可以访问。
文件格式
PNG、JPG、静态 GIF、WebP
文件大小上限
5120 KB
其他建议
- 图片安全区域：将重要内容放在图片中间 80% 的区域内。
- 请使用透明背景，以便图片可在“深色主题”和“浅色主题”设置中正常显示。
内容类别
借助内容分类，应用可以发布属于多个类别的内容。这会将内容与某些预定义的类别对应起来，即：
TYPE_EDUCATIONTYPE_SPORTSTYPE_MOVIES_AND_TV_SHOWSTYPE_BOOKSTYPE_AUDIOBOOKSTYPE_MUSICTYPE_DIGITAL_GAMESTYPE_TRAVEL_AND_LOCALTYPE_HOME_AND_AUTOTYPE_BUSINESSTYPE_NEWSTYPE_FOOD_AND_DRINKTYPE_SHOPPINGTYPE_HEALTH_AND_FITENESSTYPE_MEDICALTYPE_PARENTINGTYPE_DATING
图片必须托管在公共 CDN 上，以便 Google 可以访问。
内容分类使用准则
- ArticleEntity 和 GenericFeaturedEntity 等实体可以使用任何内容类别。对于 EventEntity、EventReservationEntity、PersonEntity 等其他实体，只有这些类别中的一部分符合条件。在填充列表之前，请先查看符合某个实体类型的类别列表。
对某些内容分类使用特定实体类型，而不是同时使用通用实体和 ContentCategory：
- TYPE_MOVIES_AND_TV_SHOWS - 在使用通用实体之前，请先查看手表集成指南中的实体。
- TYPE_BOOKS - 在使用通用实体之前，请先查看 EbookEntity。
- TYPE_AUDIOBOOKS - 在使用通用实体之前，请先查看 AudiobookEntity。
- TYPE_SHOPPING - 在使用通用实体之前，请先查看 ShoppingEntity。
- TYPE_FOOD_AND_DRINK - 在使用通用实体之前，请先查看食品集成指南中的实体。
ContentCategory 字段是可选字段，如果内容不属于前面提到的任何类别，则应留空。
如果提供了多个内容分类，请按照与内容的相关性顺序提供这些分类，最相关的内容分类在列表中位于最前面。
第 2 步：提供集群数据
建议在后台执行内容发布作业（例如，使用 WorkManager），并安排定期执行或按事件执行（例如，每当用户打开应用时，或当用户刚刚将商品添加到购物车时）。
AppEngagePublishClient 负责发布集群。
以下 API 可用于在客户端中发布集群：
isServiceAvailablepublishRecommendationClusterspublishFeaturedClusterpublishContinuationClusterpublishUserAccountManagementRequestupdatePublishStatusdeleteRecommendationsClustersdeleteFeaturedClusterdeleteContinuationClusterdeleteUserManagementClusterdeleteClusters
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 商店后，您的推荐、精选和接续集群便可被发布并向用户显示。