Skip to content
Docs
Main site, archipelago.banuacoder.com
Back to archipelago.banuacoder.com

Feature SDKs (Pro)

biometric_auth_sdk Pro ​

Tier
Proversion 2.0.4
Command
archipelago generate biometric_auth_sdk
Generates
  • features/biometric_auth/biometric_auth_api
  • features/biometric_auth/biometric_auth_impl
Generates first
storage_sdkwhen needed and missing, so there is nothing to install first

Biometric authentication (Face ID / Touch ID / fingerprint) feature SDK. Wraps local_auth and integrates as a passive unlock gate alongside auth_sdk.

What it is ​

A self-contained biometric_auth_api/biometric_auth_impl feature pair that lets a project prompt for Face ID/Touch ID/fingerprint and persist an "enabled" toggle. It is deliberately not a login mechanism on its own — see "Unlock vs. primary credential" below.

Variables ​

brick.yaml declares no vars: at all — this brick has no generation-time variables.

Prerequisites ​

  • hooks/pre_gen.dart requires archipelago.yaml to already exist (ArchipelagoConfigGuard.requireExists()), and prints iOS/Android platform-setup reminders up front.
  • storage_sdk is no longer a manual prerequisite. Since 1.3.0, pre_gen.dart checks archipelago.yaml's installed-bricks list and self-generates storage_sdk via SubBrickGenerator if it's missing — archipelago generate biometric_auth_sdk works standalone into a bare workspace.

Usage ​

Interactive ​

bash
archipelago generate biometric_auth_sdk

Non-interactive (CI) ​

bash
archipelago generate biometric_auth_sdk --config my_config.json

Generated Structure ​

text
features/
└── biometric_auth/
    ├── biometric_auth_api/
    │   ├── lib/
    │   │   ├── biometric_auth_api.dart
    │   │   └── src/
    │   │       ├── biometric_auth_sdk.dart           # BiometricAuthSDK contract
    │   │       └── models/
    │   │           ├── biometric_auth_failure_reason.dart
    │   │           ├── biometric_auth_result.dart    # sealed: Success/Failure
    │   │           ├── biometric_capability.dart
    │   │           └── biometric_type.dart
    │   ├── test/biometric_auth_api_test.dart
    │   └── pubspec.yaml
    └── biometric_auth_impl/
        ├── lib/
        │   ├── biometric_auth_impl.dart
        │   └── src/
        │       ├── biometric_auth_sdk_impl.dart
        │       └── di/
        │           ├── injector.dart
        │           ├── injector.module.dart
        │           └── register_module.dart
        ├── test/biometric_auth_sdk_impl_test.dart
        └── pubspec.yaml

Public API ​

dart
abstract interface class BiometricAuthSDK {
  Future<BiometricCapability> getCapability();
  Future<bool> isBiometricEnabled();
  Future<void> setBiometricEnabled({required bool enabled});
  Future<BiometricAuthResult> authenticate({
    required String reason,
    bool stickyAuth,
  });
}

There is no isAvailable() method and no .isSuccess getter. Usage, from the SDK's own doc comment:

dart
final biometricSDK = getIt<BiometricAuthSDK>();

final capability = await biometricSDK.getCapability();
if (!capability.isEnrolled) return;

final result = await biometricSDK.authenticate(
  reason: 'Verify your identity to continue.',
);

switch (result) {
  case BiometricAuthSuccess():
    getIt<AuthSDK>().loginSuccess(userId: storedUserId);
  case BiometricAuthFailure(:final reason):
    if (reason != BiometricAuthFailureReason.userCancelled) showError();
}

BiometricCapability carries isDeviceSupported, isEnrolled, and availableTypes (Set<BiometricType> — face, fingerprint, iris, strong, weak); BiometricCapability.unsupported() is the convenience constructor for web/desktop/no-sensor devices — getCapability() is safe to call on any platform and never throws. BiometricAuthFailureReason covers notAvailable, notEnrolled, lockedOut, permanentlyLockedOut, passcodeNotSet, userCancelled, unknown.

Implementation notes ​

BiometricAuthSDKImpl depends on local_auth: ^3.0.2, which replaced the older AuthenticationOptions(stickyAuth: ...)/PlatformException-only error model with a direct persistAcrossBackgrounding: parameter and a structured LocalAuthException/LocalAuthExceptionCode. The impl catches LocalAuthException first (mapping each code to a BiometricAuthFailureReason) and falls back to catching PlatformException defensively for anything that hasn't migrated to the new exception type. authenticate() returning false (user dismissed the prompt without a platform error) is mapped to BiometricAuthFailureReason.userCancelled.

Unlock vs. primary credential ​

Biometric is an unlock gate, not a primary credential — a successful prompt verifies identity locally but creates no backend session. The SDK never calls loginSuccess itself; the host app must do that after a BiometricAuthSuccess, keeping session semantics under the caller's control.

Wiring (auto-patched by post_gen.dart) ​

  • Registers both packages into the melos workspace. The SDK impl is a lazy @LazySingleton (since 2.0.0): nothing runs at boot, so it is built on first use.
  • Adds biometric_auth_impl as a path dependency to the host app's pubspec.yaml.
  • Injects BiometricAuthImplPackageModule into the app's lib/di/injector.dart via ServiceLocatorUpdater.addExternalModule.
  • Contributes local_auth's R8/ProGuard keep rules into android/app/proguard-rules.pro (between the archipelago:proguard:keep-rules markers flutter_modular_monorepo/app_scaffold ship) — advisory no-op if there's no Android app directory yet.
  • Runs dart format on the touched directories, and appends biometric_auth_sdk to archipelago.yaml's installed-bricks list.

Platform setup ​

iOS — Info.plist ​

xml
<key>NSFaceIDUsageDescription</key>
<string>We use Face ID to quickly verify your identity.</string>

Without this key, local_auth crashes at runtime when it requests Face ID on iOS. pre_gen.dart prints this reminder, but does not patch Info.plist for you.

Android — permission ​

BiometricPrompt (API 28+) needs no manifest permission. For API 23–27 (fingerprint only):

xml
<uses-permission android:name="android.permission.USE_FINGERPRINT" />

Android — R8/ProGuard ​

Handled automatically by post_gen.dart (see Wiring above) — requires shared_hooks >= 1.8.0.

Dependencies ​

Self-generates storage_sdk if missing — biometric_auth_impl persists the enabled flag through storage_sdk_api's StorageProvider rather than registering its own SharedPreferences instance, specifically to avoid a GetIt duplicate-registration crash when installed alongside feedback_sdk/rating_review_sdk (both of which also touch SharedPreferences-backed storage). Depends on local_auth, equatable, feature_sdk.

Limitations ​

  • Does not store or manage session tokens — that stays with auth_sdk.
  • On Android emulators without enrolled biometrics, getCapability().isEnrolled is false.

Changelog ​

Run archipelago brick info biometric_auth_sdk to see the latest published version. Enterprise customers can read the full CHANGELOG.md in the brick source repository.