@surtai/faceguard-rn

Official React Native SDK for FaceGuard — biometric face verification embedded in your app via a secure WebView.

Installation

npm install @surtai/faceguard-rn react-native-webview

iOS

cd ios && pod install

Add to Info.plist:

<key>NSCameraUsageDescription</key>
<string>Required for face verification</string>

Android

Add to AndroidManifest.xml:

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

Setup

Wrap your app root with FaceGuardProvider:

import { FaceGuardProvider } from '@surtai/faceguard-rn';

export default function App() {
  return (
    <FaceGuardProvider>
      {/* rest of your app */}
    </FaceGuardProvider>
  );
}

Usage

Promise-based (simplest)

import { FaceGuard } from '@surtai/faceguard-rn';

const result = await FaceGuard.verify({ token: 'PORTAL_TOKEN' });

switch (result.status) {
  case 'approved':
    console.log('Verified', result.confidence);
    break;
  case 'rejected':
    console.log('Failed', result.confidence);
    break;
  case 'canceled':
    console.log('User canceled');
    break;
  case 'error':
    console.log('Error', result.error);
    break;
}

Callback-based

const session = FaceGuard.init({
  token: 'PORTAL_TOKEN',
  onSuccess: (r) => console.log('approved', r.confidence),
  onFailed:  (r) => console.log('rejected', r.confidence),
  onCancel:  ()  => console.log('canceled'),
  onError:   (e) => console.log('error', e.message),
});

// Close programmatically if needed:
session.destroy();

Declarative component

Render the verification UI inside your own container or modal:

import { FaceGuardView } from '@surtai/faceguard-rn';
import { Modal } from 'react-native';

<Modal visible={isOpen} onRequestClose={() => setIsOpen(false)}>
  <FaceGuardView
    token="PORTAL_TOKEN"
    style={{ flex: 1 }}
    onSuccess={() => setIsOpen(false)}
    onCancel={() => setIsOpen(false)}
  />
</Modal>

Options

| Prop | Type | Required | Description | |------|------|:--------:|-------------| | token | string | ✓ | Portal JWT token issued by your backend | | baseUrl | string | | Override the verification endpoint (default: https://faceguard.surt.com) | | lang | string | | UI language: en, es, pt, de | | onReady | () => void | | Fired when the WebView finishes loading | | onSuccess | (r: { confidence: number }) => void | | Face matched successfully | | onFailed | (r: { confidence: number }) => void | | Face did not match | | onCancel | () => void | | User dismissed the flow | | onError | (e: { message: string }) => void | | Verification error |

Peer Dependencies

| Package | Version | |---------|---------| | react | >= 18 | | react-native | >= 0.73 | | react-native-webview | >= 11 |

Notes

• One session at a time — concurrent init() calls are queued; only one modal displays at a time.
• One-shot per token — the backend closes the session after the first attempt. If the user fails, your backend must issue a new portal token for a retry.
• Custom environments — pass baseUrl to target staging or local dev (e.g. an ngrok tunnel).

License

Apache-2.0