136 lines
5.6 KiB
Markdown
136 lines
5.6 KiB
Markdown
# 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).
|