# 24. FCM Push Notification Deep Linking

meta:
  id: android-production-24
  feature: android-production
  priority: P2
  depends_on: [android-production-21]
  tags: [native-features, push-notifications, production]

objective:
- Ensure FCM push notifications correctly deep link to relevant screens with proper handling of app state

deliverables:
- Deep link routing for all notification types
- Cold start handling
- Background notification processing
- Notification analytics

steps:
1. Audit existing FCM handling:
   - Review android/app/.../service/FCMService.kt
   - Review NavGraph.kt for deep links
   - Identify gaps in notification handling
2. Implement deep link routes:
   - Alert notification → AlertDetail screen
   - Exposure notification → DarkWatch screen
   - Scan complete → Dashboard screen
   - Family invite → Settings/Family
   - Subscription renewal → Settings/Billing
   - Marketing → Landing or specific feature
3. Handle app states:
   - App closed (cold start): launch → process notification → navigate
   - App background: wake → process → navigate
   - App foreground: show in-app snackbar → navigate on tap
4. Add notification actions:
   - Alert: "View Details", "Dismiss", "Mark Safe"
   - Exposure: "View Exposure", "Start Removal"
   - Scan Complete: "View Results", "Share"
5. Implement analytics:
   - Track notification delivery
   - Track notification open rates
   - Track conversion from notification to action
   - A/B test notification copy
6. Add notification preferences:
   - Allow user to customize notification types
   - Respect system notification settings
   - Update backend preferences
7. Test all scenarios:
   - Cold start from each notification type
   - Background tap on notification
   - Foreground notification handling
   - Action button taps

tests:
- Unit: Test deep link route mapping
- Integration: Test FCM message handling
- Device: Send test notifications via Firebase Console

acceptance_criteria:
- All notification types deep link to correct screens
- Cold start from notification opens correct screen
- Background notification tap navigates correctly
- Foreground notifications show in-app snackbar
- Actionable notification buttons work
- Notification preferences respected
- Analytics tracking delivery and open rates
- Rich notifications with images render correctly
- No crashes from malformed notification payloads
- Unit tests for all deep link routes

validation:
- Send test alert notification → tap → AlertDetail opens
- Send exposure notification → app closed → DarkWatch opens
- Receive notification in foreground → snackbar shown
- Tap action button → correct action performed
- Check analytics → open rate tracked

notes:
- FCMService.kt already exists but may need enhancement
- Use NavDeepLinkBuilder for proper deep linking
- Test on different OEM skins (Samsung, Xiaomi)
- Coordinate with backend on notification payload format