@richard.fadiora/liveness-detection 3.0.3 → 3.1.1

package/README.md

@@ -2,7 +2,11 @@
 
 A React-based liveness detection component that performs randomized user challenges and verifies real-user presence via a backend anti-spoofing API.
 
-This version introduces **headless mode**, **render-prop customization**, and robust **challenge sequencing**, allowing you to fully control the UI while keeping the verification logic encapsulated.
+This version introduces **headless mode**, **render-prop customization**, and robust **challenge sequencing**, **configurable thresholds** for `Smile`, `Blink`, and `Turn_Head` challenges
+
+Pause between steps for user feedback
+
+Sequential challenge execution with strict timeout handling allowing you to fully control the UI while keeping the verification logic encapsulated.
 
 ---
 
@@ -14,7 +18,8 @@ This component strengthens identity verification by combining:
 - Strict timeout enforcement  
 - Backend spoof detection  
 - Callback-based integration for easy usage  
-- Headless / fully customizable UI via render props  
+- Headless / fully customizable UI via render props
+- Configurable challenge thresholds to adapt difficulty  
 
 It protects against:
 
@@ -38,6 +43,14 @@ It protects against:
 - Real-time validation using webcam input and MediaPipe models.  
 - Sequential verification ensures **no steps are skipped**.  
 - Developers can render custom UI via the **render prop** while using the same underlying logic.
+- Challenge thresholds are configurable through props:
+
+| Prop Name             | Default | Description                              |
+|-----------------------|---------|------------------------------------------|
+| `smileThreshold`      | 0.20    | Minimum smile width to count as valid    |
+| `blinkThreshold`      | 0.01    | Maximum eye aspect ratio to count as blink |
+| `minturnHeadThreshold`| 0.15    | Minimum yaw for right head turn detection      |
+| `maxturnHeadThreshold`| 0.85    | Maximum yaw for left head turn detection      |
 
 ### 3️⃣ Backend Liveness Verification
 
@@ -76,6 +89,11 @@ onError({ success: false, reason, skinConfidence: null });
 | `duration` | `number`                     | No       | Maximum time for all challenges (default: 60s) |
 | `render`   | `(sdk: object) => JSX.Element` | No      | Optional render prop for full UI customization |
 | `classNames` | `object`                   | No       | Optional CSS class names to customize default UI |
+| `smileThreshold`       | `number`     | No       | Minimum smile width for Smile challenge                  |
+| `blinkThreshold`       | `number`     | No       | Maximum eye aspect ratio for Blink challenge             |
+| `minturnHeadThreshold` | `number`     | No       | Minimum yaw for Turn_Head challenge                      |
+| `maxturnHeadThreshold` | `number`     | No       | Maximum yaw for Turn_Head challenge                      |
+
 
 ---
 
@@ -115,6 +133,25 @@ export default App;
   )}
 />
 ```
+## 📤 Hook Return Values
+
+The `useLiveness` hook exposes the following values and control functions for managing the liveness detection session.
+
+| Name | Type | Description |
+|-----|------|-------------|
+| `webcamRef` | `ref` | React ref attached to the webcam component. Provides access to the live video stream used for face and hand detection as well as frame capture for verification. |
+| `status` | `string` | Represents the current state of the liveness session. Possible values include `loading`, `ready`, `capturing`, `verifying`, `success`, `error`, and `expired`. |
+| `errorMsg` | `string` | Contains the error message displayed when the liveness verification fails or when the system encounters an issue. |
+| `sequence` | `string[]` | The randomized sequence of liveness challenges selected for the current session. Three challenges are chosen from the challenge pool. |
+| `currentStep` | `number` | The index of the current challenge being performed within the challenge sequence. |
+| `timeLeft` | `number` | Remaining time (in seconds) before the session expires. The timer runs while the system is in the `capturing` state. |
+| `isStepTransitioning` | `boolean` | Indicates whether the system is currently transitioning between challenges. Used to briefly pause detection and provide UI feedback after a challenge is completed. |
+| `start` | `function` | Starts the liveness challenge session and begins the detection loop. |
+| `reset` | `function` | Resets the entire session, including the timer, challenge sequence, step index, and error state. |
+| `sendFinalProof` | `function` | Sends captured face frames to the backend verification API to perform the final liveness check. Normally triggered automatically after the last challenge is completed. |
+
+
+
 
 ---
 
@@ -126,6 +163,7 @@ classNames={{
   container: "liveness-container",
   webcam: "liveness-webcam",
   button: "liveness-button",
+  challenge: "liveness-challenge",
   timer: "liveness-timer",
   error: "liveness-error",
   success: "liveness-success",
@@ -158,6 +196,11 @@ classNames={{
   cursor: pointer;
   margin-top: 10px;
 }
+.liveness-challenge {
+  margin: 5px 0;
+  font-weight: bold;
+  font-size: 40px;
+}
 .liveness-timer {
   margin: 10px 0;
   font-weight: bold;
@@ -203,7 +246,7 @@ classNames={{
 
 - Webcam permissions required  
 - Backend must accept 5 frames in expected format  
-- `apiUrl` must be reachable and have an endpoint `v1/verify` 
+- `apiUrl` must be reachable and have an endpoint `/v1/verify` 
 - CORS must be configured properly
 
 ---