🌐 Company Site - Here
🤗 Hugging Face - Here
🛟 Help Center - Here
🐳 Docker Hub - Here
Ready in ~15 minutes (after runtime download): Drop Android AAR + iOS frameworks → Run the example on a phone Jump: Quick start · Get the runtimes · Run the demo · Integrate into your app · JS API
Customer repo name: FaceRecognition-React-Native
Use this for the example app (check each box in order):
- Clone repo and run
yarn(root) +yarn(example/) - Download runtimes from Google Drive
- Android: copy
facerecognitionsdk.aar→example/android/libfacesdk/ - iOS: unzip frameworks →
ios/Frameworks/(facerecognitionsdk,FaceRecognitionEngine,onnxruntime) - iOS:
cd example && bundle install && cd ios && pod install - Terminal 1:
cd example && yarn start - Terminal 2:
cd example && yarn ios --device(oryarn android) - Home screen status bar shows Ready → Enroll / Identify / Capture / Attribute
Integrating into your own app? Skip to Integrate into your own app — Android AAR path is different (
node_modules/.../android/libs/).
Explore FacePlugin Face Recognition SDK for React Native — enroll, 1:N identify with VideoWorker, oval capture coach, and face attributes with 2D liveness. The npm package face-recognition-sdk wraps the same native engines as our FaceRecognitionSDK Android and iOS apps.
This is an on-premise FacePlugin SDK. All processing stays on the device — no biometric data is sent to FacePlugin cloud.
This repository contains:
| Folder | Purpose |
|---|---|
| Repository root | face-recognition-sdk — the React Native library you install in your app |
example/ |
Full demo (Enroll, Identify, Capture, Attribute, Settings, About) |
Native binaries are not on GitHub (too large). Download them from Google Drive (links below) and copy into the paths shown.
Expo Go is not supported. You need a development build (bare React Native or Expo prebuild) because this package includes native Android / iOS code.
| Feature | Supported |
|---|---|
| Gallery enroll (single face) | ✓ |
| Live 1:N identify (VideoWorker) | ✓ |
| 2D liveness gate on identify | ✓ |
| Oval capture coach + enroll | ✓ |
| Gallery attributes + landmarks | ✓ |
| Local person database | ✓ |
| Settings (thresholds / clear DB) | ✓ |
| Platform | Repository |
|---|---|
| Android | FaceRecognition-Android |
| iOS | FaceRecognition-iOS |
| React Native | FaceRecognition-React-Native (this repo) |
| Windows | FaceRecognition-Windows |
| Linux / Docker | FaceRecognition-Linux |
| Step | What you need |
|---|---|
| 1 | Node.js 18+, Yarn, React Native environment (setup guide) |
| 2 | Physical device recommended (camera / liveness; emulator is limited) |
| 3 | Android facerecognitionsdk.aar and iOS frameworks — see Get the runtimes |
| 4 | Demo licenses are in example/src/license.ts (bound to com.faceplugin.facerecognitionsdk). Request a new key only if you change applicationId / bundle id — see SDK License |
You can run the example app as-is after placing the runtimes. Home tiles unlock when the status bar shows Ready.
| Platform | Requirement |
|---|---|
| React Native | 0.74.x (example ships 0.74.5) |
| Android | minSdk 24, physical device recommended |
| iOS | iOS 13+, A12+ recommended, physical device |
| Node | 18+ |
Same Google Drive packs as FaceRecognitionSDK Android / iOS (includes frc.fpk models inside the runtime).
| File | Example path | Customer path (your app) |
|---|---|---|
facerecognitionsdk.aar |
example/android/libfacesdk/facerecognitionsdk.aar |
node_modules/face-recognition-sdk/android/libs/facerecognitionsdk.aar |
Unzip into ios/Frameworks/:
| Archive | Place at |
|---|---|
facerecognitionsdk.framework.zip |
ios/Frameworks/facerecognitionsdk.framework |
FaceRecognitionEngine.framework.zip |
ios/Frameworks/FaceRecognitionEngine.framework |
onnxruntime.framework.zip |
ios/Frameworks/onnxruntime.framework |
Then run pod install in example/ios.
Person enrollment data is local (
AsyncStoragein the example). Drive holds the native runtime only, not the enrolled person gallery.
yarn
cd example && yarn
# place AAR + frameworks (see above)
cd ios && pod install && cd ..
yarn start
# other terminal:
yarn android
# or
yarn ios --device- Wait until the home status bar shows Ready
- ENROLL — pick a gallery photo with exactly one face
- IDENTIFY — live camera 1:N + liveness → result
- CAPTURE — oval coach → optional enroll
- ATTRIBUTE — gallery → landmarks + attributes
- SETTINGS — thresholds, clear persons
- ABOUT
| Home | Identify | Capture |
|---|---|---|
|
|
|
| Capture result | Attribute | Attribute (emotion) |
|---|---|---|
|
|
|
| Attribute (quality) | Settings | About |
|---|---|---|
|
|
|
| Home (tiles) | Attribute (liveness) |
|---|---|
|
|
Licenses are offline and bound to your app identifier.
The sample app already includes a valid key for com.faceplugin.facerecognitionsdk (Android applicationId and iOS bundle id). You only need a new key if you use a different id.
The code below shows how to use the license:
FaceRecognition-React-Native/example/src/license.ts
Lines 11 to 18 in 2fbb291
FaceRecognition-React-Native/example/src/SdkContext.tsx
Lines 60 to 75 in 2fbb291
Please contact us to get the license.
yarn add github:Faceplugin-ltd/FaceRecognition-React-Native
# or npm / private git URL for face-recognition-sdk- Copy
facerecognitionsdk.aarintonode_modules/face-recognition-sdk/android/libs/ - Copy the three iOS frameworks into
node_modules/face-recognition-sdk/ios/Frameworks/andpod install - Activate + init before calling detect / VideoWorker APIs
- For Capture UI (
FaceCapture), also install peers:react-native-vision-camera,react-native-svg(and camera permissions)
import {
setActivation,
init,
faceDetection,
templateExtraction,
SDK_SUCCESS,
} from 'face-recognition-sdk';
const code = await setActivation('FP1.…');
if (code === SDK_SUCCESS) {
await init();
}After yarn install, re-copy the AAR/frameworks if node_modules was wiped (or add a postinstall script).
Fully on-device face recognition for React Native — no cloud round-trip. One TypeScript API for Android and iOS; results use the same FaceBox shape on both platforms (Android is normalized for you).
| You want to… | Use |
|---|---|
| Know if a selfie is a real person | faceDetection + livenessLabel |
| Enroll Alice, then recognize her later | templateExtraction + similarity |
| Show age / emotion / glasses on a result screen | face.attributes |
| Live 1:N match from the camera | startVideoWorker + addVideoWorkerListener |
All methods return Promises. Status 0 (SDK_SUCCESS) means activate / init succeeded.
Typical KYC / door-access flow in ~15 lines:
import {
setActivation,
init,
faceDetection,
templateExtraction,
similarity,
cropFace,
SDK_SUCCESS,
} from 'face-recognition-sdk';
async function checkPerson(selfieUri: string, enrolledTemplateB64: string) {
await setActivation('FP1.…'); // your offline license
if ((await init()) !== SDK_SUCCESS) {
throw new Error('Engine failed to load');
}
const faces = await faceDetection(selfieUri, {
allAttributes: true,
check_liveness: true,
check_liveness_level: 0, // accurate 2D liveness
});
if (!faces.length) return { ok: false, reason: 'No face found' };
const face = faces[0];
const live = (face.livenessLabel ?? '').toLowerCase();
if (live.includes('spoof') || live.includes('fake')) {
return { ok: false, reason: 'Spoof detected', face };
}
const probe = await templateExtraction(selfieUri, face);
const score = await similarity(probe, enrolledTemplateB64); // 0…1
const thumbB64 = await cropFace(selfieUri, face); // JPEG for your UI
return {
ok: score >= 0.8,
score,
age: face.age,
gender: face.genderLabel,
emotion: face.emotionLabel,
liveness: face.livenessLabel,
attributes: face.attributes, // full map, same on iOS & Android
thumbB64,
};
}What you get back (same keys on Android and iOS):
{
ok: true,
score: 0.93,
age: 34,
gender: 'Male',
emotion: 'Neutral',
liveness: 'Real · 96%',
attributes: {
Liveness2D: 'Real · 96%',
Gender: 'Male · 99%',
Emotion: 'Neutral · 88%',
Glasses: 'No',
// …plus Lighting, Sharpness, … when the engine returns them
}
}// --- Enroll (gallery or capture) ---
const [face] = await faceDetection(photoUri, { allAttributes: true });
const template = await templateExtraction(photoUri, face);
await saveToYourDb({ name: 'Alice', template }); // your storage
// --- Identify later ---
const [probeFace] = await faceDetection(newSelfieUri, {
check_liveness: true,
check_liveness_level: 0,
});
const probe = await templateExtraction(newSelfieUri, probeFace);
let best = { name: '', score: 0 };
for (const person of await loadYourDb()) {
const score = await similarity(probe, person.template);
if (score > best.score) best = { name: person.name, score };
}
if (best.score >= 0.8) {
console.log(`Welcome, ${best.name} (${Math.round(best.score * 100)}%)`);
}Push enrolled templates, feed camera frames, listen for matches. Orientation /
front-sensor quirks are handled inside ingestLiveCameraFrame — same on
Android and iOS.
import {
startVideoWorker,
syncVideoWorkerDatabase,
ingestLiveCameraFrame,
addVideoWorkerListener,
stopVideoWorker,
} from 'face-recognition-sdk';
await startVideoWorker({ matchThreshold: 0.67 });
await syncVideoWorkerDatabase(
enrolledPeople.map((p) => p.template),
0.67
);
const sub = addVideoWorkerListener((json) => {
const ev = JSON.parse(json);
if (ev.event === 'match') {
console.log('Matched!', ev.match);
}
});
// Beginner — pass the VisionCamera snapshot + which lens you used:
const photo = await camera.takeSnapshot({ quality: 85 });
await ingestLiveCameraFrame(photo, { frontCamera: true });
// Also OK — URI only:
// await ingestLiveCameraFrame(uri, { frontCamera: true });
sub.remove();
await stopVideoWorker();Full camera + overlay wiring is in example/src/screens/IdentifyScreen.tsx.
Skip rebuilding the oval guide / VideoWorker / eye-pose state machine. Import the Capture component from the /capture entry (requires react-native-vision-camera + react-native-svg):
import { FaceCapture } from 'face-recognition-sdk/capture';
import type { CaptureSettings } from 'face-recognition-sdk/capture';
const settings: CaptureSettings = {
camera_lens: 'front',
liveness_threshold: 0.5,
liveness_level: 0,
yaw_threshold: 40,
roll_threshold: 40,
pitch_threshold: 40,
eyeclose_threshold: 0.5,
};
<FaceCapture
settings={settings}
onCancel={() => navigation.goBack()}
onCaptured={(result) => {
// result.uri, result.faceBox, result.cropB64
}}
renderActions={(result) => (
<Button title="Enroll" onPress={() => enroll(result)} />
)}
/>Still-image-only apps can keep using face-recognition-sdk without installing VisionCamera.
| Field | Example use |
|---|---|
x1,y1,x2,y2 |
Draw the cyan box on the preview |
liveness / livenessLabel |
Gate “continue” on Real vs Spoof |
age, genderLabel, emotionLabel |
Person card on the result screen |
glassesLabel, maskLabel, occlusionLabel |
Compliance / quality warnings |
attributes |
Rich “Attribute” UI (PascalCase → "value · NN%") |
landmarks |
Flat [x0,y0,x1,y1,…] for landmark dots |
faceDetection() always returns this canonical shape. Optional: normalizeFaceBox / normalizeFaceBoxes if you parse raw bridge JSON yourself.
image may be a file/content URI or base64 / data: URL.
Useful params: allAttributes, check_liveness, check_liveness_level (0 = accurate), check_eye_closeness, check_face_occlusion, estimate_age_gender, check_emotion, check_mask, check_glasses, …
Flags / landmark modes: DETECT_*, LANDMARK_MODE_14 / 68 / 468.
| Method | Role |
|---|---|
getMachineCode / setActivation / init / deinit |
License + engine lifecycle |
faceDetection / detect |
Faces + attributes (faceDetection = normalized array) |
templateExtraction / similarity / cropFace |
Enroll / match / thumbnail |
startVideoWorker / syncVideoWorkerDatabase / ingestLiveCameraFrame / addVideoWorkerListener / stopVideoWorker |
Live 1:N (ingestLiveCameraFrame(photo, { frontCamera }) hides orientation) |
FaceCapture (from face-recognition-sdk/capture) |
Ready-made Capture UI (oval + gates); optional peers VisionCamera + SVG |
lastLicenseError |
Human-readable license failure |
| Issue | Fix |
|---|---|
| Missing AAR | Copy facerecognitionsdk.aar to example/android/libfacesdk/ |
| Missing iOS frameworks | Unzip all three frameworks under ios/Frameworks/ then pod install |
| License invalid | Confirm applicationId / bundle id is com.faceplugin.facerecognitionsdk or request a new key |
| Expo Go | Not supported — use a bare / prebuild binary |
| Identify never matches | Enroll at least one person; check identify threshold in Settings |
| Identify only works with an upside-down / reversed face | Use ingestLiveCameraFrame(photo, { frontCamera }) (not a raw frame without prep). Android + iOS share one JS orientation policy. |
- Face Recognition with Liveness Detection-Android (Java, Kotlin)
- Face Recognition with Liveness Detection-iOS (Objective C, Swift)
- Face Recognition with Liveness Detection-Windows
- Face Recognition with Liveness Detection-React Native
- Face Recognition with Liveness Detection-Flutter
- Face Recognition with Liveness Detection-Ionic Cordova
- Face Recognition with Liveness Detection-.Net MAUI
- Face Recognition with Liveness Detection-.Net WPF
- Face Recognition with Liveness Detection-Javascript
- Face Recognition with LivenessDetection-React
- Face Recognition with LivenessDetection-Vue
- Face Liveness Detection-Android (Java, Kotlin)
- Face Liveness Detection-iOS (Objective C, Swift)
- Face Liveness Detection-Windows
- Face Liveness Detection-Linux
- Face Liveness Detection-Docker
- Open Source Face Recognition SDK
- Face Recognition SDK
- Liveness Detection SDK
- Palm Recognition SDK
- ID Document Recognition-Android (Java, Kotlin)
- ID Document Recognition-Windows
- ID Document Recognition
- ID Document Liveness Detection
