Liveness-3D&I Module

Overview

The Liveness-3D&I module provides advanced face liveness detection using Identy Face technology. This module ensures that the person being verified is physically present and provides high-quality biometric templates for face matching and verification.

Key Features

Advanced Liveness Detection: Prevents spoofing attacks with photos, videos, or masks
Biometric Templates: Generates multiple template formats (JPEG, WSQ)
Quality Metrics: Provides quality and resolution scores
Anti-Spoofing Threshold: Configurable security levels
Assisted Mode: Optional guidance for users during capture
Real-time Feedback: Visual and textual guidance during capture
Customizable UI: Full customization of colors, fonts, and feedback messages
Cross-Platform: Works on mobile and desktop browsers

Hardware Requirements

This module requires valid Identy Face credentials including model URL.

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 Identy Face credentials:

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

const CREDENTIALS = {
  modelUrl: 'YOUR_IDENTY_MODEL_URL',
};

const TOKEN = 'YOUR_FAD_TOKEN';

Configure Detection Settings

Set up liveness detection parameters:

const CONFIGURATION = {
  livenesCheck: true,              // Enable liveness detection
  asThreshold: 'HIGH',             // Anti-spoofing threshold: LOW, MEDIUM, HIGH
  assisted: false,                 // Enable assisted capture mode
  timeout: 50000,                  // Capture timeout (milliseconds)
  appUI: 0,                        // UI variant
  headerProcess: window.location.origin,
};

Customize UI and Feedback

Configure the visual appearance and feedback messages:

const CONFIGURATION = {
  // ... previous config
  customization: {
    fadCustomization: {
      colors: {
        primary: '#A70635',
      },
      buttons: {
        primary: {
          backgroundColor: '#A70635',
          labelColor: '#ffffff',
        },
      },
    },
    moduleCustomization: {
      style: {
        identy: {
          canvas: {
            canvasBackground: '#F2F2F2',
            labelColor: '#FFFFFF',
            ovalBorderBackground: null,
            ovalBorderErrorBackground: '#E4DC30',
            tickerActiveBackground: null,
            tickerDefaultBackground: '#FFFFFF',
          },
        },
      },
      legends: {
        identy: {
          feedbackCaptured: 'Capture successful',
          feedbackChangeLight: 'Avoid reflections and shadows',
          feedbackClose: 'Move away from device',
          feedbackFar: 'Move closer to device',
          feedbackEyeLevel: 'Look straight ahead',
          feedbackNotStable: 'Hold still',
          feedbackProcessing: 'Processing',
        },
      },
    },
  },
};

Initialize SDK and Start Liveness Check

Create the SDK instance and start the liveness detection:

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

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

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

    // Access captured data
    const jpegTemplate = moduleResponse.data.templates.JPEG;
    const quality = moduleResponse.data.quality;
    const resolution = moduleResponse.data.resolution;
    const captureDate = moduleResponse.data.capture_date;

    // Display results
    displayResults(jpegTemplate, { quality, resolution, captureDate });

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

Response Structure

{
  event: string,  // 'PROCESS_COMPLETED'
  data: {
    templates: {
      JPEG: string,   // Base64 encoded JPEG template
      WSQ?: string,   // Base64 encoded WSQ template (optional)
    },
    quality: number,        // Quality score (0-100)
    resolution: number,     // Image resolution
    capture_date: string,   // ISO timestamp
  }
}

The JPEG template is a base64-encoded image that can be used for face matching. Quality scores above 70 are generally considered good.

Error Handling

Handle errors using the SDK error constants:

if (ex.code === FadSDK.Errors.IdentyFace.NO_MODEL_URL) {
  alert('Credentials are missing. Please provide model URL.');
}

Configuration Options

Anti-Spoofing Threshold

Set the security level for liveness detection:

asThreshold: 'HIGH'  // Options: 'LOW', 'MEDIUM', 'HIGH'

Level	False Accept Rate	Use Case
`LOW`	Higher	Less critical applications
`MEDIUM`	Balanced	General purpose
`HIGH`	Lower	High security applications

Higher thresholds provide better security but may require better lighting and positioning.

Assisted Mode

Enable or disable assisted capture:

assisted: true  // true: guided capture, false: automatic

Assisted Mode Benefits:

Step-by-step guidance
Better user experience for first-time users
Higher success rates

Automatic Mode Benefits:

Faster capture
Better for experienced users
Streamlined flow

Timeout Settings

Configure capture timeout:

timeout: 50000  // Timeout in milliseconds (50 seconds)

Adjust based on:

Expected user experience level
Lighting conditions
Device performance

