engage-sdk-integration

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

This skill guides you through integrating the Play Engage SDK into an Android app. It ensures that the code follows the mandatory structure and uses the required Engage entities for each vertical.

本Skill将引导您完成Play Engage SDK到Android应用的集成过程。确保代码遵循强制结构，并针对每个垂直领域使用所需的Engage实体。

Workflow

工作流程

Follow these steps to assist the developer:

Identify Vertical and Cluster:
- Ask the developer which vertical their app belongs to based on references/schemas/.
- Check if the integration is for TV or Mobile. Read the TV-specific sections in patterns.md as well if the integration is for TV.
- Use
```
{VERTICAL}.md
```
  in the references/schemas/ directory to identify the corresponding Engage entities and the
```
client
```
  class name. The
```
client
```
  field in the JSON provides the full class name. (e.g.,
```
com.google.android.engage.food.service.AppEngageFoodClient
```
  ).
- Note: Initializing the client class requires a
```
Context
```
  parameter (e.g.,
```
AppEngageFoodClient(context)
```
  ).
- Always refer to common.md for common entities.
- Ask which cluster type they want to publish from the supported cluster types for that vertical.
- Find the method to call from
```
{VERTICAL}.md
```
  in the references/schemas/ directory for the specified cluster. Each method will specify the request it expects.
- Get the request structure from requests.md and clusters from clusters.md. Then suggest and use sources to fill the fields in the request structure correctly, along with the required entities and clusters.
Generate Structured Boilerplate Code:
- Create a new directory for all Engage-related code. Name the directory to match the naming convention of the existing codebase.
- Generate the following classes using templates in patterns.md:
  - ```
  Constants
```
  : Holds constant values like attempt counts, publish types.
- ```
ItemToEntityConverter
```
    : Converts app's local models to Engage's Entity models.
  - ```
  ClusterRequestFactory
```
  : Constructs the publish requests.
- ```
EngageWorker
```
    : Handles the actual publishing and publish errors using WorkManager.
  - ```
  EngagePublisher
```
  : Orchestrates periodic and one-time jobs.
- ```
EngageBroadcastReceiver
```
    : Listens for AppEngageService intents and starts a one-time publish job from
```
EngagePublisher
```
    . Important : Implement both static registration and dynamic registration patterns, including the companion object
```
register
```
    method inside the
```
EngageBroadcastReceiver
```
    class.
Suggest Entity Mapping:
- Ask the developer to provide their local model schema(e.g., a data class or a JSON snippet).
- If they haven't provided one, share entities from
```
{VERTICAL}.md
```
  in the references/schemas/ directory as a guide.
- Once the local model is identified, suggest a mapping to the corresponding Engage entity.
- Generate the conversion logic using the
```
ItemToEntityConverter
```
  pattern in patterns.md and add it to the generated
```
{ENGAGE_CODE_DIR}/ItemToEntityConverter
```
Suggest Data Source:
- Ask the developer to provide the source of actual data you'll publish.
- Once the source of data is identified, use the source of data to fetch data in app's local model schema.
- Use
```
{ENGAGE_CODE_DIR}/ItemToEntityConverter
```
  to convert this data to Engage entity.
- Use obtained Engage entity model data with
```
{ENGAGE_CODE_DIR}/ ClusterRequestFactory
```
  to get cluster requests.
- Call corresponding cluster publishing method obtained from
```
{VERTICAL}.md
```
  in the references/schemas/ directory with the obtained request in previous step in
```
{ENGAGE_CODE_DIR}/EngageWorker
```
  .
Gradle and Manifest Updates:
- Suggest updates to
```
build.gradle
```
  and
```
AndroidManifest.xml
```
  .
- For mobile apps, use patterns.md.
- For TV apps, use the TV-specific sections in patterns.md.
- Provide the necessary
```
implementation
```
  dependencies for
```
build.gradle
```
  or
```
build.gradle.kts
```
  from patterns.md.
- Provide the
```
<receiver>
```
  and
```
<service>
```
  declarations for
```
AndroidManifest.xml
```
  .
- Note: There's no separate import according to vertical except TV. For each vertical other than TV 'com.google.android.engage:engage-core:1.5.12' is enough.
Debugging:
- Perform a Gradle sync.
- If errors occur, follow this resolution order:
  - Fix import errors. For package
```
com.google.android.engage
```
    or classes starting with
