Ionic Capacitor

Faceplugin Face Recognition Ionic Capacitor SDK. On-premise face matching and liveness. face-recognition-capacitor plugin for new Ionic apps.

Fully on-premise Face Recognition SDK for Ionic Capacitor. Package: face-recognition-capacitor. Use this for new Ionic apps. Cordova is a different repo.

ionic serve / the browser cannot load the engine. Open Android Studio or Xcode and run on a physical phone.

Code

GitHub - Faceplugin-ltd/FaceRecognition-Ionic-Capacitor: Face Recognition & Liveness SDK for Ionic Capacitor with face detection, face matching, 1:N identification, face landmarks and attributes. On-device Android & iOS.GitHub

How to run

1

Install tools

Node 18+, JDK 17, Android Studio and/or Xcode 15+. Physical phone with USB debugging.

2

Clone, install, build the plugin

git clone https://github.com/Faceplugin-ltd/FaceRecognition-Ionic-Capacitor.git
cd FaceRecognition-Ionic-Capacitor
npm install
npm run build
cd example && npm install

3

Place native runtimes

Platform	File	Example app path	Your own app path
Android	facerecognitionsdk.aar	example/android/libfacesdk/	node_modules/face-recognition-capacitor/android/libs/
iOS	three frameworks	ios/Frameworks/	node_modules/face-recognition-capacitor/ios/Frameworks/

• Android Google Drive: facerecognitionsdk.aar

• iOS Google Drive: frameworks (facerecognitionsdk, FaceRecognitionEngine, onnxruntime)

4

Sync and run

cd example
npm run build
npx cap sync
npx cap open android

Or npx cap open ios. Wait for the home status bar → Ready.

Keep demo ids so the included license works:

Platform	Id
Android package name	com.faceplugin.facerecognitionsdk
iOS bundle identifier	com.faceplugin.facerecognitionsdk

Demo tiles: Enroll, Identify, Capture, Attribute, Settings, About.

License

Licenses are offline. The sample key is only for the demo app. Request a new license key for your own app. Request a License & Support.

Default thresholds in Settings: identify 0.67, liveness 0.5, pose 40°, eye-close 0.5.

Integrate into your own app

npm install git+https://github.com/Faceplugin-ltd/FaceRecognition-Ionic-Capacitor.git
npx cap sync

Copy runtimes into node_modules/face-recognition-capacitor/... as in the table above. Set your appId in capacitor.config.ts. Add camera + photo-library permissions.

import {
  getMachineCode,
  setActivation,
  init,
  lastLicenseError,
  faceDetection,
  templateExtraction,
  cropFace,
  SDK_SUCCESS,
} from 'face-recognition-capacitor';

async function activate() {
  const mc = await getMachineCode(); // machine code — send when requesting a key
  const act = await setActivation('license key');
  if (act !== SDK_SUCCESS) throw new Error(await lastLicenseError());
  const initCode = await init();
  if (initCode !== SDK_SUCCESS) throw new Error(`init failed: ${initCode}`);
}

async function enrollStill(imageUri: string) {
  const faces = await faceDetection(imageUri);
  if (faces.length !== 1) return;
  const template = await templateExtraction(imageUri, faces[0]);
  const cropB64 = await cropFace(imageUri, faces[0]);
  // Store template + crop in YOUR database
}

APIs

Call order: getMachineCode → setActivation → init → detect / VideoWorker → deinit.

Status codes: 0 Success, 1 Invalid license, 2 Expired, 3 Not activated, 4 Init failed.

setActivation: This API is used to activate the SDK

setActivation(license: string): Promise<number>

init: This API is used to initialize the SDK

init(): Promise<number>

getMachineCode: This API is used to retrieve the machine code

getMachineCode(): Promise<string>

faceDetection: This API is used to detect faces

faceDetection(image: ImageInput, param?: FaceDetectionParam): Promise<FaceBox[]>

FaceBox includes geometry (x1,y1,x2,y2), pose, liveness / quality / eyes / occlusion, age / gender / emotion / mask / glasses, landmarks, landmarkCount.

templateExtraction: This API is used to extract face template

templateExtraction(image: ImageInput, faceBox: FaceBox): Promise<string>

similarity: This API is used to calculate similarity between two templates

similarity(feature1: string, feature2: string): Promise<number>

Also: getLicenseStatus, detect(image, crop?, flags?), extractFeature, quality, cropFace, lastLicenseError.

VideoWorker: This API is used for live 1:N identify

startVideoWorker(config?: VideoWorkerConfig): Promise<number>
syncVideoWorkerDatabase(featuresB64: string[], matchThreshold?: number): Promise<number>
startLivePreview() / takeLiveSnapshot() / ingestLiveCameraFrame(...)
subscribeVideoWorker(listener)
stopVideoWorker()

Optional session helpers in the example: IdentifySession, CaptureSession.

Request a License & Support · Contact us

FAQ

Package? face-recognition-capacitor. Prefer Capacitor over Cordova for new Ionic apps.

Offline? Yes after setActivation / init with a license key for your app id.

Related documentation

• Faceplugin Face Recognition Mobile SDK · Ionic Cordova · Glossary

• ID Document Recognition Ionic Capacitor SDK

• Request a License · Status codes

• Combining products (eKYC) · SDK comparison