blusalt_liveness_native
Facial Comparison and Face Detection SDK for Android and IOS
Get your Liveness credentials from Blusalt
Features
Facial comparison (LivenessFacialComparisonType)
- Dynamic Liveness Detection (Motional): This method verifies liveness by requiring the user to perform specific actions like opening their mouth or shaking their head. It's strict because attempts to bypass the action (like holding a still image) will be detected and likely terminate the process.
- Static Liveness Detection (Still): This approach asks users to position their face within the camera frame and validates liveness based on facial data points. It's less strict than the dynamic method. If users struggle with finding the right camera position, the process might not automatically terminate, allowing them to adjust.
Face Detection (LivenessDetectionOnlyType)
- Dynamic Liveness Detection (Motional): Functions identically to the dynamic method under facial comparison. See above for details.
- Static Liveness Detection (Still): Same behavior as in facial comparison. Refer to the static method above for explanation.
- Flash Liveness Detection (Flash): This method is only available for facial detection, not facial comparison. It works similarly to the static method but increases the device screen brightness to enhance facial data point detection.
Usage
dependencies:
blusalt_liveness_native: ^lastVersion
///[webhookUrl] as webhook callback. Our server will POST data to this URL upon triggering events. (Reference is required)
///
///[thresholdInPercent] ranges between 0-100. The higher the value, the stricter the facial comparison.
///When set to null or no value is passed, it will use the default value from SDK which ranges from 90-94.
///
///[timeoutDurationInSec] this value can be used top override the timeout duration of networks calls in the SDK.
///When set to null or no value is passed, it will use the default value from SDK 120s.
///
/// [startProcessOnGettingToFirstScreen] starts the SDK on getting to the SDK homepage
/// rather than making user click continue button.
///
/// [showScore] If you want to show the score of facial comparison result.
///
/// [showThreshold] If you want to show the min required score of facial comparison result.
startFacialComparisonSDK() async {
BlusaltLivenessResultResponse? response =
await _livenessPlugin.startFacialComparisonSDK(
apiKey: apiKey,
appName: appName,
clientId: clientId,
isDev: isDev,
reference: null,
webhookUrl: null,
livenessFacialComparisonType:
LivenessFacialComparisonType.motional,
startProcessOnGettingToFirstScreen: true,
thresholdInPercent: null,
showScore: false,
showThreshold: false,
timeoutDuration: null);
}
startLivenessDetectionOnlySDK() async {
BlusaltLivenessResultResponse? response =
await _livenessPlugin.startLivenessDetectionOnlySDK(
apiKey: apiKey,
appName: appName,
clientId: clientId,
isDev: isDev,
reference: null,
webhookUrl: null,
livenessDetectionOnlyType:
LivenessDetectionOnlyType.still,
startProcessOnGettingToFirstScreen: true,
timeoutDuration: null);
}
Example
The following example leverages two external packages:
dependencies:
image_picker: ^lastVersion
flutter_highlight: ^lastVersion
import 'dart:io';
import 'dart:async';
import 'dart:convert';
import 'package:flutter/material.dart';
import 'package:flutter/services.dart';
import 'package:blusalt_liveness_native/enums.dart';
import 'package:blusalt_liveness_native/liveness.dart';
import 'package:blusalt_liveness_native/model.dart';
import 'package:image_picker/image_picker.dart';
import 'package:flutter_highlight/flutter_highlight.dart';
import 'package:flutter_highlight/themes/atom-one-dark.dart';
void main() {
runApp(const MyApp());
}
enum VerificationCompletedType { comparison, detection, none }
class MyApp extends StatefulWidget {
const MyApp({super.key});
@override
State<MyApp> createState() => _MyAppState();
}
class _MyAppState extends State<MyApp> {
final _livenessPlugin = BlusaltLivenessNative();
String? imageUri;
TextEditingController clientIdController = TextEditingController();
TextEditingController appNameController = TextEditingController();
TextEditingController apiKeyController = TextEditingController();
TextEditingController webHookUrlController = TextEditingController();
TextEditingController referenceController = TextEditingController();
TextEditingController thresholdController = TextEditingController();
TextEditingController timeoutDurationController = TextEditingController();
bool isDev = false;
// If you want to show the score of facial comparison result
bool isShowScore = false;
// If you want to show the min required score of facial comparison result
bool isShowThreshold = false;
// If you want to start the SDK on getting to the SDK homepage rather than making user click continue button
bool startProcessOnGettingToFirstScreen = false;
VerificationCompletedType verificationType = VerificationCompletedType.none;
final ImagePicker _picker = ImagePicker();
BlusaltLivenessResultResponse? resultResponse;
@override
void dispose() {
super.dispose();
clientIdController.dispose();
appNameController.dispose();
apiKeyController.dispose();
webHookUrlController.dispose();
referenceController.dispose();
thresholdController.dispose();
timeoutDurationController.dispose();
}
Future<BlusaltLivenessResultResponse?> startFaceComparison() async {
final XFile? image = await _picker.pickImage(source: ImageSource.gallery);
if (image != null) {
setState(() {
imageUri = image.path;
});
resultResponse = await _livenessPlugin.startFacialComparisonSDK(
apiKey: apiKeyController.text,
appName: appNameController.text,
clientId: clientIdController.text,
isDev: isDev,
webhookUrl: webHookUrlController.text.isEmpty
? null
: webHookUrlController.text,
reference: referenceController.text,
imageData: await image.readAsBytes(),
startProcessOnGettingToFirstScreen:
startProcessOnGettingToFirstScreen,
showScore: isShowScore,
showThreshold: isShowThreshold,
thresholdInPercent: validateNumber(thresholdController.text),
timeoutDurationInSec:
validateDurationNumber(timeoutDurationController.text));
if (resultResponse?.blusaltLivenessProcess ==
BlusaltLivenessProcess.completed) {
// Face comparison is successful
setState(() {
verificationType = VerificationCompletedType.comparison;
});
} else {
// Face comparison failed
debugPrint(resultResponse?.code ?? '');
debugPrint(resultResponse?.message ?? '');
}
return resultResponse;
}
return null;
}
Future<BlusaltLivenessResultResponse?> startLivenessDetectionOnly() async {
resultResponse = await _livenessPlugin.startLivenessDetectionOnlySDK(
apiKey: apiKeyController.text,
appName: appNameController.text,
clientId: clientIdController.text,
isDev: isDev,
webhookUrl: webHookUrlController.text.isEmpty
? null
: webHookUrlController.text,
reference: referenceController.text,
startProcessOnGettingToFirstScreen: startProcessOnGettingToFirstScreen,
timeoutDurationInSec:
validateDurationNumber(timeoutDurationController.text));
if (resultResponse?.blusaltLivenessProcess ==
BlusaltLivenessProcess.completed) {
// Liveness detection is successful
setState(() {
verificationType = VerificationCompletedType.detection;
});
} else {
// Liveness detection failed
debugPrint(resultResponse?.code ?? '');
debugPrint(resultResponse?.message ?? '');
}
return resultResponse;
}
double? validateNumber(String value) {
if (value.isEmpty) {
return null;
}
return double.tryParse(value);
}
int? validateDurationNumber(String value) {
if (value.isEmpty) {
return null;
}
return int.tryParse(value);
}
@override
Widget build(BuildContext context) {
return MaterialApp(
home: Scaffold(
appBar: AppBar(
title: const Text('Plugin example app'),
),
body: SingleChildScrollView(
padding: const EdgeInsets.all(16),
child: Column(
crossAxisAlignment: CrossAxisAlignment.center,
children: [
if (imageUri != null)
Image.file(
File(imageUri!),
width: 100,
height: 100,
)
else
const Padding(
padding: EdgeInsets.only(top: 20),
child: Text("No image selected"),
),
const SizedBox(height: 14),
TextField(
controller: clientIdController,
decoration: const InputDecoration(
border: OutlineInputBorder(),
hintText: "Enter client id",
hintStyle: TextStyle(color: Color(0xFFCCCCCC)),
),
onChanged: (text) => setState(() {}),
),
const SizedBox(height: 14),
TextField(
controller: appNameController,
decoration: const InputDecoration(
border: OutlineInputBorder(),
hintText: "Enter app name",
hintStyle: TextStyle(color: Color(0xFFCCCCCC)),
),
onChanged: (text) => setState(() {}),
),
const SizedBox(height: 14),
TextField(
controller: apiKeyController,
decoration: const InputDecoration(
border: OutlineInputBorder(),
hintText: "Enter api key",
hintStyle: TextStyle(color: Color(0xFFCCCCCC)),
),
onChanged: (text) => setState(() {}),
),
const SizedBox(height: 14),
TextField(
controller: webHookUrlController,
decoration: const InputDecoration(
border: OutlineInputBorder(),
hintText: "Enter webhook url (Optional)",
hintStyle: TextStyle(color: Color(0xFFCCCCCC)),
),
onChanged: (text) => setState(() {}),
),
const SizedBox(height: 14),
TextField(
controller: referenceController,
decoration: const InputDecoration(
border: OutlineInputBorder(),
hintText: "Enter reference (Optional)",
hintStyle: TextStyle(color: Color(0xFFCCCCCC)),
),
onChanged: (text) => setState(() {}),
),
const SizedBox(height: 14),
TextField(
controller: timeoutDurationController,
decoration: const InputDecoration(
border: OutlineInputBorder(),
hintText:
"Enter a duration you want SDK to timeout in seconds (Optional)",
hintStyle: TextStyle(color: Color(0xFFCCCCCC)),
),
keyboardType: TextInputType.number,
inputFormatters: [FilteringTextInputFormatter.digitsOnly],
maxLines: 2,
),
const SizedBox(height: 4),
CustomCheckbox(
label: "Point to Development Environment?",
value: isDev,
onCheck: (value) => setState(() => isDev = value),
),
const SizedBox(height: 2),
CustomCheckbox(
label: "Start Process On Getting To First Screen?",
value: startProcessOnGettingToFirstScreen,
onCheck: (value) =>
setState(() => startProcessOnGettingToFirstScreen = value),
),
const SizedBox(height: 34),
const Text(
'More Options Specific to Facial Comparison:',
textAlign: TextAlign.center,
style: TextStyle(fontSize: 17, fontWeight: FontWeight.bold),
),
const SizedBox(height: 2),
CustomCheckbox(
label: "Show Percent on completion",
value: isShowScore,
onCheck: (value) => setState(() => isShowScore = value),
),
const SizedBox(height: 2),
CustomCheckbox(
label: "Show Threshold on completion",
value: isShowThreshold,
onCheck: (value) => setState(() => isShowThreshold = value),
),
const SizedBox(height: 14),
TextField(
controller: thresholdController,
decoration: const InputDecoration(
border: OutlineInputBorder(),
hintText:
"Enter a threshold number for facial comparison which ranges from 0-100 (Optional)",
hintStyle: TextStyle(color: Color(0xFFCCCCCC)),
),
keyboardType: TextInputType.number,
inputFormatters: [FilteringTextInputFormatter.digitsOnly],
maxLines: 2,
),
const SizedBox(height: 24),
Row(
children: [
Expanded(
child: ElevatedButton(
onPressed: startLivenessDetectionOnly,
style: ElevatedButton.styleFrom(
backgroundColor: Colors.blue,
minimumSize: const Size(double.infinity, 50),
),
child: const Text(
"Start SDK Liveness Detection",
textAlign: TextAlign.center,
style: TextStyle(color: Colors.white),
),
),
),
const SizedBox(width: 16),
Expanded(
child: ElevatedButton(
onPressed: startFaceComparison,
style: ElevatedButton.styleFrom(
backgroundColor: Colors.blue,
minimumSize: const Size(double.infinity, 50),
),
child: const Text(
"Start SDK Facial Comparison",
textAlign: TextAlign.center,
style: TextStyle(color: Colors.white),
),
),
),
],
),
if (verificationType != VerificationCompletedType.none)
const SizedBox(height: 34),
if (verificationType != VerificationCompletedType.none)
Text(
"Result: (${verificationType == VerificationCompletedType.comparison
? 'Facial Comparison'
: 'Face Detection'})",
textAlign: TextAlign.center,
style: const TextStyle(fontWeight: FontWeight.w500),
),
if (verificationType != VerificationCompletedType.none)
const SizedBox(height: 4),
if (verificationType != VerificationCompletedType.none)
JsonViewerWidget(jsonData: resultResponse?.toJson()),
const SizedBox(height: 34),
Image.asset(
'assets/images/blusalt_logo.png',
width: 100,
height: 100,
color: Colors.black,
),
const SizedBox(height: 24),
],
),
),
),
);
}
}
class CustomCheckbox extends StatelessWidget {
final String label;
final bool value;
final Function(bool) onCheck;
const CustomCheckbox({
Key? key,
required this.label,
required this.value,
required this.onCheck,
}) : super(key: key);
@override
Widget build(BuildContext context) {
return Row(
children: [
Checkbox(
materialTapTargetSize: MaterialTapTargetSize.shrinkWrap,
value: value,
onChanged: (newValue) => onCheck(newValue ?? false),
),
Expanded(
child: Text(
label,
style: const TextStyle(fontWeight: FontWeight.w500),
)),
],
);
}
}
class JsonViewerWidget extends StatelessWidget {
final dynamic jsonData;
const JsonViewerWidget({
super.key,
required this.jsonData,
});
@override
Widget build(BuildContext context) {
final prettyJson = const JsonEncoder.withIndent(' ').convert(jsonData);
return ClipRRect(
borderRadius: BorderRadius.circular(8),
child: Stack(
children: [
SingleChildScrollView(
scrollDirection: Axis.vertical,
child: SingleChildScrollView(
scrollDirection: Axis.horizontal,
child: ConstrainedBox(
constraints: BoxConstraints(
minWidth: MediaQuery
.of(context)
.size
.width - 32,
),
child: HighlightView(
prettyJson,
language: 'json',
theme: atomOneDarkTheme,
padding: const EdgeInsets.all(16),
textStyle: const TextStyle(
fontFamily: 'monospace',
fontSize: 14,
),
),
)),
),
Positioned(
top: 8,
right: 8,
child: IconButton(
icon: const Icon(
Icons.copy,
color: Colors.white70,
size: 20,
),
onPressed: () {
_copyToClipboard(context, prettyJson);
},
tooltip: 'Copy to clipboard',
constraints: const BoxConstraints(),
padding: const EdgeInsets.all(8),
),
),
],
),
);
}
void _copyToClipboard(BuildContext context, prettyJson) {
Clipboard.setData(ClipboardData(text: prettyJson));
ScaffoldMessenger.of(context).showSnackBar(
const SnackBar(
content: Text('JSON copied to clipboard'),
duration: Duration(seconds: 2),
),
);
}
}
Installation
Android
Step 1
Create a github.properties file in root of android folder and put below into content.
Replace values with your github credentials from github and make sure to grant necessary permissions
especially for github packages
USERNAME_GITHUB=SampleUsername
TOKEN_GITHUB=SampleClassicToken
Step 2
Add below to project level gradle file /android/build.gradle
buildscript {
ext.kotlin_version = '1.9.+'
...
dependencies {
classpath 'com.android.tools.build:gradle:7.3.+'
classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
}
}
allprojects {
def githubPropertiesFile = rootProject.file("github.properties")
def githubProperties = new Properties()
githubProperties.load(new FileInputStream(githubPropertiesFile))
repositories {
maven {
name "GitHubPackages"
url 'https://maven.pkg.github.com/Blusalt-FS/Liveness-Only-Android-Package'
credentials {
username githubProperties['USERNAME_GITHUB']
password githubProperties['TOKEN_GITHUB']
}
}
}
}
Step 3
Change the minimum Android sdk version to 24 (or higher) in your /android/app/build.gradle file.
android {
...
defaultConfig {
...
minSdkVersion 24
}
...
}
Step 4
If you're experiencing crashes or timeouts.
Add below to your progaurd.pro file if using progaurd or minify is enabled
/android/app/proguard-rules.pro
-keep public class com.megvii.**{*;}
-keep class net.blusalt.liveness_native.** { *; }
Enable proguard in /android/app/build.gradle file like below.
android {
...
buildTypes {
release {
minifyEnabled true
proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
}
}
...
}
Note on Android:
If you are getting an error on android which says "Unauthorized" when gradle is downloading or building, generate a new github token that have access to clone, read and write to repo, access github packages. If you don't know which to tick, tick all boxes. Cheers
iOS
Minimum iOS Deployment = 14
Add one row to the ios/Runner/Info.plist:
with the key Privacy - Camera Usage Description and a usage description.
<key>NSCameraUsageDescription</key>
<string>your usage description here</string>
📱 Note on iOS
-
Physical Device Requirement
This plugin only works on a physical iOS device. iOS Simulators are not supported and may not reflect actual behavior. -
Ensure
BlusaltLivenessOnly.xcframeworkis Linked
In your Xcode workspace:- Navigate to
Pods>BlusaltLivenessOnly.xcframework - Confirm that it is properly linked and included in your app’s build target.
- Navigate to
-
Add Required Frameworks to Xcode
If you encounter errors related toMediaPlayerorWebKit, follow these steps:- Open your project in Xcode.
- Under the
TARGETSsection, click on Runner. - Go to the General tab and scroll to Frameworks, Libraries, and Embedded Content.
- Click the
+button and add the following frameworks:AVFoundation.frameworkCoreMedia.frameworkCoreMotion.frameworkMediaPlayer.frameworkSystemConfiguration.frameworkWebKit.framework