Engage SDK 健康与健身：第三方技术集成说明

通过在用户所在位置触达他们来提升应用互动度。集成 Engage SDK 可将个性化推荐和连续内容直接提供给跨多个设备界面的用户，例如 收藏集、娱乐空间 以及 Play 商店。该集成将平均 APK 大小增加不到 50 KB（压缩后），大部分应用只需大约一周的开发时间。访问我们的 商业网站 了解详情。

本指南包含开发者合作伙伴的说明，用于向 Engage 内容界面提供健康与健身内容。

集成详情

术语

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

推荐集群显示来自单个开发者合作伙伴的个性化健康与健身建议。这些推荐可以根据用户进行个性化设置，也可以是通用型（例如，热门健身与健康）。使用这些来展示与健康和健身相关的文章或人物。
- 推荐集群可以由 ArticleEntity、PersonEntity 或 EventEntity 组成，但不能是不同实体类型的混合。
您的推荐采用以下结构
- 推荐集群：一个 UI 视图，其中包含来自同一开发者合作伙伴的一组推荐。
- 实体：一个表示集群中单个项目的对象。此集成提供了一些将使用推荐集群展示的实体
  - ArticleEntity：ArticleEntity 表示与健康与健身相关的文本内容推荐。它可用于文章、博文、营销内容、新闻片段等。
    
    图 1：显示推荐集群中单个 ArticleEntity 的 UI。
  - PersonEntity：PersonEntity 表示一个人。推荐可以是突出教练或任何与健康和健身相关的人物等。
    
    图 2：显示推荐集群中单个 PersonEntity 的 UI。
  - EventEntity：EventEntity 表示未来发生的事件。事件开始时间是需要向用户传达的关键信息。此实体可用于展示与健康和健身相关的事件，例如献血营、培训课程、健身房或瑜伽课等。
    
    图 3：显示推荐集群中单个 EventEntity 的 UI。
连续集群在一个 UI 分组中显示来自多个开发者合作伙伴的用户最近互动过的内容。每个开发者合作伙伴都可以在连续集群中广播最多 10 个实体。

您的连续内容可以采用以下结构
- ArticleEntity：ArticleEntity 表示与健康与健身相关的文本内容推荐。此实体可用于表示未完成的新闻文章或用户希望从上次离开的地方继续消费的其他内容。例如：新闻片段、关于健康或健身相关主题的博文片段。
  
  图 6. 显示连续集群中单个 ArticleEntity 的 UI。
- EventReservationEntity：EventReservationEntity 表示事件预订，可帮助用户跟踪即将到来或正在进行的健身和健康事件预订。例如：训练课程
  
  图 8. 显示连续集群中单个 EventReservationEntity 的 UI。
精选集群在一个 UI 分组中展示来自多个开发者合作伙伴的一系列实体。将只有一个精选集群，它位于 UI 顶部附近，优先级高于所有推荐集群。每个开发者合作伙伴都可以在精选集群中广播最多 10 个实体。
- GenericFeaturedEntity：GenericFeaturedEntity 与推荐项不同，精选项应用于开发者提供的单个热门内容，并且应表示对用户来说最重要、最有趣和最相关的内容。
  
  图 12：显示精选集群中单个主打 GenericFeaturedEntity 卡片的 UI

前期准备

最低 API 级别：19

将 com.google.android.engage:engage-core 库添加到您的应用中

dependencies {
    // Make sure you also include that repository in your project's build.gradle file.
    implementation 'com.google.android.engage:engage-core:1.5.2'
}

摘要

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

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

集群类型	集群限制	集群中的最低实体限制	集群中的最大实体限制
推荐集群	最多 7 个	至少 1 个	最多 50 个（`ArticleEntity`、`PersonEntity` 或 `EventEntity`）
连续集群	最多 1 个	至少 1 个	最多 20 个（`ArticleEntity` 或 `EventReservationEntity`）
精选集群	最多 1 个	至少 1 个	最多 20 个（`GenericFeaturedEntity`）

