Original README snapshot from the linked source repository. Visit the repository for the latest content.
Flutter Liveness Detection Randomized Plugin
A Flutter plugin for liveness detection with randomized challenge response method with an interaction mechanism between the user and the system in the form of a movement challenge that indicates life is detected on the face. This plugin helps implement secure biometric authentication by detecting real human presence through dynamic facial verification challenges.
Author
Crafted with love by Bagus Subagja ❤️
Feel free to fork and modify this package to suit your needs - that's much more enjoyable and respectful 😊
Preview 🪟
https://github.com/user-attachments/assets/f7266dc9-c4a2-4fba-8684-0ead2f678180
Update 1.2.1
⬆️ Kotlin updated to 2.1.0 for better performance and support 16KB google page size policy
⬆️ compileSdk & targetSdk bumped to 36 (Android 16)
☕ Java & Kotlin JVM target upgraded to VERSION_17
📱 minSdk raised to 24 (Android 7.0)
🗑️ Removed useLegacyPackaging — no longer needed with modern AGP
🔍 google_mlkit_face_detection updated to 0.13.2
🐦 Flutter minimum version bumped to 3.38.7
Update 1.1.0
⏱️ Added automatic cooldown feature after 3 failed verification attempts
🔒 10-minute waiting period with persistent countdown (survives app restarts)
🎯 Countdown only decreases when app is active (pauses when app is backgrounded)
🔄 API Refactor : All parameters consolidated into LivenessDetectionConfig
🎯 Simplified API - only requires context and config parameters
🛠️ Fixed customizedLabel logic for proper skip challenge behavior
✅ Added validation: customizedLabel must not be null when useCustomizedLabel is true
Update 1.0.6
Face stretching already fixed on this version
Features ✨
📱 Real-time face detection
🎲 Randomized challenge sequence generation
💫 Cross-platform support (iOS & Android)
🎨 Light and dark mode support
✅ High accuracy liveness verification
🚀 Simple integration API
🎭 Customizable liveness challenge labels
⏳ Flexible security verification duration
🎲 Adjustable number of liveness challenges
🛠️ Adjustable image quality result
⏱️ Automatic cooldown after failed attempts
Getting Started 🌟
Add this to your package's pubspec.yaml file:
dependencies:
flutter_liveness_detection_randomized_plugin: ^1.2.1
Usage 🚀
final String ? response = await FlutterLivenessDetectionRandomizedPlugin .instance.livenessDetection (
context: context,
config: LivenessDetectionConfig (
cameraResolution: ResolutionPreset .medium,
imageQuality: 100 ,
isEnableMaxBrightness: true ,
durationLivenessVerify: 60 ,
showDurationUiText: false ,
startWithInfoScreen: true ,
isDarkMode: false ,
showCurrentStep: true ,
isEnableSnackBar: true ,
shuffleListWithSmileLast: true ,
useCustomizedLabel: false ,
customizedLabel: LivenessDetectionLabelModel (
blink: '' ,
lookDown: '' ,
lookLeft: null ,
lookRight: 'Turn Right' ,
lookUp: 'Look Up Please' ,
smile: null ,
),
enableCooldownOnFailure: true ,
maxFailedAttempts: 3 ,
cooldownMinutes: 10 ,
),
);
Configuration Parameters 📋
Camera & Image Settings
cameraResolution: Camera quality (ResolutionPreset.low/medium/high)
imageQuality: Output image quality 0-100 (default: 100)
isEnableMaxBrightness: Auto brightness adjustment (default: true)
Detection Settings
durationLivenessVerify: Detection timeout in seconds (default: 45)
showDurationUiText: Show countdown timer (default: false)
startWithInfoScreen: Show tutorial before detection (default: false)
UI Settings
isDarkMode: Dark theme mode (default: true)
showCurrentStep: Show current step number (default: false)
isEnableSnackBar: Show success/failure notifications (default: true)
shuffleListWithSmileLast: Randomize challenges with smile at end (default: true)
Customization
useCustomizedLabel: Enable custom challenge labels (default: false)
customizedLabel: Custom labels for each challenge type
Security Features
enableCooldownOnFailure: Enable cooldown after failed attempts (default: true)
maxFailedAttempts: Number of failures before cooldown (default: 3)
cooldownMinutes: Cooldown duration in minutes (default: 10)
Cooldown Feature
The plugin includes an automatic cooldown mechanism to prevent brute force attempts:
Configurable number of failed attempts before cooldown
Configurable cooldown duration
Countdown timer only decreases when app is active
Cooldown state persists through app restarts
Users see a countdown screen during cooldown period
Customized Steps Label
You can customize challenge labels or skip certain challenges:
Use empty string '' to skip a challenge
Use null to keep default label
Provide custom string for personalized labels
When useCustomizedLabel: true, customizedLabel must not be null
Complete Example 💡
import 'package:flutter_liveness_detection_randomized_plugin/index.dart' ;
class MyApp extends StatelessWidget {
@override
Widget build (BuildContext context) {
return MaterialApp (
home: Scaffold (
body: Center (
child: ElevatedButton (
onPressed: () async {
final result = await FlutterLivenessDetectionRandomizedPlugin .instance.livenessDetection (
context: context,
config: LivenessDetectionConfig (
startWithInfoScreen: true ,
isDarkMode: false ,
showCurrentStep: true ,
isEnableSnackBar: true ,
),
);
if (result != null ) {
print ('Face captured: $result ' );
} else {
print ('Detection failed' );
}
},
child: Text ('Start Liveness Detection' ),
),
),
),
);
}
}
Platform Setup
Android
Add camera permission to your android/app/src/main/AndroidManifest.xml:
<uses-permission android:name ="android.permission.CAMERA" />
Minimum SDK version: 24
iOS
Add camera usage description to ios/Runner/Info.plist:
<key > NSCameraUsageDescription</key >
<string > Camera access is required for liveness detection</string >
Testing Scenarios 🧪
The example app includes 8 comprehensive liveness scenarios to test all features:
Scenario 1: Default Configuration
LivenessDetectionConfig (
shuffleListWithSmileLast: true ,
startWithInfoScreen: true ,
)
Scenario 2: Random Shuffle
LivenessDetectionConfig (
shuffleListWithSmileLast: false ,
durationLivenessVerify: 30 ,
startWithInfoScreen: false ,
)
Scenario 3: Dark Mode + High Resolution
LivenessDetectionConfig (
isDarkMode: true ,
cameraResolution: ResolutionPreset .high,
durationLivenessVerify: 60 ,
)
Scenario 4: Custom Indonesian Labels
LivenessDetectionConfig (
useCustomizedLabel: true ,
customizedLabel: LivenessDetectionLabelModel (
blink: 'Kedip 2-3 Kali' ,
lookUp: 'Lihat ke Atas' ,
smile: 'Tersenyum Lebar' ,
),
)
Scenario 5: Skip Steps (Minimal Challenges)
LivenessDetectionConfig (
useCustomizedLabel: true ,
customizedLabel: LivenessDetectionLabelModel (
blink: 'Blink Eyes' ,
lookDown: '' ,
lookLeft: '' ,
lookRight: '' ,
lookUp: 'Look Up Please' ,
smile: 'Smile Wide' ,
),
)
Scenario 6: Timer + Cooldown Features
LivenessDetectionConfig (
showDurationUiText: true ,
enableCooldownOnFailure: true ,
maxFailedAttempts: 2 ,
cooldownMinutes: 5 ,
)
Scenario 7: Minimal Features
LivenessDetectionConfig (
isEnableMaxBrightness: false ,
isEnableSnackBar: false ,
showCurrentStep: false ,
)
Scenario 8: All Features Enabled
LivenessDetectionConfig (
isDarkMode: true ,
cameraResolution: ResolutionPreset .high,
showDurationUiText: true ,
enableCooldownOnFailure: true ,
useCustomizedLabel: true ,
customizedLabel: LivenessDetectionLabelModel (
blink: '👁️ Kedipkan Mata' ,
smile: '😊 Senyum Manis' ,
),
)
Migration Guide 🔄
From v1.0.x to v1.1.0+
All parameters are now consolidated into the LivenessDetectionConfig object:
Before:
await plugin.livenessDetection (
context: context,
config: LivenessDetectionConfig (...),
isEnableSnackBar: true ,
shuffleListWithSmileLast: true ,
showCurrentStep: true ,
isDarkMode: false ,
);
After:
await plugin.livenessDetection (
context: context,
config: LivenessDetectionConfig (
isEnableSnackBar: true ,
shuffleListWithSmileLast: true ,
showCurrentStep: true ,
isDarkMode: false ,
),
);