flutter_biometric_auth_plus #

Enhanced biometric authentication with fallback options and better error handling for Flutter applications.

Features #

• 🔐 Enhanced Biometric Authentication: Support for fingerprint, face recognition, and iris scanning
• 🛡️ Fallback Options: Automatic fallback to device passcode when biometrics fail
• 📱 Cross-Platform: Works on both Android and iOS
• 🚨 Better Error Handling: Comprehensive error messages and user feedback
• 🔍 Device Capability Detection: Automatically detects available biometric methods
• 📊 Detailed Results: Rich authentication results with metadata
• 🎯 Type Safety: Built with Dart's strong typing system

Getting Started #

Prerequisites #

• Flutter 3.10.0 or higher
• Dart 3.0.0 or higher
• Android API level 23+ (Android 6.0+)
• iOS 11.0+

Installation #

Add this to your package's pubspec.yaml file:

dependencies:
  flutter_biometric_auth_plus: ^0.0.1

Platform Setup #

Android

Add the following permissions to your android/app/src/main/AndroidManifest.xml:

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

iOS

Add the following to your ios/Runner/Info.plist:

<key>NSFaceIDUsageDescription</key>
<string>This app uses Face ID to authenticate users</string>

Usage #

Basic Authentication #

import 'package:flutter_biometric_auth_plus/flutter_biometric_auth_plus.dart';

// Check if biometrics are available
bool isAvailable = await BiometricAuth.isBiometricsAvailable();

if (isAvailable) {
  try {
    // Authenticate using biometrics
    AuthResult result = await BiometricAuth.authenticate(
      reason: 'Please authenticate to access the app',
    );
    
    if (result.isSuccess) {
      print('Authentication successful using ${result.biometricType.displayName}');
    } else {
      print('Authentication failed');
    }
  } on BiometricException catch (e) {
    print('Biometric error: ${e.message}');
  }
}

Authentication with Fallback #

// Authenticate with fallback to device passcode
AuthResult result = await BiometricAuth.authenticateWithFallback(
  reason: 'Please authenticate to access the app',
  localizedFallbackTitle: 'Use Passcode',
);

if (result.isSuccess) {
  if (result.data?['fallbackUsed'] == true) {
    print('Authenticated using device passcode');
  } else {
    print('Authenticated using biometrics');
  }
}

Check Available Biometric Types #

List<BiometricType> availableBiometrics = await BiometricAuth.getAvailableBiometrics();

for (BiometricType type in availableBiometrics) {
  print('Available: ${type.displayName}');
}

Get Device Biometric Strength #

String strength = await BiometricAuth.getBiometricStrength();
print('Device biometric strength: $strength');

Error Handling #

try {
  await BiometricAuth.authenticate(reason: 'Authenticate');
} on BiometricException catch (e) {
  switch (e.code) {
    case 'BIOMETRICS_NOT_AVAILABLE':
      print('Biometrics not available: ${e.message}');
      break;
    case 'AUTHENTICATION_FAILED':
      print('Authentication failed: ${e.message}');
      break;
    case 'PERMISSION_DENIED':
      print('Permission denied: ${e.message}');
      break;
    default:
      print('Unknown error: ${e.message}');
  }
}

API Reference #

BiometricAuth #

Static Methods

• isBiometricsAvailable() - Check if biometric authentication is available
• getAvailableBiometrics() - Get list of available biometric types
• authenticate() - Authenticate using biometrics
• authenticateWithFallback() - Authenticate with fallback to device passcode
• isDeviceSupported() - Check if device supports biometric authentication
• getBiometricStrength() - Get device's biometric strength rating

BiometricType #

Enum representing available biometric types:

• fingerprint - Fingerprint authentication
• face - Face recognition
• iris - Iris scanning
• any - Any available biometric method
• none - No biometrics available

AuthResult #

Class representing authentication operation results:

• isSuccess - Whether authentication succeeded
• biometricType - Type of biometric used
• data - Additional metadata
• timestamp - When authentication occurred

AuthError #

Class representing authentication errors:

• code - Error code
• message - Human-readable error message
• details - Additional error details
• timestamp - When error occurred

BiometricException #

Exception thrown when biometric authentication fails:

• error - The underlying AuthError
• code - Error code
• message - Error message
• details - Error details

Examples #

See the example/ directory for complete working examples.

Contributing #

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License #

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments #

• Built on top of the excellent local_auth package
• Inspired by the need for better error handling and fallback options in biometric authentication

Support #

If you encounter any issues or have questions, please:

1. Check the existing issues
2. Create a new issue with detailed information
3. Contact the maintainer

Note: This package requires proper platform permissions and device capabilities to function correctly. Make sure to test on actual devices with biometric hardware.