第 1 步：提供实体数据

SDK 定义了不同的实体来表示每种项目类型。我们支持健康与健身类别的以下实体

GenericFeaturedEntity
ArticleEntity
PersonEntity
EventEntity
EventReservationEntity

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

`GenericFeaturedEntity`

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

`ArticleEntity`

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

`PersonEntity`

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

`EventEntity`

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

`EventReservationEntity`

属性	要求	说明	格式
操作 URI	必填	指向提供者应用中实体的深层链接。注意：您可以使用深层链接进行归因。请参阅此常见问题解答	Uri
标题	必填	实体的标题。	字符串建议文本大小：最多 50 个字符
事件预计开始时的 Unix 时间戳。	必填	注意：这将以毫秒为单位表示。事件模式	毫秒级 Unix 时间戳
一个字段，指示事件是虚拟的、面对面的还是两者兼而有之。	必填	枚举：VIRTUAL、IN_PERSON 或 HYBRID	事件发生的国家/地区。
个人所在或提供服务的国家/地区。	有条件必填	注意：这对于 IN_PERSON 或 HYBRID 的事件是必需的事件发生的城市。	自由文本位置 - 城市
个人所在或提供服务的城市。	有条件必填	应向用户显示的事件发生地点地址或场馆名称。事件发生的城市。	自由文本位置 - 城市
将向用户显示个人所在或提供服务的地址。	有条件必填	事件举办地点的街道地址（如果适用）。事件发生的城市。	自由文本位置 - 城市
个人所在或提供服务的街道地址（如果适用）。	可选	事件举办的州或省（如果适用）。	自由文本位置 - 城市
个人所在或提供服务的州/省（如果适用）。	可选	事件举办地点的邮政编码（如果适用）。	自由文本位置 - 城市
个人所在或提供服务的邮政编码（如果适用）。	可选	事件举办的街区（如果适用）。	自由文本位置 - 城市
个人所在或提供服务的街区（如果适用）。	可选	结束时间	自由文本位置 - 城市
海报图片	可选	提供多张图片时，我们只会显示 1 张。推荐宽高比为 16:9 注意：强烈建议使用图片。如果提供了徽章，请确保图片顶部和底部都有 24 dps 的安全空间	请参阅图片规格获取指导。
事件预计结束时的 Unix 时间戳。	可选	价格 - 当前价格事件模式	毫秒级 Unix 时间戳
服务提供商的名称。	可选	注意：服务提供商需要文本或图片。自由文本。例如，活动组织者/旅游的名称	服务提供商 - 图片
服务提供商的徽标/图片。	可选	预订 ID 自由文本。例如，活动组织者/旅游的名称	请参阅图片规格获取指导。
说明	可选	描述实体的单段文本。注意：将向用户显示描述或副标题列表，但不能同时显示。	自由文本建议文本大小：180 个字符
副标题列表	可选	最多 3 个副标题，每个副标题为一行文本。注意：将向用户显示描述或副标题列表，但不能同时显示。	自由文本每个副标题的建议文本大小：最多 50 个字符
徽章	可选	每个徽章可以是自由文本（最多 15 个字符）或小图片。
徽章 - 文本	可选	徽章标题注意：徽章需要文本或图片	自由文本建议文本大小：最多 15 个字符
徽章 - 图片	可选	小图片特殊用户体验处理，例如作为图片/视频缩略图上的徽章叠加层。注意：徽章需要文本或图片	请参阅图片规格获取指导。
事件预订的预订 ID。	可选	事件评分的计数。	自由文本
有条件必填	事件门票/通行证的当前价格。	如果提供了划线价格，则必须提供此项。价格 - 划线价格	自由文本
事件门票/通行证的原始价格。	可选	价格标注	自由文本
如果可用，可用于展示促销、活动、会员折扣的价格标注。	可选	建议文本大小：45 个字符以下（过长的文本可能会显示省略号）	自由文本 TYPE_MOVIES_AND_TV_SHOWS（例如 - 电影院）
评分 - 最大值	可选	评分尺度的最大值。如果也提供了评分的当前值，则必须提供此项。	数字 >= 0.0
评分 - 当前值	可选	评分尺度的当前值。如果也提供了评分的最大值，则必须提供此项。	数字 >= 0.0
评分 - 计数	可选	注意：如果您的应用希望控制此内容如何向用户显示，请提供此字段。请提供可向用户显示的简洁字符串。例如，如果计数为 1,000,000，请考虑使用 1M 这样的缩写，以免在较小的显示尺寸上被截断。注意：如果您不希望自行处理显示缩写逻辑，请提供此字段。如果计数和计数值都存在，我们将使用计数向用户显示	字符串
注意：如果您不自行处理显示缩写逻辑，请提供此字段。如果计数和计数值都存在，则向用户显示计数。	可选	注意：如果您的应用希望控制此内容如何向用户显示，请提供此字段。请提供可向用户显示的简洁字符串。例如，如果计数为 1,000,000，请考虑使用 1M 这样的缩写，以免在较小的显示尺寸上被截断。图片规格	长整型
内容类别	可选	描述实体中内容的类别。	TYPE_HEALTH_AND_FITENESS（例如 - 瑜伽/健身教练） TYPE_DIGITAL_GAMES（例如 - 电子竞技） TYPE_MUSIC（例如 - 音乐会） TYPE_TRAVEL_AND_LOCAL（例如 - 旅游、节日） TYPE_HEALTH_AND_FITENESS（例如 - 瑜伽课） TYPE_EDUCATION（例如 - 课程） TYPE_SPORTS（例如 - 足球比赛） TYPE_DATING（例如 - 聚会）服务提供商 - 名称请参阅内容类别部分获取指导。

