android flesh out
This commit is contained in:
135
android/docs/app-actions.md
Normal file
135
android/docs/app-actions.md
Normal file
@@ -0,0 +1,135 @@
|
||||
# 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)
|
||||
```bash
|
||||
# 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).
|
||||
Reference in New Issue
Block a user