engage-sdk-integration

本技能将指导你把 Play Engage SDK 集成到 Android 应用中，确保代码遵循强制结构，并为每个垂直领域使用必需的 Engage 实体。

工作流

按照以下步骤协助开发者：

1. 识别垂直领域和集群：

   • 根据 references/schemas/ 询问开发者其应用属于哪个垂直领域。
   • 检查集成面向 TV 还是移动设备。如果集成面向 TV，也要阅读 patterns.md 中针对 TV 的部分。
   • 使用 references/schemas/ 目录中的 {VERTICAL}.md，确定相应的 Engage 实体和 client 类名。JSON 中的 client 字段提供完整类名。例如：com.google.android.engage.food.service.AppEngageFoodClient。
   • 注意： 初始化客户端类需要传入 Context 参数。例如：AppEngageFoodClient(context)。
   • 务必参考 common.md 了解通用实体。
   • 询问开发者希望从该垂直领域支持的集群类型中发布哪种集群。
   • 在 references/schemas/ 目录中的 {VERTICAL}.md 里查找指定集群对应的调用方法。每种方法都会说明其所需的请求。
   • 从 requests.md 获取请求结构，并从 clusters.md 获取集群。然后建议并使用数据源，正确填充请求结构中的字段以及所需的实体和集群。

2. 生成结构化样板代码：

   • 为所有 Engage 相关代码新建一个目录。目录名称应符合现有代码库的命名约定。
   • 使用 patterns.md 中的模板生成以下类：
     • Constants：存放尝试次数和发布类型等常量值。
     • ItemToEntityConverter：将应用的本地模型转换为 Engage 的 Entity 模型。
     • ClusterRequestFactory：构建发布请求。
     • EngageWorker：使用 WorkManager 处理实际发布和发布错误。
     • EngagePublisher：编排定期任务和一次性任务。
     • EngageBroadcastReceiver：监听 AppEngageService intents，并通过 EngagePublisher 启动一次性发布任务。重要：同时实现静态注册和动态注册模式，包括在 EngageBroadcastReceiver 类内部实现伴生对象 register 方法。

3. 建议实体映射：

   • 请开发者提供其本地模型架构（例如，数据类或 JSON 片段）。
   • 如果开发者尚未提供，请分享 references/schemas/ 目录中 {VERTICAL}.md 里的实体作为参考。
   • 确定本地模型后，建议其与相应 Engage 实体之间的映射。
   • 使用 patterns.md 中的 ItemToEntityConverter 模式生成转换逻辑，并将其添加到生成的 {ENGAGE_CODE_DIR}/ItemToEntityConverter 中。

4. 建议数据源：

   • 请开发者提供实际要发布的数据源。
   • 确定数据源后，使用它按应用的本地模型架构获取数据。
   • 使用 {ENGAGE_CODE_DIR}/ItemToEntityConverter 将这些数据转换为 Engage 实体。
   • 使用获取到的 Engage 实体模型数据，通过 {ENGAGE_CODE_DIR}/ ClusterRequestFactory 获取集群请求。
   • 在 {ENGAGE_CODE_DIR}/EngageWorker 中，使用上一步获取的请求，调用 references/schemas/ 目录中 {VERTICAL}.md 对应的集群发布方法。

5. Gradle 和清单文件更新：

   • 提议更新 build.gradle 和 AndroidManifest.xml。
   • 对于移动应用，请使用 patterns.md。
   • 对于 TV 应用，请使用 patterns.md 中针对 TV 的章节。
   • 根据 patterns.md，提供 build.gradle 或 build.gradle.kts 所需的 implementation 依赖项。
   • 提供 AndroidManifest.xml 的 <receiver> 和 <service> 声明。
   • 注意：除 TV 外，其他垂直领域都没有专用导入。对于所有其他垂直领域，com.google.android.engage:engage-core:1.6.0 即可满足需求。

6. 调试和验证：

   • 自我验证清单：在确认工作完成之前，必须验证已实现以下所有内容：
     • [ ] 在 AndroidManifest.xml 中（<application> 标签内）静态注册了 EngageBroadcastReceiver。
     • [ ] 在 Application 类或主 Activity 类中，通过调用 EngageBroadcastReceiver.register(context) 动态注册了 EngageBroadcastReceiver。
     • [ ] 在 EngageBroadcastReceiver 的 companion object 中实现了 register 方法，以处理动态注册。
     • [ ] 在 EngageWorker 中处理了空数据列表（例如，删除集群，而不是发布空数据）。
     • [ ] 所有 Gradle 编译都使用了 --no-daemon。
   • 执行 Gradle 同步。
   • 如果发生错误（例如导入失败、命名空间冲突或编译错误），请阅读 references/troubleshooting.md 并解决问题。
   • 执行 Gradle 编译。必须运行 ./gradlew compileDebugUnitTestSources --no-daemon 或 ./gradlew assembleDebug --no-daemon。有关编译规则以及快速编译捷径的警告，请参阅 references/troubleshooting.md。重复此步骤，直到编译成功。

7. **用户检查清单：**代码生成结束时，告知用户按以下清单检查集成是否完整且符合预期：

   • [ ] 确认在 {ENGAGE_CODE_DIR}/ 中创建了所有与 Engage 相关的文件：
     • Constants
     • ItemToEntityConverter
     • ClusterRequestFactory
     • EngageWorker
     • {cluster_type}Publisher
     • EngageBroadcastReceiver
   • [ ] 确认应用的本地模型已通过在 {ENGAGE_CODE_DIR}/ItemToEntityConverter 中正确填充模型字段，转换为 Engage 实体。
   • [ ] 确认 ItemToEntityConverter 中的所有图像 URI 均指向符合该垂直领域严格宽高比要求的图像（例如，16:9、1:1、2:3）。
   • [ ] 确认 {ENGAGE_CODE_DIR}/EngageWorker 使用了第 4 步中确定的数据源。
   • [ ] 确认在 Application 类或 MainActivity 中调用了 EngageBroadcastReceiver.register(context)，以动态注册接收器。
   • [ ] 确认 AndroidManifest.xml 包含 EngageBroadcastReceiver 的静态 <receiver> 声明，并带有必要的 intent 操作。
   • 重要：明确指示开发者在自定义 Application 类的 onCreate() 中（或主 Activity 的 onCreate() 中）调用 EngageBroadcastReceiver.register(context)，以动态注册接收器。强调集成正常运行需要同时进行静态和动态注册。

参考资料

• 常见问题： Engage 常见问题 - 请参阅本文档，了解开发者常见问题的 解答。

• 垂直领域指南：

  • 美食垂直领域
  • 观看垂直领域
  • 收听垂直领域
  • 阅读垂直领域
  • 购物垂直领域
  • 社交垂直领域
  • 旅行垂直领域
  • 健康与健身垂直领域
  • 其他垂直领域
  • TV 入门指南
  • TV 推荐
  • TV 继续观看
  • TV 权益

• 垂直领域架构：

  • 美食架构
  • 观看架构
  • 收听架构
  • 阅读架构
  • 购物架构
  • 社交架构
  • 旅行架构
  • TV 架构
  • 其他架构