```
AppEngage
```
    , verify the package name in the
```
{VERTICAL}.md
```
    in references/schemas/ directory or common.md.
  - Fix any other errors.
- Execute a full Gradle build and resolve any remaining compilation issues. Repeat this step until the Gradle build is successful.
User Checklist: At the end of code generation, notify the user to go through this checklist to verify that the integration is complete and as intended: [ ] Verify that all the engage related files are created in
```
{ENGAGE_CODE_DIR}/
```
:
- ```
Constants
```
- ```
ItemToEntityConverter
```
- ```
ClusterRequestFactory
```
- ```
EngageWorker
```
- ```
{cluster_type}Publisher
```
- ```
EngageBroadcastReceiver
```
  [ ] Verify that app's local model is converted to Engage entity by populating the fields correctly in the model in
```
{ENGAGE_CODE_DIR}/ ItemToEntityConverter
```
  . [ ] Verify that
```
{ENGAGE_CODE_DIR}/EngageWorker
```
  uses the data source identified in Step 4. [ ] Verify that
```
EngageBroadcastReceiver.register(context)
```
  is called within the
```
Application
```
  class or
```
MainActivity
```
  to register the receiver dynamically. [ ] Verify that
```
AndroidManifest.xml
```
  contains the static
```
<receiver>
```
  declaration for
```
EngageBroadcastReceiver
```
  with the necessary intent actions.
- Important : Explicitly instruct the developer to call
```
EngageBroadcastReceiver.register(context)
```
  inside their custom
```
Application
```
  class
```
onCreate()
```
  (or their main activity
```
onCreate()
```
  ) to dynamically register the receiver. Stress that both static and dynamic registrations are required for the integration to function.

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

