Google 正在构建一个设备上的界面,该界面按垂直方向组织用户的应用,并为个性化应用内容的消费和发现提供新的沉浸式体验。此全屏体验为开发者合作伙伴提供了一个机会,让他们可以在其应用之外的专用频道中展示其最佳的丰富内容。本指南包含开发者合作伙伴使用 Engage SDK 填充此新界面区域以集成其旅行和活动内容的说明。
集成详情
术语
此集成包括以下三种集群类型:**推荐**、**精选**和**续播**。
**推荐**集群显示来自单个开发者合作伙伴的个性化旅行和活动建议。这些建议可以个性化到用户或泛化(例如,趋势项目)。使用这些来显示文章、活动、住宿或兴趣点推荐。
- 推荐集群可以由
ArticleEntity
、EventEntity
、LodgingEntity
、PointOfInterestEntity
或StoreEntity
列表组成,但不能混合使用不同类型的实体。
您的推荐采用以下结构
**推荐集群:**包含来自同一开发者合作伙伴的一组推荐的 UI 视图。
**实体:**表示集群中单个项目的对象。此集成提供了一些将使用推荐集群显示的实体
**ArticleEntity**:ArticleEntity 代表与旅行和活动相关的基于文本内容的推荐。它可以用于文章、博客文章、营销内容、新闻片段等。
**EventEntity**:EventEntity 代表未来发生的事件。事件开始时间是需要传达给用户的重要信息。
**LodgingEntity**:LodgingEntity 代表住宿,例如酒店、公寓、短期和长期出租的度假屋。
**StoreEntity**:StoreEntity 代表商店、餐馆、咖啡馆等。它突出显示内容,其中餐厅或商店是需要传达给用户的关键信息。
**PointOfInterestEntity**:PointOfInterestEntity 代表一个兴趣点,例如加油站、活动场地、主题公园、博物馆、旅游景点、远足路线等。它突出显示内容,其中位置是需要传达给用户的关键信息。它不应用于住宿、商店或餐厅。
- 推荐集群可以由
**续播**集群在一个 UI 分组中显示来自多个开发者合作伙伴的用户最近参与的内容。每个开发者合作伙伴最多可以在续播集群中广播 10 个实体。
您的续播内容可以采用以下结构
**ArticleEntity**:ArticleEntity 代表与旅行和活动相关的推荐内容。此实体可用于表示用户想继续从上次中断的地方继续消费的未完成新闻文章或其他内容。例如:关于旅游目的地或活动的新闻片段、博客文章片段。
**RestaurantReservationEntity**:RestaurantReservationEntity 代表餐厅或咖啡馆的预订,并帮助用户跟踪即将到来的或正在进行的餐厅预订。
EventReservationEntity(事件预订实体):EventReservationEntity 代表一个事件的预订,帮助用户追踪即将到来或正在进行的事件预订。事件可以包括但不限于以下类型:
- 体育赛事,例如足球比赛预订
- 电竞赛事,例如电子竞技比赛预订
- 娱乐活动,例如电影院观影、音乐会、戏剧表演、签书会预订
- 旅游或景点预订,例如导游服务、博物馆门票
- 社交/研讨会/会议预订
- 教育/培训课程预订
LodgingReservationEntity(住宿预订实体):LodgingEntityReservation 代表旅行住宿的预订,帮助用户追踪即将到来或正在进行的酒店或度假租赁预订。
TransportationReservationEntity(交通工具预订实体):TransportationReservationEntity 代表任何交通方式的预订,帮助用户追踪即将到来或正在进行的航班、渡轮、火车、巴士、网约车或邮轮预订。
VehicleRentalReservationEntity(车辆租赁预订实体):VehicleRentalReservationEntity 代表车辆租赁预订,帮助用户追踪即将到来或正在进行的车辆租赁预订。
Featured(特色)集群在一个 UI 分组中展示来自多个开发者合作伙伴的实体选择。将只有一个 Featured 集群,它位于 UI 顶部附近,优先级高于所有 Recommendation 集群。每个开发者合作伙伴最多可以在 Featured 集群中广播 10 个实体。
GenericFeaturedEntity(通用特色实体):GenericFeaturedEntity 与 Recommendation 项目的不同之处在于,Featured 项目应用于开发者的单个顶级内容,并应代表对用户最有趣和最相关的单个最重要内容。
前期准备工作
最低 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'
}
总结
此设计基于 绑定服务 的实现。
客户端可以发布的数据受不同集群类型的以下限制:
集群类型 | 集群限制 | 集群中实体的最小数量 | 集群中实体的最大数量 |
---|---|---|---|
Recommendation 集群 | 最多 5 个 | 至少 5 个 | 最多 25 个(ArticleEntity 、EventEntity 、LodgingEntity 、StoreEntity 或 PointOfInterestEntity ) |
Continuation 集群 | 最多 1 个 | 至少 1 个 | 最多 10 个(ArticleEntity 、RestaurantReservationEntity 、EventReservationEntity 、LodgingReservationEntity 、TransportationReservationEntity 或 VehicleRentalReservationEntity ) |
Featured 集群 | 最多 1 个 | 至少 1 个 | 最多 10 个(GenericFeaturedEntity ) |
步骤 1:提供实体数据
SDK 定义了不同的实体来表示每种项目类型。我们支持以下针对旅游和活动的类别实体:
GenericFeaturedEntity
ArticleEntity
EventEntity
LodgingEntity
StoreEntity
PointOfInterestEntity
RestaurantReservationEntity
EventReservationEntity
LodgingReservationEntity
TransportationReservationEntity
VehicleRentalReservationEntity
下表概述了每种类型的可用属性和要求。
GenericFeaturedEntity
属性 | 要求 | 描述 | 格式 |
---|---|---|---|
Action Uri(操作 URI) | 必填 |
指向提供商应用中实体的深度链接。 注意:您可以使用深度链接进行归因。 请参阅此常见问题解答 |
Uri |
海报图片 | 必填 | 提供多张图片时,我们只会显示一张图片。建议的纵横比为 16:9 注意:如果提供徽章,请确保图片顶部和底部的安全空间为 24 dp |
请参阅 图片规格 以获取指导。 |
标题 | 可选 | 实体的标题。 | 自由文本 建议文本大小:50 个字符 |
描述 | 可选 | 一段描述实体的文本。 注意:将向用户显示描述或副标题列表,两者不会同时显示。 |
自由文本 建议文本大小:180 个字符 |
副标题列表 | 可选 | 最多 3 个副标题,每个副标题为一行文本。 注意:将向用户显示描述或副标题列表,两者不会同时显示。 |
自由文本 每个副标题的建议文本大小:最大 50 个字符 |
徽章 | 可选 | 每个徽章都是自由文本(最多 15 个字符)或小图片。 图片/视频顶部的特殊 UX 处理,例如作为图片上的徽章叠加层
|
|
徽章 - 文本 | 可选 | 徽章的标题 注意:徽章需要文本或图片 |
自由文本 建议文本大小:最大 15 个字符 |
徽章 - 图片 | 可选 | 小图片 特殊的 UX 处理,例如作为图片/视频缩略图上的徽章叠加层。 注意:徽章需要文本或图片 |
请参阅 图片规格 以获取指导。 |
内容类别 | 可选 | 描述实体中内容的类别。 | 枚举列表 请参阅 内容类别部分 以获取指导。 |
ArticleEntity
属性 | 要求 | 描述 | 格式 |
---|---|---|---|
Action Uri(操作 URI) | 必填 |
指向提供商应用中实体的深度链接。 注意:您可以使用深度链接进行归因。 请参阅此常见问题解答 |
Uri |
标题 | 必填 | 实体的标题。 | 自由文本 建议文本大小:最大 50 个字符 |
海报图片 | 可选 | 提供多张图片时,我们只会显示一张图片。建议的纵横比为 16:9 注意:强烈建议使用图片。如果提供徽章,请确保图片顶部和底部的安全空间为 24 dp |
请参阅 图片规格 以获取指导。 |
来源 - 标题 | 可选 | 作者、组织或记者的姓名 | 自由文本 建议文本大小:少于 25 个字符 |
来源 - 图片 | 可选 | 来源的图片,例如作者、组织、记者 | 请参阅 图片规格 以获取指导。 |
描述 | 可选 | 一段描述实体的文本。 注意:将向用户显示描述或副标题列表,两者不会同时显示。 |
自由文本 建议文本大小:180 个字符 |
副标题列表 | 可选 | 最多 3 个副标题,每个副标题为一行文本。 注意:将向用户显示描述或副标题列表,两者不会同时显示。 |
自由文本 每个副标题的建议文本大小:最大 50 个字符 |
徽章 | 可选 | 每个徽章都是自由文本(最多 15 个字符)或小图片。 图片/视频顶部的特殊 UX 处理,例如作为图片上的徽章叠加层
|
|
徽章 - 文本 | 可选 | 徽章的标题 注意:徽章需要文本或图片 |
自由文本 建议文本大小:最大 15 个字符 |
徽章 - 图片 | 可选 | 小图片 特殊的 UX 处理,例如作为图片/视频缩略图上的徽章叠加层。 注意:徽章需要文本或图片 |
请参阅 图片规格 以获取指导。 |
内容发布时间 | 可选 | 内容在应用中发布/更新时的以毫秒为单位的纪元时间戳。 | 以毫秒为单位的纪元时间戳 |
上次参与时间 | 条件性必填 | 用户上次与该实体互动时的以毫秒为单位的纪元时间戳。 注意:如果此实体是 Continuation 集群的一部分,则此字段为必填字段。 |
以毫秒为单位的纪元时间戳 |
进度百分比 | 条件性必填 | 用户迄今为止消费的完整内容的百分比。 注意:如果此实体是 Continuation 集群的一部分,则此字段为必填字段。 |
0~100(含)之间的整数值。 |
内容类别 | 可选 | 描述实体中内容的类别。 | 枚举列表 请参阅 内容类别部分 以获取指导。 |
EventEntity
属性 | 要求 | 描述 | 格式 |
---|---|---|---|
Action Uri(操作 URI) | 必填 |
指向提供商应用中实体的深度链接。 注意:您可以使用深度链接进行归因。 请参阅此常见问题解答 |
Uri |
标题 | 必填 | 实体的标题。 | 字符串 建议文本大小:最大 50 个字符 |
开始时间 | 必填 |
预期事件开始时的纪元时间戳。 注意:这将以毫秒为单位表示。 |
以毫秒为单位的纪元时间戳 |
事件模式 | 必填 | 一个字段,用于指示事件将是虚拟的、线下的还是两者兼而有之。 |
枚举:VIRTUAL、IN_PERSON 或 HYBRID |
海报图片 | 必填 | 提供多张图片时,我们只会显示一张图片。建议的纵横比为 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 个字符(过长的文本可能会显示省略号) |
内容类别 | 可选 | 描述实体中内容的类别。 | 合格枚举列表
请参阅 内容类别部分 以获取指导。 |
LodgingEntity
属性 | 要求 | 描述 | 格式 |
---|---|---|---|
Action Uri(操作 URI) | 必填 |
指向提供商应用中实体的深度链接。 注意:您可以使用深度链接进行归因。 请参阅此常见问题解答 |
Uri |
标题 | 必填 | 实体的标题。 | 字符串 建议文本大小:最大 50 个字符 |
海报图片 | 必填 |
提供多张图片时,我们只会显示一张图片。建议的纵横比为 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) | 必填 |
指向提供商应用中实体的深度链接。 注意:您可以使用深度链接进行归因。 请参阅此常见问题解答 |
Uri |
标题 | 可选 | 商店的名称。 | 自由文本 建议文本大小:少于 45 个字符(过长的文本可能会显示省略号) |
位置 | 可选 | 商店位置。 | 自由文本 建议文本大小:少于 45 个字符(过长的文本可能会显示省略号) |
宣传标语 | 可选 | 如有可用,宣传标语用于宣传商店的促销活动、活动或更新。 | 自由文本 建议文本大小:少于 45 个字符(过长的文本可能会显示省略号) |
宣传标语小字 | 可选 | 宣传标语的小字文本。 | 自由文本 建议文本大小:少于 45 个字符(过长的文本可能会显示省略号) |
描述 | 可选 | 商店描述。 | 自由文本 建议文本大小:少于 90 个字符(过长的文本可能会显示省略号) |
评分 - 最大值 | 可选 | 评分量表的最大值。 如果也提供了评分的当前值,则必须提供此项。 |
数字 >= 0.0 |
评分 - 当前值 | 可选 | 评分量表的当前值。 如果也提供了评分的最大值,则必须提供此项。 |
数字 >= 0.0 |
评分 - 计数 | 可选 | 住宿评分的计数。 注意:如果您的应用想要控制如何向用户显示此内容,请提供此字段。提供可以向用户显示的简洁字符串。例如,如果计数为 1,000,000,请考虑使用 1M 等缩写,这样它就不会在较小的显示尺寸上被截断。 |
字符串 |
评分 - 计数值 | 可选 | 住宿评分的计数。 注意:如果您不想自己处理显示缩写逻辑,请提供此字段。如果同时存在 Count 和 Count Value,我们将使用 Count 向用户显示。 |
长整型 |
PointOfInterestEntity
属性 | 要求 | 描述 | 格式 |
---|---|---|---|
Action Uri(操作 URI) | 必填 |
指向提供商应用中实体的深度链接。 注意:您可以使用深度链接进行归因。 请参阅此常见问题解答 |
Uri |
标题 | 必填 | 实体的标题。 | 字符串 建议文本大小:最大 50 个字符 |
海报图片 | 必填 | 提供多张图片时,我们只会显示一张图片。建议的纵横比为 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 个字符(过长的文本可能会显示省略号) |
内容类别 | 可选 | 描述实体中内容的类别。 | 合格枚举列表
请参阅 内容类别部分 以获取指导。 |
RestaurantReservationEntity
属性 | 要求 | 描述 | 格式 |
---|---|---|---|
Action Uri(操作 URI) | 必填 |
指向提供商应用中实体的深度链接。 注意:您可以使用深度链接进行归因。 请参阅此常见问题解答 |
Uri |
标题 | 必填 | 实体的标题。 | 字符串 建议文本大小:最大 50 个字符 |
预订开始时间 | 必填 | 预订预计开始的纪元时间戳(毫秒)。 | 以毫秒为单位的纪元时间戳 |
位置 - 国家 | 必填 | 餐厅所在的国家。 | 自由文本 建议文本大小:最大约 20 个字符 |
位置 - 城市 | 必填 | 餐厅所在的城市。 | 自由文本 建议文本大小:最大约 20 个字符 |
位置 - 显示地址 | 必填 | 将显示给用户的餐厅地址。 | 自由文本 建议文本大小:最大约 20 个字符 |
位置 - 街道地址 | 可选 | 餐厅的街道地址(如果适用)。 | 自由文本 建议文本大小:最大约 20 个字符 |
位置 - 州/省 | 可选 | 餐厅所在的州或省份(如果适用)。 | 自由文本 建议文本大小:最大约 20 个字符 |
位置 - 邮政编码 | 可选 | 餐厅的邮政编码(如果适用)。 | 自由文本 建议文本大小:最大约 20 个字符 |
位置 - 街区 | 可选 | 餐厅所在的街区(如果适用)。 | 自由文本 建议文本大小:最大约 20 个字符 |
海报图片 | 可选 | 提供多张图片时,我们只会显示一张图片。建议的纵横比为 16:9 | 请参阅 图片规格 以获取指导。 |
描述 | 可选 | 一段描述实体的文本。 注意:将向用户显示描述或副标题列表,两者不会同时显示。 |
自由文本 建议文本大小:180 个字符 |
副标题列表 | 可选 | 最多 3 个副标题,每个副标题为一行文本。 注意:将向用户显示描述或副标题列表,两者不会同时显示。 |
自由文本 每个副标题的建议文本大小:最大 50 个字符 |
餐桌大小 | 可选 | 预订组的人数 | 整数 > 0 |
EventReservationEntity
属性 | 要求 | 描述 | 格式 |
---|---|---|---|
Action Uri(操作 URI) | 必填 |
指向提供商应用中实体的深度链接。 注意:您可以使用深度链接进行归因。 请参阅此常见问题解答 |
Uri |
标题 | 必填 | 实体的标题。 | 字符串 建议文本大小:最大 50 个字符 |
开始时间 | 必填 |
预期事件开始时的纪元时间戳。 注意:这将以毫秒为单位表示。 |
以毫秒为单位的纪元时间戳 |
事件模式 | 必填 | 一个字段,用于指示事件将是虚拟的、线下的还是两者兼而有之。 |
枚举:VIRTUAL、IN_PERSON 或 HYBRID |
位置 - 国家 | 条件性必填 | 举办事件的国家。 注意:对于 IN_PERSON 或 HYBRID 事件,此项为必填项 |
自由文本 建议文本大小:最大约 20 个字符 |
位置 - 城市 | 条件性必填 | 举办事件的城市。 注意:对于 IN_PERSON 或 HYBRID 事件,此项为必填项 |
自由文本 建议文本大小:最大约 20 个字符 |
位置 - 显示地址 | 条件性必填 | 应向用户显示的事件举办地点的地址或场馆名称。 注意:对于 IN_PERSON 或 HYBRID 事件,此项为必填项 |
自由文本 建议文本大小:最大约 20 个字符 |
位置 - 街道地址 | 可选 | 举办事件的地点的街道地址(如果适用)。 | 自由文本 建议文本大小:最大约 20 个字符 |
位置 - 州/省 | 可选 | 举办事件的州或省(如果适用)。 | 自由文本 建议文本大小:最大约 20 个字符 |
位置 - 邮政编码 | 可选 | 举办事件的地点的邮政编码(如果适用)。 | 自由文本 建议文本大小:最大约 20 个字符 |
位置 - 街区 | 可选 | 举办事件的街区(如果适用)。 | 自由文本 建议文本大小:最大约 20 个字符 |
海报图片 | 可选 | 提供多张图片时,我们只会显示一张图片。建议的纵横比为 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 向用户显示。 |
长整型 |
内容类别 | 可选 | 描述实体中内容的类别。 | 合格枚举列表
请参阅 内容类别部分 以获取指导。 |
LodgingReservationEntity
属性 | 要求 | 描述 | 格式 |
---|---|---|---|
Action Uri(操作 URI) | 必填 |
指向提供商应用中实体的深度链接。 注意:您可以使用深度链接进行归因。 请参阅此常见问题解答 |
Uri |
标题 | 必填 | 实体的标题。 | 自由文本。例如,“您从 12 月 12 日起的住宿” 建议文本大小:最大 50 个字符 |
入住时间 | 必填 | 代表预订入住时间的纪元时间戳(毫秒)。 | 以毫秒为单位的纪元时间戳 |
退房时间 | 必填 | 代表预订退房时间的纪元时间戳(毫秒)。 | 以毫秒为单位的纪元时间戳 |
位置 - 国家 | 必填 | 住宿所在的国家。 | 自由文本 建议文本大小:最大约 20 个字符 |
位置 - 城市 | 必填 | 住宿所在的城市。 | 自由文本 建议文本大小:最大约 20 个字符 |
位置 - 显示地址 | 必填 | 将向用户显示的住宿地址。 | 自由文本 建议文本大小:最大约 20 个字符 |
位置 - 街道地址 | 可选 | 住宿的街道地址(如果适用)。 | 自由文本 建议文本大小:最大约 20 个字符 |
位置 - 州/省 | 可选 | 住宿所在的州或省(如果适用)。 | 自由文本 建议文本大小:最大约 20 个字符 |
位置 - 邮政编码 | 可选 | 住宿的邮政编码(如果适用)。 | 自由文本 建议文本大小:最大约 20 个字符 |
位置 - 街区 | 可选 | 住宿的街区(如果适用)。 | 自由文本 建议文本大小:最大约 20 个字符 |
海报图片 | 可选 |
提供多张图片时,我们只会显示一张图片。建议的纵横比为 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) | 必填 |
指向提供商应用中实体的深度链接。 注意:您可以使用深度链接进行归因。 请参阅此常见问题解答 |
Uri |
标题 | 必填 | 实体的标题。 | 自由文本。例如,“SFO 至 SAN” 建议文本大小:最大 50 个字符 |
交通工具类型 | 必填 | 预订的交通方式/类型。 | 枚举:FLIGHT、TRAIN、BUS 或 FERRY |
出发时间 | 必填 | 代表出发时间的纪元时间戳(毫秒)。 | 以毫秒为单位的纪元时间戳 |
到达时间 | 必填 | 代表到达时间的纪元时间戳(毫秒)。 | 以毫秒为单位的纪元时间戳 |
出发地点 - 国家 | 可选 | 出发国家。 | 自由文本 建议文本大小:最大约 20 个字符 |
出发地点 - 城市 | 可选 | 出发城市。 | 自由文本 建议文本大小:最大约 20 个字符 |
出发地点 - 显示地址 | 可选 | 将显示给用户的出发地点。 | 自由文本 建议文本大小:最大约 20 个字符 |
出发地点 - 街道地址 | 可选 | 出发地点的街道地址(如果适用)。 | 自由文本 建议文本大小:最大约 20 个字符 |
出发地点 - 州/省 | 可选 | 出发地点的州或省份(如果适用)。 | 自由文本 建议文本大小:最大约 20 个字符 |
出发地点 - 邮政编码 | 可选 | 出发地点的邮政编码(如果适用)。 | 自由文本 建议文本大小:最大约 20 个字符 |
出发地点 - 街区 | 可选 | 出发地点的街区(如果适用)。 | 自由文本 建议文本大小:最大约 20 个字符 |
到达地点 - 国家 | 可选 | 到达国家。 | 自由文本 建议文本大小:最大约 20 个字符 |
到达地点 - 城市 | 可选 | 到达城市。 | 自由文本 建议文本大小:最大约 20 个字符 |
到达地点 - 显示地址 | 可选 | 将显示给用户的到达地点。 | 自由文本 建议文本大小:最大约 20 个字符 |
到达地点 - 街道地址 | 可选 | 到达地点的街道地址(如果适用)。 | 自由文本 建议文本大小:最大约 20 个字符 |
到达地点 - 州/省 | 可选 | 到达地点的州或省份(如果适用)。 | 自由文本 建议文本大小:最大约 20 个字符 |
到达地点 - 邮政编码 | 可选 | 到达地点的邮政编码(如果适用)。 | 自由文本 建议文本大小:最大约 20 个字符 |
到达地点 - 街区 | 可选 | 到达地点的街区(如果适用)。 | 自由文本 建议文本大小:最大约 20 个字符 |
服务提供商 - 名称 | 可选 |
服务提供商的名称。 注意:服务提供商需要文本或图像。 |
自由文本。例如,航空公司名称 |
服务提供商 - 图片 | 可选 |
服务提供商的徽标/图片。 注意:服务提供商需要文本或图像。 |
请参阅 图片规格 以获取指导。 |
海报图片 | 可选 |
提供多张图片时,我们只会显示一张图片。建议的纵横比为 16:9 |
请参阅 图片规格 以获取指导。 |
描述 | 可选 | 一段描述实体的文本。 注意:将向用户显示描述或副标题列表,两者不会同时显示。 |
自由文本 建议文本大小:180 个字符 |
副标题列表 | 可选 | 最多 3 个副标题,每个副标题为一行文本。 注意:将向用户显示描述或副标题列表,两者不会同时显示。 |
自由文本 每个副标题的建议文本大小:最大 50 个字符 |
预订 ID | 可选 | 交通工具预订的预订 ID。 | 自由文本 |
价格 - 当前价格 | 条件性必填 | 预订的当前价格。 如果提供了划掉的价格,则必须提供此项。 |
自由文本 |
价格 - 划掉的价格 | 可选 | 预订的原价,在 UI 中将被删除线。 | 自由文本 |
价格标注 | 可选 | 价格标注,用于显示促销、活动、会员折扣(如果可用)。 | 自由文本 建议文本大小:少于 45 个字符(过长的文本可能会显示省略号) |
交通工具编号 | 必填 | 航班号、公交车号、火车号或渡轮/邮轮号。 | 自由文本 |
登机时间 | 必填 | 代表预订登机时间的纪元时间戳(如果适用)。 | 以毫秒为单位的纪元时间戳 |
VehicleRentalReservationEntity
属性 | 要求 | 描述 | 格式 |
---|---|---|---|
Action Uri(操作 URI) | 必填 |
指向提供商应用中实体的深度链接。 注意:您可以使用深度链接进行归因。 请参阅此常见问题解答 |
Uri |
标题 | 必填 | 实体的标题。 | 自由文本。例如,“Avis Union Square SF” 建议文本大小:最大 50 个字符 |
取车时间 | 必填 | 代表预订取车时间的纪元时间戳。 | 以毫秒为单位的纪元时间戳 |
还车时间 | 可选 | 代表预订退还时间的纪元时间戳。 | 以毫秒为单位的纪元时间戳 |
取车地址 - 国家 | 可选 | 取车地点的国家。 | 自由文本 建议文本大小:最大约 20 个字符 |
取车地址 - 城市 | 可选 | 取车地点的城市。 | 自由文本 建议文本大小:最大约 20 个字符 |
取车地址 - 显示地址 | 可选 | 将显示给用户的取车地点。 | 自由文本 建议文本大小:最大约 20 个字符 |
取车地址 - 街道地址 | 可选 | 取车地点的街道地址(如果适用)。 | 自由文本 建议文本大小:最大约 20 个字符 |
取车地址 - 州/省 | 可选 | 取车地点的州或省份(如果适用)。 | 自由文本 建议文本大小:最大约 20 个字符 |
取车地址 - 邮政编码 | 可选 | 取车地点的邮政编码(如果适用)。 | 自由文本 建议文本大小:最大约 20 个字符 |
取车地址 - 街区 | 可选 | 取车地点的街区(如果适用)。 | 自由文本 建议文本大小:最大约 20 个字符 |
还车地址 - 国家 | 可选 | 还车地点的国家。 | 自由文本 建议文本大小:最大约 20 个字符 |
还车地址 - 城市 | 可选 | 还车地点的城市。 | 自由文本 建议文本大小:最大约 20 个字符 |
还车地址 - 显示地址 | 可选 | 将显示给用户的还车地点。 | 自由文本 建议文本大小:最大约 20 个字符 |
还车地址 - 街道地址 | 可选 | 还车地点的街道地址(如果适用)。 | 自由文本 建议文本大小:最大约 20 个字符 |
还车地址 - 州/省 | 可选 | 还车地点的州或省份(如果适用)。 | 自由文本 建议文本大小:最大约 20 个字符 |
还车地址 - 邮政编码 | 可选 | 还车地点的邮政编码(如果适用)。 | 自由文本 建议文本大小:最大约 20 个字符 |
还车地址 - 街区 | 可选 | 还车地点的街区(如果适用)。 | 自由文本 建议文本大小:最大约 20 个字符 |
服务提供商 - 名称 | 可选 |
服务提供商的名称。 注意:服务提供商需要文本或图像。 |
自由文本。例如,“Avis 租车” |
服务提供商 - 图片 | 可选 |
服务提供商的徽标/图片。 注意:服务提供商需要文本或图像。 |
请参阅 图片规格 以获取指导。 |
海报图片 | 可选 |
提供多张图片时,我们只会显示一张图片。建议的纵横比为 16:9 |
请参阅 图片规格 以获取指导。 |
描述 | 可选 | 一段描述实体的文本。 注意:将向用户显示描述或副标题列表,两者不会同时显示。 |
自由文本 建议文本大小:180 个字符 |
副标题列表 | 可选 | 最多 3 个副标题,每个副标题为一行文本。 注意:将向用户显示描述或副标题列表,两者不会同时显示。 |
自由文本 每个副标题的建议文本大小:最大 50 个字符 |
确认 ID | 可选 | 车辆租赁预订的确认 ID。 | 自由文本 |
价格 - 当前价格 | 条件性必填 | 预订的当前价格。 如果提供了划掉的价格,则必须提供此项。 |
自由文本 |
价格 - 划掉的价格 | 可选 | 预订的原价,在 UI 中将被删除线。 | 自由文本 |
价格标注 | 可选 | 价格标注,用于显示促销、活动、会员折扣(如果可用)。 | 自由文本 建议文本大小:少于 45 个字符(过长的文本可能会显示省略号) |
图片规格
此表列出了图像资源的必需规格
宽高比 | 最小像素 | 推荐像素 |
---|---|---|
正方形 (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 - 在使用通用实体之前,请查看Watch 集成指南中的实体。
- TYPE_BOOKS - 在使用通用实体之前,请查看EbookEntity。
- TYPE_AUDIOBOOKS - 在使用通用实体之前,请查看AudiobookEntity。
- TYPE_SHOPPING - 在使用通用实体之前,请查看ShoppingEntity。
- TYPE_FOOD_AND_DRINK - 在使用通用实体之前,请查看食品集成指南中的实体。
ContentCategory 字段是可选的,如果内容不属于前面提到的任何类别,则应将其留空。
如果提供了多个内容类别,请按与内容的相关性顺序提供它们,并将最相关的类别放在列表的第一个位置。
步骤 2:提供集群数据
建议在后台执行内容发布作业(例如,使用WorkManager)并定期或基于事件(例如,每次用户打开应用或用户刚刚将某些内容添加到购物车时)进行调度。
AppEngagePublishClient
负责发布集群。
客户端有以下 API 用于发布集群
isServiceAvailable
publishRecommendationClusters
publishFeaturedCluster
publishContinuationCluster
publishUserAccountManagementRequest
updatePublishStatus
deleteRecommendationsClusters
deleteFeaturedCluster
deleteContinuationCluster
deleteUserManagementCluster
deleteClusters
isServiceAvailable
此 API 用于检查服务是否可用于集成以及内容是否可以显示在设备上。
Kotlin
client.isServiceAvailable.addOnCompleteListener { task -> if (task.isSuccessful) { // Handle IPC call success if(task.result) { // Service is available on the device, proceed with content publish // calls. } else { // Service is not available, no further action is needed. } } else { // The IPC call itself fails, proceed with error handling logic here, // such as retry. } }
Java
client.isServiceAvailable().addOnCompleteListener(task - > { if (task.isSuccessful()) { // Handle success if(task.getResult()) { // Service is available on the device, proceed with content publish // calls. } else { // Service is not available, no further action is needed. } } else { // The IPC call itself fails, proceed with error handling logic here, // such as retry. } });
publishRecommendationClusters
此 API 用于发布 RecommendationCluster
对象列表。
Kotlin
client.publishRecommendationClusters( PublishRecommendationClustersRequest.Builder() .addRecommendationCluster( RecommendationCluster.Builder() .addEntity(entity1) .addEntity(entity2) .setTitle("Top Picks For You") .build() ) .build() )
Java
client.publishRecommendationClusters( new PublishRecommendationClustersRequest.Builder() .addRecommendationCluster( new RecommendationCluster.Builder() .addEntity(entity1) .addEntity(entity2) .setTitle("Top Picks For You") .build()) .build());
当服务收到请求时,以下操作将在一个事务中进行
- 删除开发者合作伙伴的现有
RecommendationCluster
数据。 - 解析请求中的数据并将其存储在更新后的推荐集群中。
如果发生错误,则整个请求将被拒绝,并保持现有状态。
publishFeaturedCluster
此 API 用于发布 FeaturedCluster
对象列表。
Kotlin
client.publishFeaturedCluster( PublishFeaturedClusterRequest.Builder() .setFeaturedCluster( FeaturedCluster.Builder() .addEntity(entity1) .addEntity(entity2) .build()) .build())
Java
client.publishFeaturedCluster( new PublishFeaturedClustersRequest.Builder() .addFeaturedCluster( new FeaturedCluster.Builder() .addEntity(entity1) .addEntity(entity2) .build()) .build());
当服务收到请求时,以下操作将在一个事务中进行
- 删除开发者合作伙伴的现有
FeaturedCluster
数据。 - 解析请求中的数据并将其存储在更新后的特色集群中。
如果发生错误,则整个请求将被拒绝,并保持现有状态。
publishContinuationCluster
此 API 用于发布 ContinuationCluster
对象。
Kotlin
client.publishContinuationCluster( PublishContinuationClusterRequest.Builder() .setContinuationCluster( ContinuationCluster.Builder() .addEntity(entity1) .addEntity(entity2) .build()) .build())
Java
client.publishContinuationCluster( new PublishContinuationClusterRequest.Builder() .setContinuationCluster( new ContinuationCluster.Builder() .addEntity(entity1) .addEntity(entity2) .build()) .build());
当服务收到请求时,以下操作将在一个事务中进行
- 删除开发者合作伙伴的现有
ContinuationCluster
数据。 - 解析请求中的数据并将其存储在更新后的续集集群中。
如果发生错误,则整个请求将被拒绝,并保持现有状态。
publishUserAccountManagementRequest
此 API 用于发布登录卡片。登录操作将用户引导至应用的登录页面,以便应用可以发布内容(或提供更个性化的内容)。
登录卡片包含以下元数据:
属性 | 要求 | 描述 |
---|---|---|
Action Uri(操作 URI) | 必填 | 指向操作的深层链接(即导航到应用登录页面) |
图片 | 可选 - 如果未提供,则必须提供标题 |
卡片上显示的图片 16:9 宽高比的图片,分辨率为 1264x712 |
标题 | 可选 - 如果未提供,则必须提供图片 | 卡片上的标题 |
操作文本 | 可选 | CTA 上显示的文本(即登录) |
副标题 | 可选 | 卡片上的可选副标题 |
Kotlin
var SIGN_IN_CARD_ENTITY = SignInCardEntity.Builder() .addPosterImage( Image.Builder() .setImageUri(Uri.parse("http://www.x.com/image.png")) .setImageHeightInPixel(500) .setImageWidthInPixel(500) .build()) .setActionText("Sign In") .setActionUri(Uri.parse("http://xx.com/signin")) .build() client.publishUserAccountManagementRequest( PublishUserAccountManagementRequest.Builder() .setSignInCardEntity(SIGN_IN_CARD_ENTITY) .build());
Java
SignInCardEntity SIGN_IN_CARD_ENTITY = new SignInCardEntity.Builder() .addPosterImage( new Image.Builder() .setImageUri(Uri.parse("http://www.x.com/image.png")) .setImageHeightInPixel(500) .setImageWidthInPixel(500) .build()) .setActionText("Sign In") .setActionUri(Uri.parse("http://xx.com/signin")) .build(); client.publishUserAccountManagementRequest( new PublishUserAccountManagementRequest.Builder() .setSignInCardEntity(SIGN_IN_CARD_ENTITY) .build());
当服务收到请求时,以下操作将在一个事务中进行
- 删除开发者合作伙伴的现有
UserAccountManagementCluster
数据。 - 解析请求中的数据并将其存储在更新后的用户帐户管理集群中。
如果发生错误,则整个请求将被拒绝,并保持现有状态。
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
返回。
错误代码 | 错误名称 | 说明 |
---|---|---|
1 |
SERVICE_NOT_FOUND |
给定设备上服务不可用。 |
2 |
SERVICE_NOT_AVAILABLE |
给定设备上服务可用,但在调用时不可用(例如,它被明确禁用)。 |
3 |
SERVICE_CALL_EXECUTION_FAILURE |
由于线程问题导致任务执行失败。在这种情况下,可以重试。 |
4 |
SERVICE_CALL_PERMISSION_DENIED |
调用方无权进行服务调用。 |
5 |
SERVICE_CALL_INVALID_ARGUMENT |
请求包含无效数据(例如,超过允许的集群数量)。 |
6 |
SERVICE_CALL_INTERNAL |
服务端发生错误。 |
7 |
SERVICE_CALL_RESOURCE_EXHAUSTED |
服务调用过于频繁。 |
步骤 3:处理广播意图
除了通过作业进行内容发布 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 商店后,您的推荐、特色和续集集群可能会发布并对用户可见。