Kordant/tasks/shieldai-unified-restructure/39-android-native-features.md

# 39. Android App — Push Notifications, Biometrics, Voice Enrollment, Call Screening

meta:
  id: shieldai-unified-restructure-39
  feature: shieldai-unified-restructure
  priority: P1
  depends_on: [shieldai-unified-restructure-34, shieldai-unified-restructure-35, shieldai-unified-restructure-36, shieldai-unified-restructure-37, shieldai-unified-restructure-38]
  tags: [android, jetpack-compose, native-features, push, biometrics, call-screening, mobile]

objective:
- Implement native Android features that differentiate the mobile experience: push notifications via FCM, biometric authentication, voice enrollment with audio recording, and call screening integration for SpamShield.

deliverables:
- `android/app/src/main/java/com/shieldai/android/service/FCMService.kt` — Firebase Cloud Messaging:
  - Extends `FirebaseMessagingService`
  - `onMessageReceived` — processes incoming notifications
  - `onNewToken` — sends token to backend (task 14)
  - Creates notification channels for different alert types
  - Rich notifications with images and actions
  - Deep links to relevant screens based on payload
- `android/app/src/main/java/com/shieldai/android/ui/screens/auth/BiometricAuthScreen.kt` — Biometric prompt:
  - Uses `BiometricPrompt` from `androidx.biometric:biometric`
  - Face/fingerprint authentication
  - Fallback to device PIN/pattern/password
  - Stores credential in `EncryptedSharedPreferences`
- `android/app/src/main/java/com/shieldai/android/ui/screens/voiceprint/RecordingScreen.kt` — Voice recording:
  - Real-time waveform visualization using `AudioRecord` + `Canvas`
  - Record / stop / playback controls
  - Duration timer
  - Quality check (minimum duration, amplitude threshold)
  - Submit enrollment to API
- `android/app/src/main/java/com/shieldai/android/service/CallScreeningService.kt` — Call screening:
  - Extends `CallScreeningService` (API 29+)
  - Intercepts incoming calls
  - Queries `spamshield.checkNumber` via API
  - Displays caller info overlay with reputation score
  - Auto-blocks known spam numbers based on user rules
  - Logs screened calls for history
- `android/app/src/main/java/com/shieldai/android/util/PermissionManager.kt` — Permission handling:
  - Centralized manager for all runtime permissions
  - Camera, microphone, phone, notifications, call screening
  - Handles permission rationale and denied states
- `android/app/src/main/AndroidManifest.xml` — Updated permissions and services:
  - `INTERNET`, `RECORD_AUDIO`, `READ_PHONE_STATE`, `CALL_PHONE`
  - `BIND_CALL_SCREENING_SERVICE`
  - `RECEIVE_BOOT_COMPLETED` (for starting services)
  - FCM service declaration
  - Call screening service declaration

steps:
1. **Push Notifications (FCM)**:
   - Add `google-services.json` to `app/` directory
   - Add `com.google.gms:google-services` plugin to build.gradle
   - Create `FCMService.kt` extending `FirebaseMessagingService`
   - `onNewToken`: send to backend via `api.notification.registerDevice`
   - `onMessageReceived`:
     - Parse notification payload
     - Create notification channel if not exists (Android 8+)
     - Show notification with `NotificationManager`
     - Handle data messages (silent pushes) for background sync
   - Add `FirebaseMessaging.getInstance().subscribeToTopic("alerts")` for broadcast alerts
   - Handle notification tap: extract `screen` and `id`, navigate via deep link
2. **Biometric Auth**:
   - `BiometricPrompt` with `BiometricPrompt.PromptInfo`
   - `setDeviceCredentialAllowed(true)` for fallback
   - `setConfirmationRequired(false)` for faster auth
   - On success: unlock `EncryptedSharedPreferences`
   - Show prompt on app launch if biometric is enabled
3. **Voice Recording**:
   - Request `RECORD_AUDIO` permission at runtime
   - `AudioRecord` with `MediaRecorder.AudioSource.MIC`
   - Configuration: 16kHz, mono, 16-bit PCM
   - Real-time waveform: read amplitude in a coroutine, update `Canvas` path
   - Minimum duration: 5 seconds
   - Save as WAV file
   - Playback with `MediaPlayer`
   - Submit to API via multipart upload
4. **Call Screening**:
   - Extend `CallScreeningService`
   - `onScreenCall(details)` callback when incoming call arrives
   - Extract phone number from `Call.Details`
   - Query API: `spamshield.checkNumber` (use cached result if available)
   - `respondToCall` with `CallResponse.Builder`:
     - If spam: `setDisallowCall(true)`, `setRejectCall(true)`, `setSkipCallLog(false)`
     - If suspicious: `setDisallowCall(false)` but show warning notification
     - If clean: `setDisallowCall(false)`
   - Show custom incoming call UI overlay (optional, requires additional permissions)
   - Log all screened calls to local DB
5. **Permission Manager**:
   - `checkPermission(permission)` → boolean
   - `requestPermission(permission, rationale)` → shows dialog, then system prompt
   - `handlePermissionResult(requestCode, permissions, grantResults)`
   - Guides user to Settings if permission permanently denied
6. Update manifest:
   - Add all required permissions
   - Declare FCM service with `android:exported="false"`
   - Declare call screening service with `android:permission="android.permission.BIND_CALL_SCREENING_SERVICE"`
7. Test on physical device (emulator cannot test FCM, biometrics, or call screening accurately).

steps:
- Unit: FCMService parses notification payload correctly
- Unit: BiometricPrompt configuration is valid
- Unit: PermissionManager returns correct status for each permission
- Integration: FCM token registration sends correct data to backend
- E2E: Receive test push notification and verify deep link navigation
- E2E: Record voice sample and submit enrollment successfully
- E2E: Simulate incoming call and verify screening logic

acceptance_criteria:
- [ ] App registers for FCM and sends device token to backend
- [ ] Incoming push notifications display correctly with channels and actions
- [ ] Tapping a notification deep links to the correct screen
- [ ] Face/fingerprint authentication works for app unlock
- [ ] Voice recording captures audio, shows waveform, and submits enrollment
- [ ] Call screening intercepts incoming calls and blocks known spam
- [ ] All permission requests include explanatory rationale
- [ ] Denied permissions show helpful guidance to Settings app
- [ ] Native features work on phones with API 26+

validation:
- Test push notifications using Firebase Console
- Verify biometric auth on device with face/fingerprint sensor
- Record a 10-second voice sample and verify enrollment created in backend
- Simulate incoming call using `adb shell am start -a android.intent.action.CALL -d tel:1234567890`
- Run `./gradlew test` for unit tests

notes:
- FCM requires a `google-services.json` file from Firebase Console. Add setup instructions to README.
- Call screening (`CallScreeningService`) is only available on Android 10+ (API 29+). For older versions, use a broadcast receiver for `PHONE_STATE` changes as fallback.
- The call screening service runs in the background and must be lightweight. Offload API calls to a coroutine.
- For call screening UI, the system provides a default incoming call screen. Custom UI overlays require `SYSTEM_ALERT_WINDOW` permission and are complex to implement correctly.
- Voice recording quality matters for ML model accuracy. Use 16kHz mono WAV — this matches the web app's preprocessing pipeline.
- Biometric auth should be optional. Users can always use password login.
- Consider adding a Quick Settings tile for toggling call screening on/off.
- For Android 14+ (API 34+), use the new `android.telecom.Call Screening` APIs if available.