Scenario Deep-Link Router
Component Detail
Description
Mobile-side service that parses incoming push notification payloads and routes the user to the correct in-app screen. Handles cold-start deep linking (app not running) as well as foreground routing. Used by the in-app banner and the notification detail view.
scenario-deep-link-router
Summaries
The Scenario Deep-Link Router is what turns a notification tap into a meaningful, seamless product experience. Without it, users who tap a push notification land on the app's home screen with no connection to the action they were invited to take — a friction point that wastes marketing investment and frustrates users. With it, users are taken directly to the relevant in-app screen, whether the app was already running or launched cold from a lock screen. This direct routing capability measurably improves notification-driven conversion rates and reinforces the perception that the product is responsive and well-crafted, supporting both retention and word-of-mouth growth.
This is a medium-complexity mobile component with no declared backend dependencies, but it has implicit coupling to every screen in the app that a notification can target. The primary delivery risk is scope creep: each time a new notification scenario is added, a corresponding deep-link route must be registered and tested, which creates an ongoing maintenance obligation for the mobile team. Cold-start handling adds meaningful QA complexity — tests must cover foreground routing, background resume, and fresh-launch deferred navigation as distinct paths. Coordination with the Scenario Notification Content Builder (which generates the deep-link URL) is required to ensure URL schema consistency.
Platform-specific quirks (iOS vs Android cold-start lifecycle) should be explicitly scoped in sprint planning.
This mobile service exposes `handleNotificationTap()`, `resolveRoute()`, `navigateTo()`, and `registerColdStartPayload()`. The routing logic pattern is a URL-to-named-route resolver: a deep-link URL such as `app://challenge/123` is parsed to extract the route name and parameters, then handed to the app's navigation stack. Cold-start deferred navigation requires storing the payload at `registerColdStartPayload()` before the navigation stack is initialised, then consuming it post-init. Back-stack integrity must be explicitly managed — navigating directly to a deep screen should push a sensible back-stack rather than leaving the user with no navigation path.
As a shared component consumed by both the in-app banner and notification detail view, changes to the URL schema or route registry must be backward-compatible or coordinated as a breaking change across all producers.
Responsibilities
- Parse deep-link URL from push notification payload
- Resolve the target named route and required parameters
- Navigate to the target screen preserving back-stack integrity
- Handle cold-start deferred navigation after app initialisation
Interfaces
handleNotificationTap(payload)
resolveRoute(deepLinkUrl)
navigateTo(route, params)
registerColdStartPayload(payload)
Relationships
Dependents (2)
Components that depend on this component