Liveness&T Module

Overview

The Liveness&T module provides face liveness detection using TOC (Technology of Confidence) technology. This module offers a streamlined approach to verifying that the person being authenticated is physically present, preventing spoofing attacks with photos or videos.

Key Features

Active Liveness Detection: Challenge-response based liveness verification
Simple Integration: Straightforward API with minimal configuration
Face Scan Output: Provides face image for verification and matching
Multiple Detection Modes: Configurable liveness detection strategies
Customizable UI: Full customization of feedback messages
Cross-Platform: Works on mobile and desktop browsers
Module Close Detection: Track when users exit the process

Hardware Requirements

This module requires valid TOC credentials (app identifier).

Modern web browser with WebRTC support
Device camera (front-facing recommended)
Good lighting conditions
Stable internet connection
HTTPS protocol (required)

Installation

npm install @fad-producto/fad-sdk

Implementation

Import SDK and Configure Credentials

Import the FAD SDK and set up your TOC credentials:

import FadSDK from '@fad-producto/fad-sdk';

const CREDENTIALS = {
  app: 'YOUR_TOC_APP_IDENTIFIER',
};

const TOKEN = 'YOUR_FAD_TOKEN';

Configure Liveness Detection

Set up the detection mode and customization:

const CONFIGURATION = {
  livenessDetection: {
    mode: 0,  // Detection mode (0, 1, 2, etc.)
  },
  customization: {
    moduleCustomization: {
      legends: {
        locale: 'es',  // Language: 'es' (Spanish), 'en' (English)
      },
    },
  },
};

Initialize SDK and Start Liveness Check

Create the SDK instance and start the liveness process:

async function initProcess() {
  const options = {
    environment: FadSDK.getFadEnvironments().UATHA,
  };

  const FAD_SDK = new FadSDK(TOKEN, options);
  
  try {
    const moduleResponse = await FAD_SDK.startLivenessToc(
      CREDENTIALS,
      CONFIGURATION
    );

    // Check if user closed the module
    if (moduleResponse.event === FadSDK.Constants.EventModule.MODULE_CLOSED) {
      console.log('Module closed by user');
      return;
    }

    console.log('Process completed', moduleResponse);

    // Access face scan data
    const faceScan = moduleResponse.data.faceScan;  // Base64 or URL

    // Use face scan for verification
    displayResult(faceScan);

  } catch (ex) {
    console.error('Process error:', ex);
    handleError(ex);
  } finally {
    FAD_SDK.end();
  }
}

Response Structure

{
  event: string,  // 'PROCESS_COMPLETED' or 'MODULE_CLOSED'
  data: {
    faceScan: string,  // Base64 image or URL of captured face
  }
}

The faceScan contains the captured face image that can be used for face matching or verification purposes.

Error Handling

Handle errors using the SDK error constants:

if (ex.code === FadSDK.Errors.LivenessToc.SERVICE_ERROR) {
  alert('Service error occurred. Please try again.');
}

Configuration Options

Detection Mode

Configure the liveness detection strategy:

livenessDetection: {
  mode: 0  // Detection mode
}

Different modes offer varying levels of security and user experience:

Mode	Security	User Experience	Use Case
0	Standard	Easy	General purpose
1	Enhanced	Moderate	Financial services
2	High	Challenging	High security

Consult TOC documentation for specific mode behaviors and requirements.

Locale Configuration

Set the language for user feedback:

legends: {
  locale: 'es'  // 'es' for Spanish, 'en' for English
}

Supported languages:

es - Spanish
en - English
Additional languages may be available (check TOC documentation)

Event Handling

Handle different completion events:

if (response.event === FadSDK.Constants.EventModule.MODULE_CLOSED) {
  // User closed the module
  console.log('User cancelled');
} else if (response.event === FadSDK.Constants.EventModule.PROCESS_COMPLETED) {
  // Successfully completed
  console.log('Liveness verified');
}

Usage Examples

Basic Implementation
With User Feedback
Face Matching Integration

import FadSDK from '@fad-producto/fad-sdk';

async function performLivenessCheck() {
  const FAD_SDK = new FadSDK(TOKEN, {
    environment: FadSDK.getFadEnvironments().UATHA,
  });

  try {
    const response = await FAD_SDK.startLivenessToc(
      { app: 'YOUR_APP_ID' },
      {
        livenessDetection: { mode: 0 },
        customization: {
          moduleCustomization: {
            legends: { locale: 'en' },
          },
        },
      }
    );

    if (response.event === FadSDK.Constants.EventModule.MODULE_CLOSED) {
      return null;
    }

    return response.data.faceScan;
  } finally {
    FAD_SDK.end();
  }
}

