React Native Biometric Verifier

A beginner-friendly React Native package for biometric verification with camera-based face recognition, optional QR-based location validation, and liveness checks.

This component is built so any React Native app can securely verify a user by combining:

• Face scan
• GPS location check
• QR metadata validation
• Liveness / anti-spoof detection

✅ What this package does

• Opens a verification modal with camera preview.
• Detects and captures a single face using the front camera.
• Optionally scans a QR code first to validate location.
• Uses GPS to confirm the user is within a valid radius.
• Sends face image data to a backend API for recognition.
• Displays status messages, countdown timer, and success/error feedback.

🔧 Features

• Face recognition workflow
• QR-based location verification
• Distance check using GPS coordinates
• Liveness and anti-spoof checks
• Countdown timer for verification sessions
• Animated notifications and progress state

🚀 Installation

npm install react-native-biometric-verifier

Required peer dependencies

npm install react-native-vector-icons react-native-geolocation-service react-native-image-resizer react-native-fs prop-types

The package also depends on native camera and vision packages internally. Make sure your app is configured for camera access.

📱 Platform setup

iOS

Add these keys to Info.plist:

<key>NSCameraUsageDescription</key>
<string>We need access to your camera for biometric verification.</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>We need your location to verify your presence at the designated area.</string>

Android

Add these permissions to AndroidManifest.xml:

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

📘 Basic Usage

import React, { useState } from 'react';
import { View, Button } from 'react-native';
import BiometricModal from 'react-native-biometric-verifier';
 
const App = ({ navigation }) => {
  const [isVerifierOpen, setIsVerifierOpen] = useState(false);
 
  const handleVerificationComplete = (result) => {
    console.log('Verification successful:', result);
    setIsVerifierOpen(false);
  };
 
  return (
    <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
      <Button title="Start Verification" onPress={() => setIsVerifierOpen(true)} />
 
      {isVerifierOpen && (
        <BiometricModal
          data="USER_UNIQUE_ID"
          apiurl="https://your-api-endpoint.com/"
          navigation={navigation}
          onclose={(open) => setIsVerifierOpen(open)}
          callback={handleVerificationComplete}
          qrscan={false}
          duration={100}
          MaxDistanceMeters={30}
          frameProcessorFps={5}
          livenessLevel={1}
          antispooflevel={0.35}
        />
      )}
    </View>
  );
};
 
export default App;

navigation is required because the component may call navigation.goBack() when the verification timer expires.

🧠 How the verification flow works

The component supports two main flows:

1. Face verification only (qrscan={false})
   • Open the front camera.
   • Detect a single centered face.
   • Optionally perform liveness checks.
   • Capture the face image.
   • Send the image to the backend API.
2. QR + face verification (qrscan={true})
   • Open the back camera.
   • Scan a QR code containing latitude,longitude,depKey.
   • Request current device GPS location.
   • Verify the device is within MaxDistanceMeters.
   • Verify the QR depKey matches the depKey prop.
   • Continue to face verification after location validation.

🌐 Workflow diagram

flowchart TD
  A[Start Verification] --> B{qrscan === true?}
  B -- Yes --> C[Scan QR Code]
  B -- No --> F[Start Face Scan]
  C --> D[Request Device Location]
  D --> E[Compare distance and depKey]
  E -- Valid --> F
  E -- Invalid --> G[Show location error]
  F --> H[Detect stable face & liveness]
  H --> I[Capture photo]
  I --> J[Upload to API]
  J --> K{API response}
  K -- Success --> L[Show success and callback]
  K -- Fail --> M[Show failure message]

📌 Props reference

| Prop | Type | Required | Description | Default | |------|------|----------|-------------|---------| | apiurl | string | Yes | Base URL for the verification backend request. | - | | data | string | Yes | Unique user identifier (employee ID, face ID, etc.). | - | | navigation | object | Yes | React Navigation prop used for timeout navigation. | - | | onclose | function | Yes | Called when the modal closes. Receives false. | - | | callback | function | Yes | Called after successful verification with result data. | - | | qrscan | boolean | No | Start with QR scan mode. | false | | depKey | string | No | Expected key inside the scanned QR payload. | - | | duration | number | No | Countdown length in seconds. | 100 | | MaxDistanceMeters | number | No | Allowed GPS distance radius in meters. | 30 | | frameProcessorFps | number | No | Camera frame processor FPS. | 5 | | livenessLevel | number | No | Liveness check mode: 0 or 1. | 0 | | antispooflevel | number | No | Anti-spoof threshold used internally. | 0.35 | | fileurl | string | No | Optional file URL for displaying employee data. | - | | imageurl | string | No | Optional image URL for display. | - |

🧩 Example: face-only verification

<BiometricModal
  data="EMPLOYEE_123"
  apiurl="https://your-api-endpoint.com/"
  navigation={navigation}
  onclose={(open) => setIsVerifierOpen(open)}
  callback={handleVerificationComplete}
  qrscan={false}
  duration={90}
  frameProcessorFps={4}
  livenessLevel={0}
/>

🧭 Example: QR + face verification

<BiometricModal
  data="EMPLOYEE_123"
  depKey="OFFICE_A"
  apiurl="https://your-api-endpoint.com/"
  navigation={navigation}
  onclose={(open) => setIsVerifierOpen(open)}
  callback={handleVerificationComplete}
  qrscan={true}
  duration={120}
  MaxDistanceMeters={50}
  frameProcessorFps={3}
  livenessLevel={1}
  antispooflevel={0.35}
/>

🧱 Internal architecture

• src/index.js – Main BiometricModal component and verification flow.
• src/components/CaptureImageWithoutEdit.js – Camera capture, face detection, and QR scanning.
• src/hooks/useFaceDetectionFrameProcessor.js – Face liveness and anti-spoof frame processor.
• src/hooks/useGeolocation.js – Location permission and GPS fetch.
• src/hooks/useImageProcessing.js – Image resize and Base64 conversion.
• src/hooks/useCountdown.js – Countdown timer logic.
• src/hooks/useNotifyMessage.js – Animated notification messages.
• src/utils/NetworkServiceCall.js – API request helper.
• src/utils/distanceCalculator.js – Geolocation distance calculation.
• src/utils/Global.js – Shared constants and theme values.

💡 Interview talking points

• Explain the dual modes: face-only and QR-first.
• Describe how location validation prevents spoofing of presence.
• Mention the use of use* hooks for clean and reusable code.
• Highlight the flow from camera capture → Base64 conversion → API request → callback.
• Note the user-friendly UI with timer, notifications, and step indicator.

🤝 Contribution

Contributions are welcome. Open an issue or submit a pull request for bug fixes and improvements.

📄 License

JESCON TECHNOLOGIES PVT LTD