engage-sdk-integration

Workflow

1. 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.
2. 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.
3. 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

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

     .
5. 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.
6. 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.
7. 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.

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