facetec-react-native-adaptor

facetec-react-native-adaptor

React Native bridge for FaceTec SDK - Biometric facial verification for iOS and Android.

Features

• Liveness Detection: Anti-spoofing verification to ensure a real person is present
• Photo ID Match: Enrollment with ID document scanning and face matching
• Authentication: 3D-3D face match against previously enrolled users
• Full Platform Support: Works on both iOS and Android
• Configurable: Pass your own FaceTec credentials at runtime

Requirements

General

• React Native >= 0.68.0
• FaceTec SDK license and credentials (obtain from FaceTec Developer Portal)

iOS

• iOS 12.0+
• Xcode 14+
• FaceTec.xcframework (must be added manually)

Android

• minSdkVersion 21
• compileSdkVersion 33+
• FaceTec SDK AAR file (included in the package)

Installation

npm install facetec-react-native-adaptor
# or
yarn add facetec-react-native-adaptor

iOS Setup

• Add FaceTec.xcframework to your iOS project:

  • Download FaceTec SDK from your FaceTec developer account
  • Drag FaceTec.xcframework into your Xcode project
  • Ensure it's added to "Frameworks, Libraries, and Embedded Content" with "Embed & Sign"

• Add required permissions to Info.plist:

<key>NSCameraUsageDescription</key>
<string>Camera access is required for facial verification</string>

• Run pod install:

cd ios && pod install

Android Setup

The FaceTec SDK AAR is already included in the package. Just add required permissions to AndroidManifest.xml:

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

Usage

Basic Example

import { init, liveness, photoMatch, authenticate, parseResponse, FaceTecConfig } from 'facetec-react-native-adaptor';

// Configure with your FaceTec credentials
const config: FaceTecConfig = {
  deviceKeyIdentifier: 'YOUR_DEVICE_KEY_IDENTIFIER',
  appKey: 'YOUR_APP_KEY',
  baseURL: 'https://your-facetec-server.com',
  publicFaceScanEncryptionKey: '-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----',
  productionMode: false, // Set to true for production
  language: 'es', // 'es' for Spanish, 'en' for English
  primaryColor: '#417FB2', // Color for text and UI elements
  logoURL: 'https://example.com/your-logo.png', // Optional logo URL
};

// Initialize the SDK (call once at app startup)
async function initializeFaceTec() {
  try {
    const success = await init(config);
    console.log('FaceTec initialized:', success);
  } catch (error) {
    console.error('Failed to initialize FaceTec:', error);
  }
}

// Perform liveness check
async function checkLiveness() {
  try {
    const result = await liveness();
    const response = parseResponse(result);

    if (response.wasProcessed) {
      console.log('Liveness verified!');
    }
  } catch (error) {
    console.error('Liveness check failed:', error);
  }
}

// Enroll user with Photo ID
async function enrollUser() {
  try {
    const result = await photoMatch();
    const response = parseResponse(result);

    if (response.wasProcessed) {
      // Save externalDatabaseRefID for future authentication
      const userId = response.externalDatabaseRefID;
      console.log('User enrolled with ID:', userId);
    }
  } catch (error) {
    console.error('Enrollment failed:', error);
  }
}

// Authenticate existing user
async function authenticateUser(userId: string) {
  try {
    const result = await authenticate(userId);
    const response = parseResponse(result);

    if (response.wasProcessed) {
      console.log('User authenticated successfully!');
    }
  } catch (error) {
    console.error('Authentication failed:', error);
  }
}

Using Default Export

import FaceTec, { FaceTecConfig } from 'facetec-react-native-adaptor';

const config: FaceTecConfig = {
  deviceKeyIdentifier: 'YOUR_DEVICE_KEY',
  appKey: 'YOUR_APP_KEY',
  baseURL: 'https://your-server.com',
  publicFaceScanEncryptionKey: '...',
  productionMode: false,
};

// Initialize
await FaceTec.init(config);

// Check liveness
const livenessResult = await FaceTec.liveness();

// Enroll with Photo ID
const enrollResult = await FaceTec.photoMatch();

// Authenticate
const authResult = await FaceTec.authenticate('user-reference-id');

API Reference

init(config: FaceTecConfig): Promise<boolean>

Initialize the FaceTec SDK with your configuration. Must be called before any other methods.

Parameters:

• config.deviceKeyIdentifier: Your FaceTec Device Key Identifier
• config.appKey: Your FaceTec App Key (Production Key)
• config.baseURL: URL of your FaceTec Server SDK backend
• config.publicFaceScanEncryptionKey: Your FaceTec Public Encryption Key
• config.productionMode: (optional) Set to true for production mode, defaults to false
• config.language: (optional) UI language - 'es' for Spanish, 'en' for English, defaults to 'en'
• config.primaryColor: (optional) Hex color for text and UI elements, defaults to '#417FB2'
• config.logoURL: (optional) URL to your logo image to display in the FaceTec UI

Returns: true if initialization was successful.

liveness(): Promise<string>

Perform a liveness check to verify a real person is present.

Returns: JSON string with the verification result.

photoMatch(): Promise<string>

Perform enrollment with Photo ID document scanning and face matching.

Returns: JSON string with enrollment result including externalDatabaseRefID.

authenticate(externalReferenceId: string): Promise<string>

Authenticate a user against a previous enrollment.

Parameters:

• externalReferenceId: The ID returned from a previous photoMatch() call.

Returns: JSON string with authentication result.

parseResponse(responseString: string): FaceTecResponse

Helper function to parse FaceTec response strings.

Returns: Parsed FaceTecResponse object.

Configuration Interface

interface FaceTecConfig {
  deviceKeyIdentifier: string;
  appKey: string;
  baseURL: string;
  publicFaceScanEncryptionKey: string;
  productionMode?: boolean;
  language?: 'es' | 'en';
  primaryColor?: string;
  logoURL?: string;
}

Response Interface

interface FaceTecResponse {
  wasProcessed: boolean;
  success?: boolean;
  scanResultBlob?: string;
  externalDatabaseRefID?: string;
  [key: string]: any;
}

Server Requirements

This SDK requires a FaceTec Server SDK backend to process the biometric data. Your server must implement the following endpoints:

• GET /session-token - Returns a session token
• POST /liveness-3d - Process liveness check
• POST /enrollment-3d - Process enrollment
• POST /match-3d-2d-idscan - Process Photo ID match
• POST /match-3d-3d - Process authentication

Refer to the FaceTec Server SDK documentation for implementation details.

Obtaining FaceTec Credentials

• Sign up at FaceTec Developer Portal
• Create a new application
• Obtain your:
  • Device Key Identifier
  • App Key (Production Key)
  • Public Face Scan Encryption Key
• Set up your FaceTec Server SDK backend

Troubleshooting

iOS Build Issues

• FaceTec module not found: Ensure FaceTec.xcframework is properly added to your Xcode project.

• Bridging header issues: Verify the bridging header path in your project's Build Settings.

Android Build Issues

• SDK not found: The AAR is included in the package. Make sure your build.gradle is configured correctly.

• Multidex issues: Enable multidex in your android/app/build.gradle:

android {
    defaultConfig {
        multiDexEnabled true
    }
}

Runtime Issues

• Initialization fails: Verify your credentials are correct and match your FaceTec account.

• Network errors: Ensure your baseURL is correct and the server is accessible.

• "SDK not initialized" errors: Make sure to call init() before using other methods.

License

MIT

Contributing

See the contributing guide to learn how to contribute to the repository.

Support

For FaceTec SDK support, visit FaceTec Support.

Made with create-react-native-library