# 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