Navigate Directly to Relevant Feature from Notification Tap
Each push notification payload includes a deep-link route payload that the Push Notification Service interprets when the notification is tapped. When the app is in the terminated state and a user taps a notification, the App Router Service reads the initial message payload on app launch and navigates to the target screen after authentication is verified. When the app is backgrounded, the onMessageOpenedApp handler intercepts the tap and navigates to the target screen. Notification types map to specific routes: new assignment → Assignment Detail, inactivity reminder → Activity Type Selection, follow-up reminder → Assignment Status Screen, milestone alert → Impact Summary Screen. Authentication is always verified before deep-linking to prevent unauthorized access.
User Story
Acceptance Criteria
- Given a user taps a 'new assignment' push notification while the app is terminated, when the app launches, then after successful authentication verification the user is navigated to the Assignment Detail screen for that specific assignment
- Given a user taps a push notification while the app is backgrounded, when the app comes to foreground, then the user is navigated to the target screen without passing through the home screen
- Given the target entity no longer exists when the notification is tapped (e.g., assignment was withdrawn), when the navigation resolves, then the user is shown an appropriate 'not found' message rather than a blank or crashed screen
- Given a notification is tapped by an unauthenticated session, when the app launches, then the user is first taken through the authentication flow and then redirected to the target screen upon successful login
- Given the user is already on the target screen when they tap the notification, when the navigation resolves, then the screen refreshes to show the latest state
Business Value
Deep-link navigation from notifications is critical for conversion from notification impression to in-app action. If tapping a notification only opens the app home screen, the user must then navigate manually to the relevant context, creating friction that reduces action rates. For peer mentors with low digital confidence, multi-step navigation is a known drop-off point. By routing users directly to the relevant screen, the system maximizes the percentage of notifications that result in completed actions — whether logging an activity, acknowledging an assignment, or reviewing a reminder.