Kordant/tasks/ios-production/24-push-deep-links.md

24. Push Notification Deep Linking

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

objective:

• Ensure 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 push handling:
   • Review iOS/Kordant/Services/PushNotificationService.swift
   • Review KordantApp.swift handleNotificationNavigation
   • Identify gaps in deep linking
2. Implement deep link routes:
   • Alert notification → AlertDetailView
   • Exposure notification → DarkWatchView
   • Scan complete notification → DashboardView
   • 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 toast → navigate on tap
4. Add notification categories:
   • Actionable notifications (Resolve Alert, Dismiss)
   • Rich notifications with images
   • Grouped notifications by type
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 notification handling in all states
• 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 toast
• 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 alert notification → tap → AlertDetailView opens
• Send exposure notification → app closed → DarkWatchView opens
• Receive notification in foreground → toast shown
• Tap action button → correct action performed
• Check analytics → open rate tracked

notes:

• Current KordantApp.swift has basic routing but needs expansion
• Use UNUserNotificationCenter for modern notification handling
• Test on physical device — simulator push notifications are limited
• Coordinate with backend on notification payload format