图片素材的所需规格在此表中列出

宽高比

最小像素	推荐像素	正方形 (1x1)
首选 300x300	1200x1200	横向 (1.91x1)
600x314	1200x628	纵向 (4x5)
480x600	960x1200	图片需要托管在公共 CDN 上，以便 Google 可以访问它们。

最小像素

推荐像素

正方形 (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
内容类别使用指南
开始时间

文件格式

某些实体（例如 ArticleEntity 和 GenericFeaturedEntity）有资格使用任何内容类别。对于其他实体（例如 EventEntity、EventReservationEntity、PersonEntity），只有这些类别的一个子集有资格。在填充列表之前，请检查实体类型符合条件的类别列表。

对于某些内容类别，请使用特定的实体类型，而不是通用实体和内容类别的组合
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
此 API 用于检查服务是否可用于集成，以及内容是否可以在设备上显示。

`publishRecommendationClusters`

Kotlin

Java

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.
    }
}

注意：我们强烈建议保持一个周期性作业运行，以检查服务是否在稍后时间可用。服务的可用性可能会随着 Android 版本升级、应用升级、安装和卸载而改变。通过确保在特定时间间隔内进行周期性作业检查，一旦服务可用，即可发布数据。

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.
    }
});

此 API 用于发布 RecommendationCluster 对象列表。

`publishFeaturedCluster`

重要提示： 发布 API 是 upsert API；它会替换现有内容。请勿后续调用删除和发布 API 来替换内容，因为发布 API 本身就具有此功能。

Java

client.publishRecommendationClusters(
      PublishRecommendationClustersRequest.Builder()
        .addRecommendationCluster(
          RecommendationCluster.Builder()
            .addEntity(entity1)
            .addEntity(entity2)
            .setTitle("Top Picks For You")
            .build()
        )
        .build()
    )

