Integrate OpenSRP with External App via In-App Intent

[roywanyaga]

Background/Context
The client app is used by health workers and supervisors for daily service delivery workflows. Many implementations also use a separate national eLearning app for training and certification (for example, an MoH eLearning app distributed via Google Play).

Currently, users have to exit the client app, find the eLearning app manually, and then switch back. We would like to launch the eLearning app directly from within the client, while keeping the integration generic and configurable, not hard-coded to a single country or app.

For one example deployment, the target eLearning app is available on Google Play under the package:

com.palladium.ugmohelearning

But the solution should work for any external app package configured per deployment.

User Stories

• As a frontline health worker, I want a simple action in the app (button/menu item) that opens my official eLearning app, so I can quickly access training content without manually searching for it on my phone.

• As an implementation team, I want to configure the target Android package name and label for the external app (and turn the feature on/off) without changing code, so the same client build can be reused across multiple countries.

• As a technical admin, if the app is not installed on the device, I want the app to show a clear message (and optionally a Play Store link) instead of crashing.

Proposed Approach

1. Config-driven integration

Introduce a new configuration section. Example structure:
Have a new Workflow LAUNCH_EXTERNAL_APP that can be triggered from the Navigation Menu or the Settings Page.

Example config structure

{
    "externalApps": {
      {
        "id": "elearning"
        "enabled": true,
        "label": "Go to eLearning",
        "packageName": "com.palladium.ugmohelearning",
        "playStoreUrl": "https://play.google.com/store/apps/details?id=com.palladium.ugmohelearning"
      }
    }
  }

2. UI placement

• Navigation Menu
  or
• Settings Page

3. Launching the external app

• On click:
  1. Read the packageName from config.
  2. Use PackageManager to check if an app with that package exists.
  3. Behavior:
     • If installed:
       - Use an Intent with ACTION_MAIN and CATEGORY_LAUNCHER (or a simpler getLaunchIntentForPackage) to start the app.
     • If not installed:
       - If playStoreUrl is configured: Open that URL in a browser or Play Store.
       - Otherwise: Show a simple dialog/toast explaining that the eLearning app is not installed and the user should contact their supervisor/admin.

4. Generic design

• No hard-coded reference to a specific eLearning app in code.
• Only the config defines:
  - Whether the feature is visible.
  - What it’s called in the UI.
  - Which app is launched.

This allows the same codebase to support:

• Uganda: com.palladium.ugmohelearning
• Another country: a completely different package
• Some deployments: feature disabled (no UI item shown)

Acceptance criteria

• A configuration structure exists to enable/disable the intent based app launcher and specify:

  -label – the text shown in the UI
  -packageName – the Android package to launch
  -playStoreUrl (optional) – link to install the external app if missing

• When configuration is enabled, the UI displays an entry point using the configured label.

  • When the user taps the entry point:
    1. If the external app is installed, the system launches it using the configured packageName.
    2. If the external app is not installed:
       • If playStoreUrl is provided, open that URL (typically Play Store listing).
         - If no playStoreUrl is provided, show a friendly message (e.g., “The app is not installed”) instead of crashing.

• When the config is disabled or the config block is missing, the entry point is not shown anywhere in the UI.

[roywanyaga]

This is currently out of scope but we may later explore (for elearning context only)

• Authentication integration with Keycloak,
• Passing authenticated user context between the apps.
• Deep-linking directly into specific application modules,
• Surfacing MoH-hosted training completion status inside OpenSRP.

For now, this issue focuses strictly on enabling access via an intent.

[qiarie]

@roywanyaga Is the assumption that the user will already have credentials to the learning app?

[qiarie]

@roywanyaga I have skipped using "enabled": true in the external app config.

There is already a "visible": true config in NavigationMenuConfig that covers whether an item is shown on the navigation menu or not.