在 Android 应用中集成 Play Engage…

当需要为 Android 应用（含 TV）接入 Google Play Engage SDK、生成发布样板代码、把本地数据模型映射为 Engage 实体或修复 SDK 相关错误时使用。

适用场景

解决思路

1. 确定垂直行业与 cluster：先问开发者应用属于哪个垂直行业（参考 references/schemas/ 目录），并确认是 TV 还是移动端集成；若是 TV，还要阅读 references/patterns.md 中的 TV 专属章节。
2. 用 references/schemas/ 目录下的 {VERTICAL}.md 找出对应的 Engage 实体和 client 类名（JSON 中的 client 字段给出完整类名，例如 com.google.android.engage.food.service.AppEngageFoodClient）；注意初始化 client 类需要 Context 参数，例如 AppEngageFoodClient(context)。
3. 始终参考 references/common.md 获取通用实体；再让开发者从该垂直行业支持的 cluster 类型中选择要发布的 cluster。
4. 在 references/schemas/ 的 {VERTICAL}.md 中找到该 cluster 对应的方法（每个方法会说明它期望的 request），从 references/requests.md 获取 request 结构、从 references/clusters.md 获取 cluster，然后建议并选用合适的数据源正确填充 request 字段及所需实体和 cluster。
5. 生成结构化样板代码：新建一个目录存放所有 Engage 相关代码，目录命名遵循现有代码库的命名约定。
6. 按 references/patterns.md 中的模板生成以下类：Constants（保存尝试次数、发布类型等常量）、ItemToEntityConverter（把应用本地模型转换为 Engage Entity 模型）、ClusterRequestFactory（构造发布请求）、EngageWorker（用 WorkManager 处理实际发布及发布错误）、EngagePublisher（编排周期性和一次性任务）、EngageBroadcastReceiver（监听 AppEngageService intent 并从 EngagePublisher 启动一次性发布任务）；重要：必须同时实现静态注册和动态注册两种模式，包括在 EngageBroadcastReceiver 类内部的 companion object 中实现 register 方法。
7. 建议实体映射：让开发者提供其本地模型 schema（例如 data class 或 JSON 片段）；若未提供，则用 references/schemas/ 中 {VERTICAL}.md 的实体作为参考。
8. 确定本地模型后，建议其到对应 Engage 实体的映射，并按 references/patterns.md 中的 ItemToEntityConverter 模式生成转换逻辑，加入生成的 {ENGAGE_CODE_DIR}/ItemToEntityConverter。
9. 建议数据源：让开发者提供实际要发布的数据来源；确定数据源后，用它按应用本地模型 schema 获取数据。
10. 用 {ENGAGE_CODE_DIR}/ItemToEntityConverter 把数据转换为 Engage 实体，再用得到的 Engage 实体模型数据配合 {ENGAGE_CODE_DIR}/ClusterRequestFactory 生成 cluster 请求。
11. 在 {ENGAGE_CODE_DIR}/EngageWorker 中，用上一步得到的 request 调用从 references/schemas/ 的 {VERTICAL}.md 获取的对应 cluster 发布方法。
12. 更新 Gradle 与 manifest：建议修改 build.gradle 和 AndroidManifest.xml；移动端应用参考 references/patterns.md，TV 应用参考其中的 TV 专属章节。
13. 从 references/patterns.md 提供 build.gradle 或 build.gradle.kts 所需的 implementation 依赖，并提供 AndroidManifest.xml 的 <receiver> 和 <service> 声明；注意除 TV 外没有垂直行业专属 import，其他所有垂直行业使用 com.google.android.engage:engage-core:1.6.0 即可。
14. 完成前执行自检清单：在 AndroidManifest.xml 的 <application> 标签内静态注册 EngageBroadcastReceiver；在 Application 类或主 Activity 类中调用 EngageBroadcastReceiver.register(context) 动态注册；在 EngageBroadcastReceiver 的 companion object 中实现 register 方法以支持动态注册；在 EngageWorker 中处理空数据列表（例如删除 cluster 而不是发布空数据）；所有 Gradle 编译都使用 --no-daemon。
15. 执行 Gradle sync；若出现错误（如 import 失败、命名空间冲突或编译错误），阅读 references/troubleshooting.md 解决。
16. 执行 Gradle 编译：必须运行 ./gradlew compileDebugUnitTestSources --no-daemon 或 ./gradlew assembleDebug --no-daemon（编译规则和快速编译捷径的警告见 references/troubleshooting.md），重复此步骤直到编译成功。
17. 代码生成结束后通知用户核对清单：确认 {ENGAGE_CODE_DIR}/ 下已创建所有 Engage 相关文件（Constants、ItemToEntityConverter、ClusterRequestFactory、EngageWorker、{cluster_type}Publisher、EngageBroadcastReceiver）；确认 ItemToEntityConverter 中正确填充字段、把应用本地模型转换为 Engage 实体；确认 ItemToEntityConverter 中所有图片 URI 指向符合该垂直行业严格宽高比要求（如 16:9、1:1、2:3）的图片；确认 EngageWorker 使用第 4 步确定的数据源；确认在 Application 类或 MainActivity 中调用了 EngageBroadcastReceiver.register(context) 以动态注册；确认 AndroidManifest.xml 中包含 EngageBroadcastReceiver 的静态 <receiver> 声明及必要的 intent action。
18. 重要：明确指示开发者在自定义 Application 类的 onCreate()（或主 Activity 的 onCreate()）中调用 EngageBroadcastReceiver.register(context) 动态注册接收器，并强调静态和动态注册两者都是集成正常工作的必要条件。
19. 遇到常见问题时查阅 references/android/guide/playcore/engage/faq.md；按垂直行业查阅对应指南（food、watch、listen、read、shopping、social、travel、healthandfitness、otherverticals 及 TV 的 getting-started、recommendations、continue-watching、entitlements）和对应 schema（food、watch、listen、read、shopping、social、travel、tv、other）。

适用边界 · 注意事项

• 不适用于非 Android 平台或非 Google Play Engage SDK 的集成场景。
• 不适用于未接入 Google Play 服务、无法使用 com.google.android.engage 依赖的应用。
• TV 集成不能照搬移动端模式，必须使用 references/patterns.md 中的 TV 专属章节。