注意：我们强烈建议保持一个周期性作业运行，以检查服务是否在稍后时间可用。服务的可用性可能会随着 Android 版本升级、应用升级、安装和卸载而改变。通过确保在特定时间间隔内进行周期性作业检查，一旦服务可用，即可发布数据。

client.publishRecommendationClusters(
            new PublishRecommendationClustersRequest.Builder()
                .addRecommendationCluster(
                    new RecommendationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .setTitle("Top Picks For You")
                        .build())
                .build());

现有的 RecommendationCluster 开发者合作伙伴数据将被删除。

请求中的数据将被解析并存储在更新的推荐集群中。
如果发生错误，整个请求将被拒绝，并保持现有状态。

此 API 用于发布 FeaturedCluster 对象列表。

`publishContinuationCluster`

现有的 FeaturedCluster 开发者合作伙伴数据将被删除。

Java

client.publishFeaturedCluster(
    PublishFeaturedClusterRequest.Builder()
      .setFeaturedCluster(
        FeaturedCluster.Builder()
          .addEntity(entity1)
          .addEntity(entity2)
          .build())
      .build())

注意：我们强烈建议保持一个周期性作业运行，以检查服务是否在稍后时间可用。服务的可用性可能会随着 Android 版本升级、应用升级、安装和卸载而改变。通过确保在特定时间间隔内进行周期性作业检查，一旦服务可用，即可发布数据。

client.publishFeaturedCluster(
            new PublishFeaturedClustersRequest.Builder()
                .addFeaturedCluster(
                    new FeaturedCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .build())
                .build());

现有的 RecommendationCluster 开发者合作伙伴数据将被删除。

请求中的数据将被解析并存储在更新的精选集群中。
此 API 用于发布 ContinuationCluster 对象。

此 API 用于发布 FeaturedCluster 对象列表。

`publishUserAccountManagementRequest`

现有的 ContinuationCluster 开发者合作伙伴数据将被删除。

Java

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

注意：我们强烈建议保持一个周期性作业运行，以检查服务是否在稍后时间可用。服务的可用性可能会随着 Android 版本升级、应用升级、安装和卸载而改变。通过确保在特定时间间隔内进行周期性作业检查，一旦服务可用，即可发布数据。

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

现有的 RecommendationCluster 开发者合作伙伴数据将被删除。

请求中的数据将被解析并存储在更新的连续集群中。
此 API 用于发布登录卡。登录操作会将用户引导至应用的登录页面，以便应用可以发布内容（或提供更个性化的内容）

此 API 用于发布 FeaturedCluster 对象列表。

`updatePublishStatus`

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

操作的深层链接（即导航到应用登录页面）

属性	要求	说明
操作 URI	必填	图片
可选 - 如果未提供，则必须提供标题	卡片上显示的图片	16:9 宽高比图片，分辨率为 1264x712 可选 - 如果未提供，则必须提供图片
标题	卡片标题	操作文本
CTA 上显示的文本（即登录）	可选	副标题
卡片上的可选副标题	可选	现有的 `UserAccountManagementCluster` 开发者合作伙伴数据将被删除。

Java

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

注意：我们强烈建议保持一个周期性作业运行，以检查服务是否在稍后时间可用。服务的可用性可能会随着 Android 版本升级、应用升级、安装和卸载而改变。通过确保在特定时间间隔内进行周期性作业检查，一旦服务可用，即可发布数据。

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

现有的 RecommendationCluster 开发者合作伙伴数据将被删除。

请求中的数据将被解析并存储在更新的 UserAccountManagementCluster 集群中。
如果由于任何内部业务原因，没有任何集群被发布，我们强烈建议使用 updatePublishStatus API 更新发布状态。这很重要，因为

此 API 用于发布 FeaturedCluster 对象列表。

`deleteRecommendationsClusters`

在所有情况下提供状态，即使内容已发布（STATUS == PUBLISHED），对于填充使用此显式状态来传达您的集成健康状况和其他指标的仪表板至关重要。

