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

$3

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

$3

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

$3

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

Installation

``sh
npm install facetec-react-native-adaptor


or


yarn add facetec-react-native-adaptor
`

$3

1. 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"

2. Add required permissions to Info.plist:
`xml
NSCameraUsageDescription
Camera access is required for facial verification
`

3. Run pod install:
`sh
cd ios && pod install
`

$3

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

`xml


`

Usage

$3

`typescript
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);
}
}
`

$3

`typescript
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

$3

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.

$3

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

Returns: JSON string with the verification result.

$3

Perform enrollment with Photo ID document scanning and face matching.

Returns: JSON string with enrollment result including externalDatabaseRefID.

$3

Authenticate a user against a previous enrollment.

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

Returns: JSON string with authentication result.

$3

Helper function to parse FaceTec response strings.

Returns: Parsed FaceTecResponse object.

Configuration Interface

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

Response Interface

`typescript
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

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

Troubleshooting

$3

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

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

$3

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

2. Multidex issues: Enable multidex in your android/app/build.gradle:
`gradle
android {
defaultConfig {
multiDexEnabled true
}
}
`

$3

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

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

3. "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