Kordant/tasks/android-production/24-fcm-deep-links.md

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