Canvas Styling

Customize the capture interface appearance:

canvas: {
  canvasBackground: '#F2F2F2',           // Background color
  labelColor: '#FFFFFF',                 // Text color
  ovalBorderBackground: null,            // Normal state color
  ovalBorderErrorBackground: '#E4DC30',  // Error state color
  tickerActiveBackground: null,          // Active indicator
  tickerDefaultBackground: '#FFFFFF',    // Default indicator
}

Feedback Messages

Customize all user feedback messages:

legends: {
  identy: {
    feedbackCaptured: 'Capture successful',
    feedbackChangeLight: 'Avoid reflections',
    feedbackChangeLightTooBright: 'Too bright, move to better lighting',
    feedbackChangeLightTooDark: 'Too dark, move to better lighting',
    feedbackClose: 'Move away',
    feedbackFar: 'Move closer',
    feedbackEyeLevel: 'Look straight ahead',
    feedbackNotStable: 'Hold still',
    feedbackInitialization: 'Initializing',
    feedbackProcessing: 'Processing',
  },
}

Usage Examples

Basic Implementation
With Quality Validation
Face Matching

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.startIdentyFace(
      { modelUrl: 'YOUR_MODEL_URL' },
      {
        livenesCheck: true,
        asThreshold: 'HIGH',
        timeout: 50000,
      }
    );

    // Use the JPEG template for face matching
    const faceTemplate = response.data.templates.JPEG;
    const quality = response.data.quality;

    if (quality > 70) {
      console.log('High quality capture');
    }

    return faceTemplate;
  } finally {
    FAD_SDK.end();
  }
}

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

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

    const { quality, templates, resolution } = response.data;

    if (quality < minQuality) {
      throw new Error(`Quality ${quality} is below minimum ${minQuality}`);
    }

    console.log(`Capture quality: ${quality}`);
    console.log(`Resolution: ${resolution}`);

    return templates.JPEG;
  } finally {
    FAD_SDK.end();
  }
}

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

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

    const faceTemplate = response.data.templates.JPEG;

    // Send to backend for face matching
    const matchResult = await fetch('/api/face-match', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        template: faceTemplate,
        quality: response.data.quality,
        captureDate: response.data.capture_date,
      }),
    });

    return await matchResult.json();
  } finally {
    FAD_SDK.end();
  }
}

Best Practices

Lighting Conditions

Ensure even, adequate lighting. Avoid backlighting and harsh shadows.

Quality Threshold

Set minimum quality requirements (e.g., 70+) for your use case.

Security Level

Use HIGH threshold for sensitive applications like financial services.

User Guidance

Enable assisted mode for first-time users or complex scenarios.

Quality Metrics Guide

Quality Score	Rating	Recommendation
90-100	Excellent	Perfect for all use cases
70-89	Good	Suitable for most applications
50-69	Fair	May require retry for critical apps
0-49	Poor	Retry capture recommended

Security Considerations

Always verify liveness results on your backend server. Never trust client-side verification alone.

Store biometric templates securely with encryption
Implement rate limiting to prevent abuse
Use HTTPS for all communications
Follow GDPR/CCPA guidelines for biometric data
Maintain audit logs of liveness checks
Set appropriate data retention policies
Consider data residency requirements

Troubleshooting

Initialization Fails

Verify model URL is correct and accessible
Check network connectivity
Ensure browser supports WebRTC
Verify credentials are valid

Low Quality Captures

Improve lighting conditions
Ensure face is centered in frame
Clean camera lens
Ensure user is at optimal distance
Remove glasses or obstructions

Liveness Check Fails

Improve lighting (avoid shadows)
Ensure real person (not photo/video)
Check anti-spoofing threshold setting
Verify camera quality is adequate

Timeout Issues

Increase timeout value
Improve lighting conditions
Enable assisted mode for guidance
Check device performance

Liveness-3D - FaceTec liveness detection
Liveness&T - TOC liveness detection
Fingerprints&I - Identy fingerprint capture

Getting Started

Core Concepts

Modules

Integration Guides

Liveness-3D&I Module

Overview

Key Features

Hardware Requirements

Installation

Implementation

Response Structure

Error Handling

Configuration Options

Usage Examples

Best Practices

Lighting Conditions

Quality Threshold

Security Level

User Guidance

Quality Metrics Guide

Security Considerations

Troubleshooting

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

Quality Threshold

Security Level

User Guidance

​Quality Metrics Guide

​Security Considerations

​Troubleshooting

​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

Quality Metrics Guide

Security Considerations

Troubleshooting

Related Modules