Biometric Prompt Overlay
Component Detail
Description
Full-screen overlay displayed on app resume that triggers the native biometric authentication dialog. Shows the app logo, a brief prompt message, and a fallback link to credential login. Handles Face ID on iPhone and fingerprint on supported Android devices.
biometric-prompt-overlay
Summaries
The Biometric Prompt Overlay delivers the first interaction users have with the app on every return visit, making it a critical touchpoint for perceived security and ease of use. By surfacing Face ID or fingerprint authentication immediately on app resume, the platform removes the friction of manual credential entry while meeting the security expectations of organizations handling sensitive member or financial data. This directly reduces login abandonment and session drop-off rates, improving daily active engagement metrics. The overlay's built-in fallback to credential login ensures no user is locked out, protecting retention across devices where biometrics may be unavailable or misconfigured.
A seamless, branded biometric experience also reinforces trust in the platform, which is a meaningful competitive differentiator in markets where data sensitivity is a primary adoption concern.
This is a low-complexity mobile UI component with a single hard dependency on the biometric-auth-service, which must be completed and stable before integration testing can begin. Development effort centers on the Flutter overlay widget, the local_auth plugin integration via biometric-auth-service, and the fallback navigation to the credential login screen. Key delivery risks include device-specific biometric behavior differences between iOS (Face ID) and Android (fingerprint), which require dedicated device testing on representative hardware — emulators are insufficient for biometric flows. WCAG 2.2 AA contrast compliance adds a QA checkpoint that design should review before handoff.
The overlay's behavior on app resume requires lifecycle testing across both platforms (foreground/background transitions). Budget one additional testing cycle for edge cases: biometric enrollment changes, device lockout states, and concurrent auth attempts.
This component is a Flutter overlay widget that subscribes to app lifecycle events (specifically `AppLifecycleState.resumed`) and imperatively calls `show()` to trigger the native biometric dialog via the `biometric-auth-service` dependency, which wraps `local_auth`. The `show()` method should guard against double-invocation using a boolean mutex (`_isShowing`), since rapid resume/pause cycles can fire multiple lifecycle events. `onBiometricSuccess()` should call `dismiss()` and emit a navigation event (or resolve a completer) to unblock the app. `onBiometricFailure(reason)` must distinguish between user cancellation (retry allowed) and permanent lockout (force fallback), inspecting the `BiometricError` reason code from `local_auth`.
`onFallbackRequested()` navigates to the credential login route — use a named route or a callback injected at construction to keep this component decoupled from routing logic. `setPromptMessage()` allows the parent to localize the prompt string. The overlay widget itself should use a `Stack` with a barrier layer beneath the prompt card to prevent interaction with the underlying screen during auth.
Responsibilities
- Display native biometric prompt via local_auth on app resume
- Show fallback link to email/password login when biometrics are unavailable or declined
- Provide accessible UI meeting WCAG 2.2 AA contrast requirements
Interfaces
show()
dismiss()
onBiometricSuccess()
onBiometricFailure(reason)
onFallbackRequested()
setPromptMessage(message)
Relationships
Dependencies (1)
Components this component depends on
Used Integrations (1)
External integrations and APIs this component relies on