如果没有内容发布但集成状态未损坏（STATUS == NOT_PUBLISHED），Google 可以避免在应用健康仪表板中触发警报。这证实了内容未发布是由于提供者角度的预期情况。
这有助于开发者了解数据何时发布，何时未发布。
Google 可能会使用状态代码来提示用户在应用中执行某些操作，以便他们可以看到应用内容或解决问题。
符合条件的发布状态代码列表为

如果内容由于用户未登录而未发布，Google 将建议发布登录卡。如果提供商因任何原因无法发布登录卡，那么我们建议使用状态代码 NOT_PUBLISHED_REQUIRES_SIGN_IN 调用 updatePublishStatus API

// 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

deleteRecommendationClusters

Java

client.updatePublishStatus(
   PublishStatusRequest.Builder()
     .setStatusCode(AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SIGN_IN)
     .build())

注意：我们强烈建议保持一个周期性作业运行，以检查服务是否在稍后时间可用。服务的可用性可能会随着 Android 版本升级、应用升级、安装和卸载而改变。通过确保在特定时间间隔内进行周期性作业检查，一旦服务可用，即可发布数据。

client.updatePublishStatus(
    new PublishStatusRequest.Builder()
        .setStatusCode(AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SIGN_IN)
        .build());

`此 API 用于删除推荐集群的内容。`

重要提示： 只有在没有内容可发布时才应调用删除 API。请勿后续调用删除和发布 API 来替换内容，因为发布 API 本身就具有此功能。在使用删除 API 之前，请联系 engage-developers@。

Java

client.deleteRecommendationClusters()

注意：我们强烈建议保持一个周期性作业运行，以检查服务是否在稍后时间可用。服务的可用性可能会随着 Android 版本升级、应用升级、安装和卸载而改变。通过确保在特定时间间隔内进行周期性作业检查，一旦服务可用，即可发布数据。

client.deleteRecommendationClusters();

注意： 此 API 从版本 1.1.0 开始可用。

`deleteContinuationCluster`

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

Java

client.deleteFeaturedCluster()

注意：我们强烈建议保持一个周期性作业运行，以检查服务是否在稍后时间可用。服务的可用性可能会随着 Android 版本升级、应用升级、安装和卸载而改变。通过确保在特定时间间隔内进行周期性作业检查，一旦服务可用，即可发布数据。

client.deleteFeaturedCluster();

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

`deleteUserManagementCluster`

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

Java

client.deleteContinuationCluster()

注意：我们强烈建议保持一个周期性作业运行，以检查服务是否在稍后时间可用。服务的可用性可能会随着 Android 版本升级、应用升级、安装和卸载而改变。通过确保在特定时间间隔内进行周期性作业检查，一旦服务可用，即可发布数据。

client.deleteContinuationCluster();

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

`deleteClusters`

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

Java

client.deleteUserManagementCluster()

注意：我们强烈建议保持一个周期性作业运行，以检查服务是否在稍后时间可用。服务的可用性可能会随着 Android 版本升级、应用升级、安装和卸载而改变。通过确保在特定时间间隔内进行周期性作业检查，一旦服务可用，即可发布数据。

client.deleteUserManagementCluster();

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

`此 API 用于检查服务是否可用于集成，以及内容是否可以在设备上显示。`

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

Java

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

注意：我们强烈建议保持一个周期性作业运行，以检查服务是否在稍后时间可用。服务的可用性可能会随着 Android 版本升级、应用升级、安装和卸载而改变。通过确保在特定时间间隔内进行周期性作业检查，一旦服务可用，即可发布数据。

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

错误处理

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

错误将作为 AppEngageException 返回，并包含错误代码作为原因。

Java

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
            }
          }
        }
      }

注意：我们强烈建议保持一个周期性作业运行，以检查服务是否在稍后时间可用。服务的可用性可能会随着 Android 版本升级、应用升级、安装和卸载而改变。通过确保在特定时间间隔内进行周期性作业检查，一旦服务可用，即可发布数据。

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

