Capacitor reference

Every public type in the FacePing Capacitor plugin: setup, enrolment, verification, the camera screen and results.

Package: @faceping/capacitor (npm, preview, under the preview tag). Starter app: faceping/capacitor-starter. Capacitor 8. Android 7 (API 24) or later, on 64-bit phones (arm64-v8a) and x86_64 emulators. iOS 16 or later with Swift Package Manager, or iOS 15.1 or later with CocoaPods (see iOS versions); Xcode 26 or later.

The plugin is a thin bridge over the native Android and iOS SDKs, so the face checks and results behave exactly as they do there. It works in any Capacitor 8 app, whatever the web framework: Ionic, Angular, React, Vue or plain TypeScript. FacePing runs on the phone, not in a web browser: in ionic serve or a desktop browser, every call throws an unavailable error.

Install#

npm install @faceping/capacitor@preview
npx cap sync

Then:

• iOS: add NSCameraUsageDescription to ios/App/App/Info.plist (Xcode: the App target's Info tab, Privacy - Camera Usage Description). Without it, iOS stops the app when the camera starts.
• Android: nothing to add. The FacePing library declares the CAMERA and INTERNET permissions.

iOS versions#

The FacePing iOS SDK needs iOS 15.1 or later.

• Swift Package Manager (the default for new Capacitor 8 apps): Capacitor writes the app's iOS version into its package as a whole number, so iOS 15.1 becomes iOS 15 and the build fails with "requires minimum platform version 15.1". Set the App target's Minimum Deployments to iOS 16.0, then run npx cap sync ios.
• CocoaPods: set the deployment target to 15.1 or later (platform :ios, '15.1' in the Podfile).

How the native SDKs get into your app#

• Android: the plugin depends on ai.faceping:faceping-android from Maven Central. Gradle fetches it like any other dependency.
• iOS, Swift Package Manager: the plugin's package depends on faceping/faceping-ios, a binary Swift package. Xcode downloads the framework from its GitHub release and checks its checksum.
• iOS, CocoaPods: pod install downloads FacePing.xcframework.zip once from the faceping-ios release, checks its SHA-256 against the checksum pinned in the package, and vendors it. Offline or behind a proxy, set FACEPING_IOS_ZIP=/path/to/FacePing.xcframework.zip (checked the same way) or FACEPING_IOS_URL to a mirror before npx cap sync ios.

The simulator has no front camera: test the live check on an iPhone.

Setup#

import { FacePing } from '@faceping/capacitor';

// Once, early. Resolves at once and loads the face models in the background.
await FacePing.init({ sandboxKey: 'fp_test_…' });   // sandbox: faces enrolled on the device
// await FacePing.init({ deviceToken: 'fpd_…' });   // production: faces synced from your check-in list

// Activates the sandbox key now, so a key problem shows up before the first person arrives.
await FacePing.sync();

FacePing is a single object you can call from anywhere in the app. Calling init again with the same options is fine (for example after a live reload); with different options it throws (call close() first). It resolves to { isSandbox, nativeSdkVersion }.

A key in the wrong format throws a setup error from init. A revoked key, or a first run with no connection, shows up on the first call that needs the key, so call sync() at start-up.

Options#

FacePing#

Every call returns a promise.

The camera screen#

A web view can't hold a native camera view, so FacePing brings its own screen. When you call enroll or verify without a photo, or verifyLive, the plugin opens a full-screen native camera over your app, with a title, the oval face guide and a cancel button:

• enroll and verify: the person lines up their face and taps Take photo.
• verifyLive: the check starts at once, with the liveness prompts ("Turn your head left", "Look back at the camera").

When the check is done, the guide turns green or red for a moment and the screen closes itself; then the promise resolves with the result. The screen asks for camera permission the first time it opens. If the person taps Cancel (or Android's back button), the call throws a FacePingError with the code canceled.

const result = await FacePing.verifyLive(ticketId, {
  title: 'Look at the camera to check in',
  cancelLabel: 'Use my ticket instead',
});

Only one camera screen can be open at a time: a second call while one is open throws invalidOperation.

To translate or reword the liveness prompts, use the native SDKs' strings: on Android the string resources faceping_prompt_look_at_camera, faceping_prompt_turn_left, faceping_prompt_turn_right and faceping_prompt_look_back; on iOS a FacePing.strings table with the keys faceping.prompt.lookAtCamera, faceping.prompt.turnLeft, faceping.prompt.turnRight and faceping.prompt.lookBack.

Photos#

A photo is any of:

Photos are turned upright from their EXIF orientation and scaled down to 1280 pixels on the device before anything else happens.

Backups#

The face store's encryption keys stay in the phone's Keychain or Keystore. On iOS, FacePing's folder is already excluded from backups. On Android, exclude files/faceping and the shared preferences faceping.keys from Auto Backup, or turn backup off (android:allowBackup="false" in android/app/src/main/AndroidManifest.xml).

Results#

type EnrollResult = {
  outcome: 'enrolled' | 'noFace' | 'multipleFaces' | 'faceTooSmall' | 'notLive' | 'limitReached';
  id: string;
  isEnrolled: boolean;
};

type VerifyResult = {
  outcome: 'match' | 'noMatch' | 'notEnrolled' | 'noFace' | 'livenessFailed'
         | 'challengeFailed' | 'expired' | 'leaseExpired';
  similarity: number;           // cosine similarity; the match threshold is 0.363
  livenessScore: number | null; // passive liveness of the deciding frame
  elapsedMs: number;            // how long the check took on the device
  isSandbox: boolean;
  isMatch: boolean;
};

type SyncResult = {
  status: 'ok' | 'gone' | 'revoked' | 'unavailable';
  enrolled: number;
  leaseUntil: Date | null;      // production: verifies offline until then
  deleteAfter: Date | null;
};

The outcome types are exported as EnrollOutcome and VerifyOutcome. limitReached means the sandbox already holds 25 faces on this device: forget one first. leaseExpired (production) means the device hasn't synced for longer than its lease, 24 hours by default; it needs a connection before it verifies again.

Errors#

Set-up and device problems throw a FacePingError with a message ready to show and a code. isFacePingError(e, 'canceled') checks for one.

Everything else is a result, not an exception: a face check never throws because someone looked away.