FaceAISDK React Native Demo

English | 中文

Offline face enrollment, verification, and liveness detection on iOS and Android with @faceaisdk/react-native-face-sdk.

Requirements

• Node.js 22.11+, React Native 0.84.0, CLI 20.2.0, Face SDK 1.7.1 (iOS Core 2026.09.22).
• A physical device: iOS 15.5+ or Android API 24+. Simulators are not supported.
• Xcode and CocoaPods for iOS; Android SDK (compile SDK 34) and JDK 17 for Android.

Run

Install dependencies and start Metro on port 8765:

npm install
npm start

Keep Metro running; use another terminal for the commands below.

Android

Connect a device with USB debugging enabled:

npm run android

iOS

Install Pods:

cd ios
pod install
cd ..

Open ios/FaceAISDK_RN.xcworkspace in Xcode and select your Development Team under Signing & Capabilities. Connect an iPhone, then run:

npm run ios

For Debug builds, the iPhone must be able to reach Metro on your computer's port 8765. If CLI installation fails with devicectl, select the connected device in Xcode and use Product > Run instead.

iOS 16 and Earlier

Use ios-deploy instead of devicectl. Connect and unlock one iPhone, trust the computer, then run from the project root:

npm run ios:legacy

This builds a Release app and installs it; tap the app icon to launch. Metro is not needed. Build files are cached in ios/build; existing Pods and build caches are not deleted. The CLI version and npm run ios remain unchanged. Output is brief; the full log is saved to ios/build/ios-legacy.log (replaced each run) and printed automatically if building or installation fails.

Demo APIs

See App.tsx for the complete example. Import APIs from @faceaisdk/react-native-face-sdk; each call below returns Promise.

const faceID = 'demo-user';
const options = {
  livenessType: 1 as const,
  motionTypes: '1,2,3,4,5',
  timeout: 7,
  steps: 2,
  allowMultiFaces: true,
};

| Menu | API call | | ----------------------------- | ---------------------------------------------------------- | | Enroll face with camera | addFaceBySDKCamera(faceID, {mode: 1, showConfirm: true}) | | Face verification + liveness | faceVerify(faceID, options) | | Liveness detection | livenessVerify(options) | | Query face feature | getFaceFeature(faceID) | | Insert custom face feature | insertFaceFeature(faceID, feature) | | Enroll face from Base64 image | addFaceByImage(faceID, base64Image) | | Delete face feature | deleteFaceFeature(faceID) |

• Enroll a face before verification or lookup. Standalone liveness needs no enrollment.
• DEMO_FACE_FEATURE and DEMO_BASE64_IMAGE in App.tsx are empty by default.

• motionTypes contains comma-separated motion IDs; timeout, steps, and

Results

interface FaceResult {
  code: number;
  message: string;
  faceID: string;
  similarity: number;
  liveness: number;
  faceFeature: string;
  faceBase64: string;
}

Check code and message: an SDK business failure does not necessarily reject the promise. The demo displays feature/image lengths instead of large raw values.

SDK Integration

For another React Native project:

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

iOS

Add the helper to ios/Podfile and call it after React Native's post-install step:

require_relative '../node_modules/@faceaisdk/react-native-face-sdk/scripts/faceaisdk_post_install.rb'
post_install do |installer|
  react_native_post_install(
    installer,
    config[:reactNativePath],
    :mac_catalyst_enabled => false
  )
  faceaisdk_post_install(installer)
end

Add camera usage text to Info.plist, then run pod install:

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

Android

Use minSdkVersion >= 24 and compileSdkVersion >= 34. Add camera permission to android/app/src/main/AndroidManifest.xml:

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

Request camera permission at runtime; see requestCameraPermission in App.tsx. The SDK handles the iOS permission prompt.

Troubleshooting

• SDK unavailable: confirm the dependency is installed, run pod install on

• Debug bundle not loading: confirm Metro is running on port 8765; check the

• Feature/image import fails: configure the demo constants with real data.

Related Demos & Support

iOS · Android · uniApp · Flutter

GitHub Issues · [email protected]