react-native-biometric-verifier 0.0.65 → 0.0.67

package/README.md

@@ -1,116 +1,253 @@
 # React Native Biometric Verifier
-
-A powerful and easy-to-use React Native module for biometric verification, featuring face recognition and QR code scanning capabilities with location validation.
-
-
-## Features
-
-- **Face Recognition**: Capture and verify user identity via face scan.
-- **QR Code Scanning**: specialized mode for location verification using QR codes.
-- **Location Validation**: Verify user presence within a specific geofence.
-- **Liveness Detection**: Configurable liveness and anti-spoofing checks.
-- **Customizable UI**: Animations, countdown timers, and feedback notifications.
-
-## Installation
-
+ 
+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
+ 
 ```bash
 npm install react-native-biometric-verifier
 ```
-
-### Peer Dependencies
-
-This library relies on several peer dependencies that you must install in your project:
-
+ 
+### Required peer dependencies
+ 
 ```bash
 npm install react-native-vector-icons react-native-geolocation-service react-native-image-resizer react-native-fs prop-types
 ```
-
-### Platform Configuration
-
-#### iOS
-Add the following keys to your `Info.plist` file to request camera and location permissions:
-
+ 
+> 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`:
+ 
 ```xml
 <key>NSCameraUsageDescription</key>
-<string>We need access to your camera for biometric verification</string>
+<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>
+<string>We need your location to verify your presence at the designated area.</string>
 ```
-
-#### Android
-Add the following permissions to your `AndroidManifest.xml`:
-
+ 
+### Android
+Add these permissions to `AndroidManifest.xml`:
+ 
 ```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" />
 ```
-
-## Usage
-
-Import the `BiometricModal` component and standard React hooks.
-
+ 
+---
+ 
+## 📘 Basic Usage
+ 
 ```javascript
 import React, { useState } from 'react';
 import { View, Button } from 'react-native';
 import BiometricModal from 'react-native-biometric-verifier';
-
-const App = () => {
+ 
+const App = ({ navigation }) => {
   const [isVerifierOpen, setIsVerifierOpen] = useState(false);
-
-  const handleVerificationComplete = (data) => {
-    console.log('Verification Success:', data);
-    // Handle success (e.g., navigate to next screen, show success message)
+ 
+  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" // e.g., Employee ID or Face ID
-          depKey="DEPARTMENT_KEY" // Optional: for QR location validation
+          data="USER_UNIQUE_ID"
           apiurl="https://your-api-endpoint.com/"
-          onclose={(val) => setIsVerifierOpen(val)}
+          navigation={navigation}
+          onclose={(open) => setIsVerifierOpen(open)}
           callback={handleVerificationComplete}
-          // Optional Props
-          qrscan={false} // Set to true to enable QR scan mode first
-          duration={100} // Countdown duration in seconds
-          MaxDistanceMeters={30} // Allowed radius for location verification
+          qrscan={false}
+          duration={100}
+          MaxDistanceMeters={30}
           frameProcessorFps={5}
-          livenessLevel="high"
-          antispooflevel="high"
+          livenessLevel={1}
+          antispooflevel={0.35}
         />
       )}
     </View>
   );
 };
-
+ 
 export default App;
 ```
-
-## Props
-
+ 
+> `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
+ 
+```mermaid
+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 API. | - |
-| `data` | string | Yes | Unique identifier for the user (e.g., Face ID, User ID). | - |
-| `onclose` | function | Yes | Callback function to close the modal. | - |
-| `callback` | function | Yes | Callback function returning successful verification data. | - |
-| `qrscan` | boolean | No | If `true`, starts with QR code scanning mode. | `false` |
-| `depKey` | string | No | Key used to validate the QR code content. | - |
-| `duration` | number | No | Timeout duration for the session in seconds. | `100` |
-| `MaxDistanceMeters` | number | No | Maximum allowed distance (meters) for location check. | `30` |
-| `frameProcessorFps` | number | No | Frames per second for image processing. | - |
-| `livenessLevel` | string | No | Liveness detection strictness. | - |
-| `antispooflevel` | string | No | Anti-spoofing strictness. | - |
-
-## Contributing
-
-Contributions are welcome! Please open an issue or submit a pull request for any bugs or improvements.
-
-## License
-
+| `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
+ 
+```javascript
+<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
+ 
+```javascript
+<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
+  

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-biometric-verifier",
-  "version": "0.0.65",
+  "version": "0.0.67",
   "description": "A React Native module for biometric verification with face recognition and QR code scanning",
   "main": "src/index.js",
   "types": "src/index.d.ts",