async function livenessWithFeedback() {
  const FAD_SDK = new FadSDK(TOKEN, {
    environment: FadSDK.getFadEnvironments().UATHA,
  });

  try {
    showLoadingMessage('Initializing liveness check...');

    const response = await FAD_SDK.startLivenessToc(
      CREDENTIALS,
      CONFIGURATION
    );

    if (response.event === FadSDK.Constants.EventModule.MODULE_CLOSED) {
      showMessage('Verification cancelled');
      return null;
    }

    showSuccessMessage('Liveness verified successfully!');
    return response.data.faceScan;
  } catch (error) {
    if (error.code === FadSDK.Errors.LivenessToc.FACE_BLURRY) {
      showErrorMessage('Image quality too low. Please retry in better lighting.');
    } else if (error.code === FadSDK.Errors.LivenessToc.TIMEOUT_EXCEEDED) {
      showErrorMessage('Session timed out. Please try again.');
    } else {
      showErrorMessage('Verification failed. Please try again.');
    }
    throw error;
  } finally {
    FAD_SDK.end();
  }
}

async function verifyUserIdentity(userId) {
  const FAD_SDK = new FadSDK(TOKEN, {
    environment: FadSDK.getFadEnvironments().UATHA,
  });

  try {
    // Capture liveness
    const response = await FAD_SDK.startLivenessToc(
      CREDENTIALS,
      CONFIGURATION
    );

    if (response.event === FadSDK.Constants.EventModule.MODULE_CLOSED) {
      throw new Error('User cancelled verification');
    }

    const faceScan = response.data.faceScan;

    // Send to backend for face matching
    const matchResult = await fetch('/api/verify-face', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        userId,
        faceScan,
        timestamp: new Date().toISOString(),
      }),
    });

    const result = await matchResult.json();
    
    if (result.match && result.confidence > 0.8) {
      return { verified: true, confidence: result.confidence };
    } else {
      return { verified: false, confidence: result.confidence };
    }
  } finally {
    FAD_SDK.end();
  }
}

Best Practices

Lighting Conditions

Ensure adequate, even lighting. Avoid backlighting and harsh shadows for best results.

User Guidance

Provide clear instructions before starting the liveness check to set user expectations.

Error Recovery

Implement clear error messages and allow users to easily retry the verification.

Security Mode

Choose appropriate detection mode based on your security requirements and user base.

Detection Modes Comparison

Mode 0 - Standard
Mode 1 - Enhanced
Mode 2 - High Security

Best For: General purpose applicationsCharacteristics:

Quick verification
Easy user experience
Good for low-risk scenarios
High success rate

Use Cases:

Social apps
General authentication
User-friendly flows

Security Considerations

Always verify liveness results on your backend server. Never rely solely on client-side verification.

Verify face scan on backend server
Implement rate limiting to prevent abuse
Store face scans securely with encryption
Use HTTPS for all communications
Follow GDPR/CCPA guidelines for biometric data
Maintain audit logs of liveness checks
Set appropriate session timeouts
Implement retry limits

Troubleshooting

Liveness Check Fails

Improve lighting conditions
Ensure face is clearly visible
Remove glasses or face obstructions
Follow on-screen instructions carefully
Try a different detection mode

Blurry Face Images

Improve lighting
Hold device steady
Clean camera lens
Ensure adequate distance from camera
Use device with better camera quality

Timeout Issues

Check network connectivity
Ensure stable internet connection
Verify TOC service is accessible
Try again with better conditions

Service Errors

Verify credentials are correct
Check network connectivity
Ensure TOC service is available
Contact support if issues persist

Event Handling

async function handleLiveness() {
  const FAD_SDK = new FadSDK(TOKEN, {
    environment: FadSDK.getFadEnvironments().UATHA,
  });

  try {
    const response = await FAD_SDK.startLivenessToc(
      CREDENTIALS,
      CONFIGURATION
    );

    // Handle different events
    switch (response.event) {
      case FadSDK.Constants.EventModule.PROCESS_COMPLETED:
        console.log('Liveness verified successfully');
        return response.data.faceScan;

      case FadSDK.Constants.EventModule.MODULE_CLOSED:
        console.log('User cancelled the verification');
        return null;

      default:
        console.warn('Unexpected event:', response.event);
        return null;
    }
  } finally {
    FAD_SDK.end();
  }
}

Liveness-3D - FaceTec liveness detection
Liveness-3D&I - Identy Face liveness detection
Capture-id&R - Document capture with Regula

Getting Started

Core Concepts

Modules

Integration Guides

Liveness&T Module

Overview

Key Features

Hardware Requirements

Installation

Implementation

Response Structure

Error Handling

Configuration Options

Usage Examples

Best Practices

Lighting Conditions

User Guidance

Error Recovery

Security Mode

Detection Modes Comparison

Security Considerations

Troubleshooting

Event Handling

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Modules

Integration Guides

​Overview

​Key Features

​Hardware Requirements

​Installation

​Implementation

​Response Structure

​Error Handling

​Configuration Options

​Usage Examples

​Best Practices

Lighting Conditions

User Guidance

Error Recovery

Security Mode

​Detection Modes Comparison

​Security Considerations

​Troubleshooting

​Event Handling

​Related Modules

Build docs developers (and LLMs) love

Overview

Key Features

Hardware Requirements

Installation

Implementation

Response Structure

Error Handling

Configuration Options

Usage Examples

Best Practices

Detection Modes Comparison

Security Considerations

Troubleshooting

Event Handling

Related Modules