确定垂直领域和集群：
- 根据**references/schemas/**询问开发者其应用所属的垂直领域。
- 确认集成是针对TV还是移动设备。如果是TV集成，还需阅读patterns.md中的TV专属章节。
- 使用**references/schemas/**目录下的
```
{VERTICAL}.md
```
  文件确定对应的Engage实体和
```
client
```
  类名。JSON中的
```
client
```
  字段提供完整类名（例如：
```
com.google.android.engage.food.service.AppEngageFoodClient
```
  ）。
- **注意：**初始化client类需要
```
Context
```
  参数（例如：
```
AppEngageFoodClient(context)
```
  ）。
- 始终参考common.md获取通用实体。
- 询问开发者该垂直领域支持的集群类型中，他们想要发布哪种集群类型。
- 从**references/schemas/**目录下的
```
{VERTICAL}.md
```
  文件中找到对应集群的调用方法。每个方法都会指定其预期的请求。
- 从requests.md获取请求结构，从clusters.md获取集群信息。然后建议并使用数据源正确填充请求结构中的字段，同时搭配所需的实体和集群。
生成结构化样板代码：
- 为所有Engage相关代码创建新目录，目录名称需匹配现有代码库的命名规范。
- 使用patterns.md中的模板生成以下类：
  - ```
  Constants
```
  ：存储尝试次数、发布类型等常量值。
- ```
ItemToEntityConverter
```
    ：将应用本地模型转换为Engage的实体模型。
  - ```
  ClusterRequestFactory
```
  ：构造发布请求。
- ```
EngageWorker
```
    ：使用WorkManager处理实际发布操作和发布错误。
  - ```
  EngagePublisher
```
  ：编排周期性和一次性任务。
- ```
EngageBroadcastReceiver
```
    ：监听AppEngageService意图，并从
```
EngagePublisher
```
    启动一次性发布任务。重要提示：实现静态注册和动态注册两种模式，包括
```
EngageBroadcastReceiver
```
    类中的伴生对象
```
register
```
    方法。
建议实体映射方案：
- 请开发者提供其本地模型架构（例如数据类或JSON片段）。
- 如果开发者未提供，可分享**references/schemas/**目录下
```
{VERTICAL}.md
```
  中的实体作为参考。
- 确定本地模型后，建议对应的Engage实体映射方案。
- 使用patterns.md中的
```
ItemToEntityConverter
```
  模式生成转换逻辑，并添加到生成的
```
{ENGAGE_CODE_DIR}/ItemToEntityConverter
```
  中。
建议数据源：
- 请开发者提供要发布的实际数据源。
- 确定数据源后，使用该数据源获取应用本地模型架构的数据。
- 使用
```
{ENGAGE_CODE_DIR}/ItemToEntityConverter
```
  将这些数据转换为Engage实体。
- 将获取到的Engage实体模型数据与
```
{ENGAGE_CODE_DIR}/ClusterRequestFactory
```
  结合，生成集群请求。
- 在
```
{ENGAGE_CODE_DIR}/EngageWorker
```
  中，调用从**references/schemas/**目录下
```
{VERTICAL}.md
```
  获取的对应集群发布方法，并传入上一步得到的请求。
Gradle和Manifest更新：
- 建议更新
```
build.gradle
```
  和
```
AndroidManifest.xml
```
  。
- 移动应用参考patterns.md。
- TV应用参考patterns.md中的TV专属章节。
- 从patterns.md提供
```
build.gradle
```
  或
```
build.gradle.kts
```
  所需的
```
implementation
```
  依赖。
- 提供
```
AndroidManifest.xml
```
  所需的
```
<receiver>
```
  和
```
<service>
```
  声明。
- 注意：除TV外，其他垂直领域无需单独导入依赖。非TV领域仅需
```
com.google.android.engage:engage-core:1.5.12
```
  即可。
调试：
- 执行Gradle同步。
- 若出现错误，按以下顺序解决：
  - 修复导入错误。对于
```
com.google.android.engage
```
    包或以
```
AppEngage
```
    开头的类，验证**references/schemas/**目录下
```
{VERTICAL}.md
```
    或common.md中的包名。
  - 修复其他错误。
- 执行完整的Gradle构建并解决所有剩余编译问题。重复此步骤直到Gradle构建成功。
用户检查清单： 代码生成完成后，通知用户完成以下检查清单，验证集成是否完整且符合预期： [ ] 确认所有Engage相关文件已创建在
```
{ENGAGE_CODE_DIR}/
```
目录下：
- ```
Constants
```
- ```
ItemToEntityConverter
```
- ```
ClusterRequestFactory
```
- ```
EngageWorker
```
- ```
{cluster_type}Publisher
```
- ```
EngageBroadcastReceiver
```
  [ ] 确认应用本地模型已通过在
```
{ENGAGE_CODE_DIR}/ItemToEntityConverter
```
  中正确填充字段转换为Engage实体。 [ ] 确认
```
{ENGAGE_CODE_DIR}/EngageWorker
```
  使用了步骤4中确定的数据源。 [ ] 确认已在
```
Application
```
  类或
```
MainActivity
```
  中调用
```
EngageBroadcastReceiver.register(context)
```
  以动态注册接收器。 [ ] 确认
```
AndroidManifest.xml
```
  包含
```
EngageBroadcastReceiver
```
  的静态
```
<receiver>
```
  声明，并带有必要的意图动作。
- 重要提示：明确指示开发者在自定义
```
Application
```
  类的
```
onCreate()
```
  方法（或主Activity的
```
onCreate()
```
  方法）中调用
```
EngageBroadcastReceiver.register(context)
```
  来动态注册接收器。强调静态和动态注册两者都是必需的，这样集成才能正常运行。

Reference Materials

参考资料

FAQ: Engage FAQ - Refer to this document for answers to frequently asked questions from developers.
Vertical-Specific Guides:
- Food Vertical
- Watch Vertical
- Listen Vertical
- Read Vertical
- Shopping Vertical
- Social Vertical
- Travel Vertical
- Health & Fitness Vertical
- Other Verticals
- TV Getting Started
- TV Recommendations
- TV Continue Watching
- TV Entitlements
Vertical-Specific Schemas:
- Food Schema
- Watch Schema
- Listen Schema
- Read Schema
- Shopping Schema
- Social Schema
- Travel Schema
- TV Schema
- Other Schema

常见问题： Engage FAQ - 参考此文档获取开发者常见问题的解答。
垂直领域专属指南：
- 食品垂直领域
- 视频垂直领域
- 音频垂直领域
- 阅读垂直领域
- 购物垂直领域
- 社交垂直领域
- 旅行垂直领域
- 健康与健身垂直领域
- 其他垂直领域
- TV入门指南
- TV推荐
- TV继续观看
- TV权限
垂直领域专属架构：
- 食品架构
- 视频架构
- 音频架构
- 阅读架构
- 购物架构
- 社交架构
- 旅行架构
- TV架构
- 其他架构