Kordant/android/docs/app-actions.md

Kordant App Actions — Google Assistant Integration

Overview

Kordant integrates with Google Assistant via App Actions (Built-in Intents), allowing users to interact with the app using voice commands on Android devices that have Google Play Services installed.

Architecture

User says "Hey Google, check my threat score on Kordant"
                       │
                       ▼
            Google Assistant
          (Natural Language → BII match)
                       │
                       ▼
        actions.xml (actions.intent.OPEN_APP_FEATURE)
                       │
                       ▼
        Deep-link URI: kordant://dashboard?feature=THREAT_SCORE
                       │
                       ▼
        MainActivity.handleIntent() → parseDeepLink()
                       │
                       ▼
        DeepLink.Dashboard → ViewModel / NavGraph
                       │
                       ▼
        DashboardScreen (threat score displayed)

Fulfillment is entirely deep-link based — no custom broadcast receivers or services are needed for App Actions. All BIIs map to kordant:// URIs, which are handled by MainActivity.parseDeepLink() and dispatched via the Jetpack Navigation graph.

Supported Voice Commands

Voice Command	Action	Deep Link	Screen
"Hey Google, check my threat score on Kordant"	OPEN_APP_FEATURE	kordant://dashboard	Dashboard
"Hey Google, open Kordant"	OPEN_APP_FEATURE	kordant://dashboard	Dashboard
"Hey Google, show my dashboard on Kordant"	OPEN_APP_FEATURE	kordant://dashboard	Dashboard
"Hey Google, run a security scan on Kordant"	OPEN_APP_FEATURE	kordant://scan	New Scan
"Hey Google, start a scan on Kordant"	OPEN_APP_FEATURE	kordant://scan	New Scan
"Hey Google, scan my accounts on Kordant"	OPEN_APP_FEATURE	kordant://scan	New Scan
"Hey Google, do I have security alerts on Kordant"	OPEN_APP_FEATURE	kordant://alerts	Alerts
"Hey Google, check my alerts on Kordant"	OPEN_APP_FEATURE	kordant://alerts	Alerts
"Hey Google, show my notifications on Kordant"	OPEN_APP_FEATURE	kordant://alerts	Alerts
"Hey Google, open Kordant settings"	OPEN_APP_FEATURE	kordant://settings	Settings
"Hey Google, show my preferences on Kordant"	OPEN_APP_FEATURE	kordant://settings	Settings

Entity Vocabulary

The actions.xml defines entity sets that Google Assistant uses to match natural-language phrases to deep-link targets:

Entity Set	Entities	Target
dashboardEntities	dashboard, threat score, home	Dashboard
scanEntities	scan, security scan, run scan, start scan	New Scan
alertEntities	alerts, notifications, security alerts, threats	Alerts
settingsEntities	settings, preferences, account	Settings

Files

File	Purpose
res/xml/actions.xml	App Actions BII definitions, fulfillment templates, entity sets
AndroidManifest.xml	<meta-data> reference to actions.xml + deep-link intent-filters
MainActivity.kt	handleIntent() / parseDeepLink() — deep-link dispatch
AppNavigation.kt	DeepLink.Settings navigation handling
docs/app-actions.md	This documentation

Testing

Prerequisites

• Physical device with Google Play Services and Google Assistant
• Kordant installed on the device
• Same Google account on device and Play Console

Using App Actions Test Tool

1. Open the Google Assistant App Actions Test Tool on the device
2. Select Kordant from the app list
3. Test each BII by entering a sample query or using voice
4. Verify the app opens to the correct screen

Manual Testing (Physical Device)

1. Ensure Assistant is set up: long-press Home or say "Hey Google"
2. Say the voice command (e.g., "check my threat score on Kordant")
3. Verify Kordant opens to the expected screen
4. Verify the Assistant surfaces Kordant in suggestions

Deep Link Testing (adb)

# Open Dashboard
adb shell am start -d "kordant://dashboard" -a android.intent.action.VIEW

# Check Alerts
adb shell am start -d "kordant://alerts" -a android.intent.action.VIEW

# Run Scan
adb shell am start -d "kordant://scan" -a android.intent.action.VIEW

# Open Settings
adb shell am start -d "kordant://settings" -a android.intent.action.VIEW

# Open Services
adb shell am start -d "kordant://services" -a android.intent.action.VIEW

# Alert Detail with ID
adb shell am start -d "kordant://alert?id=123" -a android.intent.action.VIEW

# Service Detail with ID
adb shell am start -d "kordant://service?id=456" -a android.intent.action.VIEW

Notes

• App Actions require Google Play Services — they will not work on devices without Google Play (e.g., some Android emulators, Amazon Fire OS).
• Built-in Intents (BIIs) only — custom intents are not supported for third-party apps. Only actions.intent.OPEN_APP_FEATURE and other Google-defined BIIs are available.
• Slices are optional and being deprecated — we chose not to implement Slices because Google is deprecating them in favor of App Widgets, which Kordant already supports (Threat Score Widget).
• No crash from malformed intents — all parseDeepLink() paths return null for unrecognized URIs, and the navigation graph safely ignores null deep links.
• Token refresh / auth state — if the user is not authenticated when a deep link arrives, the deep link is held until the auth flow completes (handled by AppNavigation composable).