face_recognition_flutter #

English | 简体中文

FaceAISDK's offline face recognition and liveness detection plugin for Flutter. It supports enrollment, 1:1 verification, local feature management, and native camera UI on Android and iOS.

Features #

• On-device face processing without a network connection.
• Face enrollment using the SDK camera or a Base64-encoded image.
• 1:1 face verification with a configurable similarity threshold.
• Motion, motion + color, color, and silent liveness detection.
• Local face feature query, insertion, deletion, existence checks, and image export.
• Compare two SDK-generated face features without opening the camera.
• Built-in native camera UI and an embeddable Flutter platform view.
• Native UI resources in English and Simplified Chinese.

Platform Support #

Swift Package Manager is not currently supported. Use CocoaPods for iOS integration.

Installation #

flutter pub add face_recognition_flutter

Android #

Add camera permission to android/app/src/main/AndroidManifest.xml:

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

Make sure the application uses minSdk 21 or later and Java 17:

android {
    defaultConfig {
        minSdk = 21
    }

    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
    }
}

iOS #

Set the minimum deployment target in ios/Podfile:

platform :ios, '15.5'

Add the FaceAISDK Core source inside the Runner target. Its tag must match the version required by the plugin podspec:

target 'Runner' do
  use_frameworks!

  flutter_install_all_ios_pods File.dirname(File.realpath(__FILE__))

  pod 'FaceAISDK_Core',
      :git => 'https://github.com/FaceAISDK/FaceAISDK_Core.git',
      :tag => '2026.09.22'
end

Add camera usage text to ios/Runner/Info.plist:

<key>NSCameraUsageDescription</key>
<string>FaceAISDK needs camera access for face enrollment and liveness verification.</string>

Localize this permission message in your app as needed.

Install the pods:

cd ios
pod install

Quick Start #

1. Enroll a face #

import 'package:face_recognition_flutter/face_recognition_flutter.dart';

final enrollment = await FaceRecognitionFlutter.addFaceBySDKCamera(
  faceId: 'user_001',
);

if (!enrollment.isSuccess) {
  print('Enrollment failed: ${enrollment.message}');
}

2. Verify the enrolled face #

final result = await FaceRecognitionFlutter.faceVerify(
  faceId: 'user_001',
);

if (result.isSuccess) {
  print('Verified. Similarity: ${result.similarity}');
} else {
  print('Verification failed: ${result.message}');
}

Liveness Detection #

Liveness modes #

Motion actions #

Pass action values as a comma-separated string, for example "1,2,3,4,5".

Validate thresholds and liveness behavior on devices used in your deployment.

Run liveness detection without 1:1 face comparison:

final result = await FaceRecognitionFlutter.livenessVerify(
  livenessType: 4,
);

API Reference #

All methods are asynchronous. Optional parameters and platform differences are documented in the Dart API.

Enroll from an image #

final result = await FaceRecognitionFlutter.addFaceBySDKImage(
  faceId: 'user_001',
  imageBase64: imageBase64,
);

Manage face features #

final featureResult = await FaceRecognitionFlutter.getFaceFeature('user_001');
final feature = featureResult.faceFeature;
if (feature != null) {
  await FaceRecognitionFlutter.insertFaceFeature(
    faceId: 'user_002',
    feature: feature,
  );
}

final exists = await FaceRecognitionFlutter.isFaceExist('user_002');
final image = await FaceRecognitionFlutter.getFaceImageBase64('user_001');

await FaceRecognitionFlutter.deleteFaceFeature('user_002');

Feature insertion does not create a face image. The image call above uses the camera-enrolled ID.

Compare face features #

final comparison = await FaceRecognitionFlutter.compareFaceFeatures(
  feature1: firstFeature,
  feature2: secondFeature,
);
if (comparison.isSuccess) {
  print('Similarity: ${comparison.similarity}');
} else {
  print(comparison.message);
}

Use two 1024-character, unpadded Base64 features returned by the SDK. Standard and URL-safe alphabets are supported. Validation checks the format only. isSuccess means the comparison completed; apply your own threshold to the raw similarity score to decide whether the faces match.

Embedded Native View #

Use FaceRecognitionView when the native camera view needs to be embedded in a Flutter layout:

FaceRecognitionView(
  creationParams: const <String, dynamic>{
    'needShowConfirmDialog': true,
  },
  onViewCreated: (controller) async {
    await controller.startScan();
  },
)

The controller provides startScan() and stopScan().

Result Object #

FaceRecognitionResult contains:

Result Codes #

Run the Example #

cd example
flutter pub get
flutter run

To select a device explicitly:

flutter devices
flutter run -d <device-id>

To run a release build on a physical device, use flutter run --release from example.

Troubleshooting #

Target file "lib/main.dart" not found #

Run the example application instead of the plugin package root:

cd example
flutter run

CocoaPods reports incompatible FaceAISDK_Core versions #

Make sure the explicit FaceAISDK_Core tag in the application Podfile matches the version required by ios/face_recognition_flutter.podspec, then run:

cd ios
pod update FaceAISDK_Core

iOS simulator architecture warnings #

Some transitive MLKit and TensorFlow Lite dependencies may not provide every simulator architecture. Use a physical iOS device for final verification.

Android Studio cannot find a connected device #

Confirm that flutter devices lists it. For Android, restart adb if necessary:

adb kill-server
adb start-server

Privacy #

Face recognition and liveness processing run locally on the device. Your application remains responsible for obtaining user consent and protecting any face images or biometric features it stores, transfers, or synchronizes.

Related SDKs #

• FaceAISDK iOS
• FaceAISDK Android
• FaceAISDK Flutter
• FaceAISDK React Native

See CHANGELOG.md for release history.