Biometric Unavailable Banner
Component Detail
Description
Inline banner or modal shown when biometric hardware is absent or not enrolled on the device. Guides the user to device settings to enable biometrics or redirects to credential login. Respects the design token system for spacing and typography.
biometric-unavailable-banner
Summaries
The Biometric Unavailable Banner directly protects user retention at one of the highest drop-off moments in a mobile application: the authentication wall. When a user's device cannot offer biometric login — due to missing hardware or unenrolled credentials — this component prevents frustration-driven abandonment by clearly explaining the situation in plain language and offering immediate, actionable paths forward. Rather than leaving users stranded with a cryptic error, it guides them either to their device settings to enable biometrics or back to a familiar password login, keeping the session alive and the user engaged. The result is a measurable reduction in login-related support tickets and improved onboarding completion rates, both of which have a direct positive impact on retention KPIs and long-term revenue.
This is a low-complexity UI component scoped entirely to the mobile execution context, with no external service dependencies, making it a low-risk and independently deliverable work item. Development effort is minimal — one to two days for implementation and design-token compliance — but it must be scheduled after the design token system and the core authentication flow are established, as it depends on both for visual consistency and trigger logic. Testing requirements are straightforward: verify correct messages per BiometricUnavailableReason variant, confirm Settings redirect works on both iOS and Android, and validate the fallback-to-password path does not break session state. No backend coordination is needed.
Risk to delivery is negligible, but skipping it would leave a UX gap that could generate user complaints post-launch.
The BiometricUnavailableBanner is a stateless or near-stateless mobile UI component that receives a typed BiometricUnavailableReason discriminated union to drive its display logic. It exposes four clean interface methods: showWithReason() to initialize and render the banner or modal with context-appropriate copy, dismiss() to programmatically hide it, onGoToSettings() to invoke the platform-specific settings deep-link (using url_launcher or equivalent), and onUsePasswordInstead() to trigger navigation back to credential-based login. All spacing and typography must be sourced from the project's design token system — no hardcoded values. Since it has zero service dependencies, it can be unit-tested in isolation with mock reason values.
Integration points are upstream: the BiometricAuthService or the login orchestrator calls showWithReason() after a canAuthenticate() failure. Ensure reason messages are localized from the outset to avoid a future i18n refactor.
Responsibilities
- Communicate unavailability reason to the user in plain language
- Provide actionable redirect to OS settings for biometric enrollment
- Offer a one-tap path back to credential login
Interfaces
showWithReason(BiometricUnavailableReason)
dismiss()
onGoToSettings()
onUsePasswordInstead()
Used Integrations (1)
External integrations and APIs this component relies on