@scripturecoder/rn-liveness

A plug-and-play face liveness detection module for React Native. Verifies a user is physically present by walking them through a series of face-detection steps (center, blink, open mouth, head turn) using the device's front camera.

Installation

yarn add @scripturecoder/rn-liveness

Peer Dependencies

Install the required peer dependencies in the consuming project:

yarn add [email protected] \
         react-native-vision-camera-face-detector@^1.9.1 \
         [email protected] \
         react-native-reanimated@^4.1.3 \
         [email protected] \
         react-native-blob-util@^0.23.2 \
         react-native-svg@^15.14.0 \
         @vokhuyet/react-native-concurrent-sound@^0.1.2

Required Native Configuration

1. Android — android/app/build.gradle

react-native-compressor bundles native audio encoder libraries that conflict with other packages. Add the following packagingOptions block inside the android { ... } section:

android {
    // ...
    packagingOptions {
        exclude 'lib/x86_64/libandroidlame.so'
        exclude 'lib/arm64-v8a/libandroidlame.so'
        exclude 'lib/armeabi-v7a/libandroidlame.so'
        exclude 'lib/x86/libandroidlame.so'
    }
}

Without this, your Android build will fail with a duplicate .so file error.

2. Android — react-native-worklets-core patch

[email protected] requires a patch to build correctly against React Native 0.82+. This package ships the patch file in patches/. You need patch-package installed and a postinstall script in your project to apply it:

// package.json (consuming project)
{
  "scripts": {
    "postinstall": "patch-package"
  },
  "dependencies": {
    "patch-package": "^8.0.1",
    "postinstall-postinstall": "^2.1.0"
  }
}

Then copy the patch into your project root's patches/ directory:

mkdir -p patches && cp node_modules/@scripturecoder/rn-liveness/patches/react-native-worklets-core+1.6.2.patch patches/

3. iOS — Camera Permission

Add to ios/YourApp/Info.plist:

<key>NSCameraUsageDescription</key>
<string>Camera is required for face verification.</string>

Usage

import Liveness from '@scripturecoder/rn-liveness';

<Liveness
  bvn="12345678901"
  apiKey="your-api-key"
  txId="unique-transaction-id"
  logo={<YourLogo />}
  onSuccess={(data) => console.log('Verified', data)}
/>

Props

| Prop | Type | Required | Description | |---------------|-------------------------------|----------|-------------------------------------------------------| | bvn | string | ✅ | User's BVN for identity matching | | apiKey | string | ✅ | API key for the liveness verification service | | txId | string | ✅ | Unique transaction ID for this verification | | onSuccess | (data: BvnDetails) => void | ✅ | Called with verified identity data on success | | baseUrl | string | ❌ | Override the API base URL (must be https://). | | stepsConfig | LivenessSteps | ❌ | Enable or disable optional liveness steps (see below) | | logo | React.ReactNode | ❌ | Optional logo shown at the top of the camera UI | | colors | LivenessColors | ❌ | Theme overrides (see below) |

stepsConfig prop

Controls which optional liveness steps are active. All steps are enabled by default. Set a step to false to skip it.

type LivenessSteps = {
  blink?: boolean;  // default: true
  mouth?: boolean;  // default: true
  head?:  boolean;  // default: true
};

Examples:

// Skip the head turn step
<Liveness stepsConfig={{ head: false }} />

// Only run center alignment (no optional steps)
<Liveness stepsConfig={{ blink: false, mouth: false, head: false }} />

// Run blink and mouth only
<Liveness stepsConfig={{ head: false }} />

onSuccess callback

type BvnDetails = {
  first_name: string;
  last_name: string;
  [key: string]: unknown;
};

colors prop

type LivenessColors = {
  background?: string;
  text?: string;
  shade?: string;
  primary?: string;
};

How It Works

The module walks the user through a series of steps detected via the front camera in real time:

1. Center (always active) — Align face within the guide frame
2. Blink (optional) — Detect eye closure
3. Open Mouth (optional) — Detect open mouth via facial contours
4. Head Turn (optional) — Detect a head movement (yaw or roll)

A photo is captured at each successful step and submitted for server-side verification. Captured images are deleted from device storage immediately after upload.