Biometric Authentication

Fluxy Biometrics offers a high-level API to integrate secure Face ID and Fingerprint authentication with standardized platform prompts.

[GUIDE] Industrial Step-by-Step

1. Installation (via CLI)

Add the biometrics module using the Fluxy CLI to maintain architectural integrity.

fluxy module add biometric

2. Managed Boot Sequence

Ensure your main.dart is configured with the mandatory three-step boot sequence.

import 'package:fluxy/fluxy.dart';
import 'core/registry/fluxy_registry.dart'; 

void main() async {
  await Fluxy.init();
  Fluxy.registerRegistry(() => registerFluxyPlugins()); 
  Fluxy.autoRegister(); // Boots biometric hardware handlers
  runApp(MyApp());
}

3. Usage (Unified API)

Access the module through the stable Fx.platform gateway.

// Simple Authentication
bool authenticated = await Fx.platform.biometric.authenticate(
  reason: "Please authenticate to access your vault",
);

// Reactive Status
Fx(() {
  final isAvailable = Fx.platform.biometric.isAvailable.value;
  return Fx.text("Hardware ready: $isAvailable");
});

Core Functionality

1. Check Availability

Before requesting authentication, check if the device supports biometrics and has data enrolled.

if (await Fx.platform.biometric.isAvailable()) {
  final types = await Fx.platform.biometric.getAvailableTypes();
  // returns [BiometricType.face, BiometricType.fingerprint]
}

2. Security Tiers

Enforce strong biometrics for sensitive actions or allow passcode fallback.

await Fx.platform.biometric.challenge(
  reason: "Access Secure Vault",
  strongAuthOnly: true, // Hardware only, no PIN
);

The Wrong Way vs. The Right Way

Pitfalls & Troubleshooting

1. "Authenticate returns false instantly without a prompt"

• The Cause: Lack of permissions in AndroidManifest.xml.
• The Fix: Ensure you have added the USE_BIOMETRIC permission.

2. "isAvailable is true but authenticate fails"

• The Cause: Hardware present but no fingerprints/Face ID enrolled.
• The Fix: Use getAvailableTypes() to verify enrolled data.

3. "The OS prompt doesn't show up on iOS"

• The Cause: Missing NSFaceIDUsageDescription in Info.plist.
• The Fix: Add the usage description key.

Best Practices

1. Fallback Logic: Always have a password-based fallback if biometrics fail.
2. Contextual Challenges: Don't authenticate on every app launch unless necessary (e.g., banking).
3. Hardware Readiness: Use the isAvailable signal to hide biometric settings in the profile view.