Scenario Deep Link Handler
Component Detail
Description
Translates a triggered scenario prompt into a go_router deep-link navigation call that opens the activity registration wizard with pre-filled route arguments. Maps scenario context fields (contact ID, activity type, date suggestion) to wizard route parameters, ensuring the wizard opens at the correct step.
scenario-deep-link-handler
Summaries
The Scenario Deep Link Handler ensures that when users receive intelligent activity prompts, tapping them instantly opens the registration wizard pre-filled with the right contact, activity type, and suggested date — eliminating the friction that typically causes drop-off. By removing manual data entry steps, this component directly increases prompt-to-registration conversion rates, translating AI-driven engagement into measurable activity logging outcomes. It protects the ROI of the entire scenario engine by ensuring that generated prompts actually drive user action rather than being ignored, making the relationship intelligence investment visible and valuable to chapter administrators and members alike.
The Scenario Deep Link Handler carries medium complexity and depends on the prompt history repository for marking prompts as acted upon after navigation. Development must be sequenced after the wizard route API and ScenarioPrompt data model are finalized, as the parameter mapping logic is tightly coupled to route argument schemas that may evolve. Testing must cover edge cases where scenario context fields are partial or missing, requiring validated fallback navigation paths. QA must include device-level deep-link testing on both iOS and Android to verify that go_router URI construction behaves correctly across platform-specific link handling behaviors before the scenario prompting feature can be signed off.
Implemented in Flutter using go_router, this component maps ScenarioPrompt fields (contactId, activityType, dateSuggestion) to ActivityWizardArgs and constructs the appropriate URI for router navigation. The navigateToWizardFromPrompt method accepts a BuildContext and ScenarioPrompt, calls buildWizardRouteArgs to assemble the args struct, then uses go_router's context.go or context.push to trigger navigation. After navigation is initiated, markPromptActedUpon writes to prompt-history-repository asynchronously via a fire-and-forget Future. Error handling must catch navigation failures and fall back to the root wizard route without pre-fill.
The getRouteUri method is independently unit-testable for URI construction logic without requiring a widget tree or router context.
Responsibilities
- Build go_router route URI from scenario prompt context
- Map scenario metadata to wizard pre-fill arguments
- Trigger navigation and mark prompt as acted upon
- Handle navigation failure gracefully with fallback
Interfaces
navigateToWizardFromPrompt(BuildContext context, ScenarioPrompt prompt): void
buildWizardRouteArgs(ScenarioPrompt prompt): ActivityWizardArgs
markPromptActedUpon(String promptId): Future<void>
getRouteUri(ScenarioPrompt prompt): String
Relationships
Dependents (2)
Components that depend on this component