错误代码

错误名称	注意	SERVICE_NOT_FOUND
`1`	`服务在给定设备上不可用。`	SERVICE_NOT_AVAILABLE
`2`	`服务在给定设备上可用，但在调用时不可用（例如，它已被明确禁用）。`	SERVICE_CALL_EXECUTION_FAILURE
`3`	`任务执行因线程问题失败。在这种情况下，可以重试。`	SERVICE_CALL_PERMISSION_DENIED
`4`	`调用者不允许进行服务调用。`	SERVICE_CALL_INVALID_ARGUMENT
`5`	`请求包含无效数据（例如，超过允许的集群数量）。`	SERVICE_CALL_INTERNAL
`6`	`服务端出现错误。`	SERVICE_CALL_RESOURCE_EXHAUSTED
`7`	`服务调用过于频繁。`	第 3 步：处理广播 Intent

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

广播 Intent 的目标主要是应用重新激活和强制数据同步。广播 Intent 的设计目的不是频繁发送。它仅在 Engage 服务确定内容可能已过时（例如，一周前的内容）时触发。这样，即使应用程序长时间未执行，也能更有信心让用户获得新鲜的内容体验。

BroadcastReceiver 必须按以下两种方式设置

使用 Context.registerReceiver() 动态注册 BroadcastReceiver 类实例。这使得内存中仍在运行的应用能够进行通信。

在您的 AndroidManifest.xml 文件中使用 <receiver> 标记静态声明实现。这使得应用程序在未运行时也能接收广播 Intent，并允许应用程序发布内容。

Java

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))
}

注意：我们强烈建议保持一个周期性作业运行，以检查服务是否在稍后时间可用。服务的可用性可能会随着 Android 版本升级、应用升级、安装和卸载而改变。通过确保在特定时间间隔内进行周期性作业检查，一旦服务可用，即可发布数据。

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

}

服务发送以下 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>

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 商店后，您的推荐、精选和连续集群可能会发布并对用户可见。
此页面上的内容和代码示例受内容许可中所述的许可条款约束。Java 和 OpenJDK 是 Oracle 和/或其附属公司的商标或注册商标。

Engage SDK 健康与健身：第三方技术集成说明 利用收藏集保持井井有条 根据您的偏好保存和分类内容。

集成详情

术语

前期准备

摘要

第 1 步：提供实体数据

GenericFeaturedEntity

ArticleEntity

PersonEntity

EventEntity

EventReservationEntity

图片素材的所需规格在此表中列出

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

建议在后台执行内容发布作业（例如，使用 WorkManager）并定期或按事件调度（例如，用户每次打开应用或将某些内容添加到购物车时）。

publishRecommendationClusters

Java

publishFeaturedCluster

Java

publishContinuationCluster

Java

publishUserAccountManagementRequest

Java

updatePublishStatus

Java

deleteRecommendationsClusters

Java

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

Java

deleteContinuationCluster

Java

deleteUserManagementCluster

Java

deleteClusters

Java

此 API 用于检查服务是否可用于集成，以及内容是否可以在设备上显示。

Java

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

Java

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

Java

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

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

如果在集成过程中有任何问题，请联系 engage-developers@google.com。

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

Engage SDK 健康与健身：第三方技术集成说明

`GenericFeaturedEntity`

`ArticleEntity`

`PersonEntity`

`EventEntity`

`EventReservationEntity`

`publishRecommendationClusters`

`publishFeaturedCluster`

`publishContinuationCluster`

`publishUserAccountManagementRequest`

`updatePublishStatus`

`deleteRecommendationsClusters`

`此 API 用于删除推荐集群的内容。`

`deleteContinuationCluster`

`deleteUserManagementCluster`

`deleteClusters`

`此 API 用于检查服务是否可用于集成，以及内容是否可以在设备上显示。`

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