Face Recognition-FaceAISDK React Native Demo

August 1, 2026 · View on GitHub

English | 中文

This repository is API demo for @faceaisdk/react-native-face-sdk. It shows offline face enrollment, 1:1 verification, liveness detection, and face-feature management on iOS and Android.

The SDK depends on the device camera and native face algorithms. A physical device is required; simulators are not supported.

Features

  • Offline face enrollment with the SDK camera
  • 1:1 face verification with liveness detection
  • Standalone liveness detection
  • Query, insert, and delete face features
  • Face enrollment from a custom Base64 image

Requirements

ItemRequirement
Node.js22.11 or later
React NativeThis demo uses 0.84.0
Face SDKThis demo uses ^1.1.0
iOS15.0 or later, physical device
AndroidminSdkVersion 24+, compileSdkVersion 34+, physical device

Run This Demo

Install JavaScript dependencies:

npm install

Android

Start Metro in one terminal:

npm start

Connect a device with USB debugging enabled, then run in another terminal:

npm run android

iOS

Install CocoaPods dependencies:

cd ios
pod install
cd ..

Open ios/FaceAISDK_RN.xcworkspace in Xcode and select a Development Team under Signing & Capabilities.

Start Metro and run the app in separate terminals:

npm start
npm run ios

Install the SDK in Another Project

npm install @faceaisdk/react-native-face-sdk latest

iOS Configuration

Add the SDK post-install helper near the top of ios/Podfile:

require_relative '../node_modules/@faceaisdk/react-native-face-sdk/scripts/faceaisdk_post_install.rb'

Call it after React Native's post-install step:

post_install do |installer|
  react_native_post_install(
    installer,
    config[:reactNativePath],
    :mac_catalyst_enabled => false
  )
  faceaisdk_post_install(installer)
end

Install Pods:

cd ios && pod install

Add camera permission to Info.plist:

<key>NSCameraUsageDescription</key>
<string>Camera access is required for face recognition and liveness detection.</string>

Android Configuration

Make sure the Android project uses at least:

minSdkVersion = 24
compileSdkVersion = 34

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

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

Camera permission must also be requested at runtime on Android. See App.tsx for a working example using PermissionsAndroid.

Import

import {
  addFaceByImage,
  addFaceBySDKCamera,
  deleteFaceFeature,
  faceVerify,
  getFaceFeature,
  insertFaceFeature,
  isFaceAIModuleAvailable,
  livenessVerify,
  type FaceResult,
} from '@faceaisdk/react-native-face-sdk';

API Examples

Check Native Module Availability

const available = isFaceAIModuleAvailable();

Use this to detect an incomplete native installation before invoking an API.

Enroll a Face with the SDK Camera

const result = await addFaceBySDKCamera('demo-user', {
  mode: 1,
  showConfirm: true,
});
OptionTypeDescription
mode1 | 2Camera enrollment mode
showConfirmbooleanWhether to show the confirmation step

Face Verification with Liveness

const result = await faceVerify('demo-user', {
  threshold: 0.83,
  livenessType: 1,
  motionTypes: '1,2,3,4,5',
  timeout: 7,
  steps: 2,
  allowMultiFaces: true,
});

Standalone Liveness Detection

const result = await livenessVerify({
  livenessType: 1,
  motionTypes: '1,2,3,4,5',
  timeout: 7,
  steps: 2,
  allowMultiFaces: true,
});

faceVerify and livenessVerify share these liveness options:

OptionTypeDescription
livenessType1 | 2 | 3 | 4Liveness detection mode
motionTypesstringComma-separated motion type IDs
timeoutnumberLiveness timeout value
stepsnumberNumber of liveness steps
allowMultiFacesbooleanWhether multiple faces are allowed

faceVerify additionally accepts threshold, the face similarity threshold.

Query a Face Feature

const result = await getFaceFeature('demo-user');

Insert a Custom Face Feature

const customFeature = '0'.repeat(1024);
const result = await insertFaceFeature('demo-user', customFeature);

The placeholder demonstrates how to pass a custom feature. Replace it with a valid feature before expecting a successful SDK result.

Enroll from a Custom Base64 Image

const customBase64Image = 'demo_base64_image_string';
const result = await addFaceByImage('demo-user', customBase64Image);

Replace the placeholder with a valid Base64-encoded image.

Delete a Face Feature

const result = await deleteFaceFeature('demo-user');

Result

All asynchronous APIs resolve to FaceResult:

interface FaceResult {
  code: number;
  message: string;
  faceID: string;
  similarity: number;
  liveness: number;
  faceFeature: string;
  faceBase64: string;
}
PropertyTypeDescription
codenumberSDK result code
messagestringSDK result message
faceIDstringFace identifier
similaritynumberFace similarity score
livenessnumberLiveness score
faceFeaturestringFace feature data
faceBase64stringBase64 face image

Use message directly for the SDK-provided result text. The demo shows feature and Base64 lengths instead of placing potentially large values in an alert.

Troubleshooting

The Demo Shows “SDK Not Connected”

  • Confirm that the package is present in dependencies.
  • On iOS, run pod install and open the .xcworkspace, not the .xcodeproj.
  • Rebuild the native app after installing or upgrading the package.

Custom Feature or Base64 Enrollment Fails

The constants in App.tsx are intentionally fake values used to demonstrate custom argument passing. Replace them with a valid face feature or Base64 image.

Support & Feedback