Skip to main content

​
Overview

The Liveness-3D module provides advanced 3D face liveness detection using FaceTec’s ZoOm technology. This module ensures that the person being verified is physically present and not a photo, video, or mask, providing the highest level of security for face authentication.

​
Key Features

  • 3D Face Mapping: Advanced 3D face capture and analysis
  • Liveness Detection: Prevents spoofing with photos, videos, or masks
  • High Security: Bank-grade biometric verification
  • User-Friendly: Guided capture process with real-time feedback
  • Cross-Platform: Works on mobile and desktop browsers
  • Audit Trail: Captures multiple images for verification audit
  • Customizable UI: Full customization of colors, fonts, and legends

​
Hardware Requirements

This module requires valid FaceTec credentials including device key identifier and production key.
  • Modern web browser with WebGL support
  • Device camera (front-facing recommended)
  • Good lighting conditions
  • Stable internet connection
  • HTTPS protocol (required)

​
Installation

npm install @fad-producto/fad-sdk

​
Implementation

1

Import SDK and Configure Credentials

Import the FAD SDK and set up your FaceTec credentials:
import FadSDK from '@fad-producto/fad-sdk';

const CREDENTIALS = {
  deviceKeyIdentifier: 'YOUR_FACETEC_DEVICE_KEY',
  baseURL: '',
  publicFaceScanEncryptionKey:
    '-----BEGIN PUBLIC KEY-----\n' +
    'YOUR_PUBLIC_ENCRYPTION_KEY' +
    '-----END PUBLIC KEY-----',
  productionKeyText: {
    domains: 'YOUR_DOMAINS',
    expiryDate: 'YYYY-MM-DD',
    key: 'YOUR_PRODUCTION_KEY',
  },
};

const TOKEN = 'YOUR_FAD_TOKEN';
2

Configure Module Options

Set up the configuration with custom UI settings:
const CONFIGURATION = {
  views: {
    instructions: true,  // Show instruction screen
  },
  customization: {
    fadCustomization: {
      colors: {
        primary: '#A70635',
        secondary: '#A70635',
        tertiary: '#363636',
        succesful: '#5A9A92',
      },
    },
    moduleCustomization: {
      legends: {
        facetec: {
          instructionsHeaderReadyDesktop: 'Biometría facial',
          instructionsMessageReadyDesktop: 'Enfoca tu rostro en la guía y da clic en el botón para continuar',
          feedbackCenterFace: 'Centra tu rostro',
          feedbackFaceNotFound: 'Enfoca tu rostro',
          feedbackMoveWebCloser: 'Acércate',
          feedbackMoveWebAway: 'Aléjate',
        },
      },
      legendsInstructions: {
        title: 'Prueba de vida',
        subtitle: 'Enfoca tu rostro en la guía',
        buttonNext: 'Continuar',
      },
    },
  },
};
3

Initialize SDK and Start Liveness Check

Create the SDK instance and start the FaceTec liveness process:
async function initProcess() {
  const options = {
    environment: FadSDK.getFadEnvironments().UATHA,
  };

  const FAD_SDK = new FadSDK(TOKEN, options);
  
  try {
    // Start FaceTec liveness detection
    const facetecResponse = await FAD_SDK.startFacetec(
      CREDENTIALS,
      CONFIGURATION
    );

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

    // Access captured data
    const auditTrailImage = facetecResponse.data.auditTrail[0];
    const lowQualityAuditImage = facetecResponse.data.lowQualityAuditTrail[0];
    const faceScan = facetecResponse.data.faceScan;

    // Display results
    displayLivenessResults(auditTrailImage, faceScan);

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

​
Response Structure

{
  event: string,  // 'PROCESS_COMPLETED'
  data: {
    auditTrail: string[],           // Array of base64 images (high quality)
    lowQualityAuditTrail: string[], // Array of base64 images (low quality)
    faceScan: string,               // Encrypted face scan data
    sessionId: string,              // Session identifier
  }
}
The faceScan field contains encrypted biometric data that should be sent to your server for verification.

​
Error Handling

Handle errors using the SDK error constants: 
if (ex.code === FadSDK.Errors.Facetec.Session.CAMERA_NOT_RUNNING) {
  alert('Camera not supported. Please try a different device.');
}

​
Customization Options

Customize all FaceTec UI feedback messages:
legends: {
  facetec: {
    // Ready screen
    instructionsHeaderReadyDesktop: 'Face Biometrics',
    instructionsMessageReadyDesktop: 'Position your face in the guide',
    actionImReady: 'Continue',
    
    // Feedback during capture
    feedbackCenterFace: 'Center your face',
    feedbackFaceNotFound: 'Face not found',
    feedbackMoveWebCloser: 'Move closer',
    feedbackMoveWebAway: 'Move away',
    feedbackHoldSteady: 'Hold steady',
    
    // Pre-session instructions
    presessionFrameYourFace: 'Frame your face',
    presessionLookStraightAhead: 'Look straight ahead',
    presessionRemoveDarkGlasses: 'Remove sunglasses',
    presessionNeutralExpression: 'Neutral expression',
    
    // Retry screen
    retryHeader: 'Try again',
    retrySubheaderMessage: 'We need a clear image',
  },
}

fadCustomization: {
  colors: {
    primary: '#A70635',     // Primary brand color
    secondary: '#A70635',   // Secondary brand color
    tertiary: '#363636',    // Tertiary color
    succesful: '#5A9A92',  // Success state color
  },
  buttons: {
    primary: {
      backgroundColor: '#A70635',
      labelColor: '#ffffff',
    },
  },
  fonts: {
    title: {
      fontSize: '25px',
      fontFamily: 'system-ui',
    },
  },
}

legendsInstructions: {
  title: 'Liveness Check',
  subtitle: 'Position your face in the guide',
  buttonNext: 'Continue',
  instructions: 'Remove sunglasses, caps, and other items that may obstruct your face.',
}

​
Usage Examples

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.startFacetec(
      CREDENTIALS,
      CONFIGURATION
    );

    // Send faceScan to your backend for verification
    const verificationResult = await fetch('/api/verify-liveness', {
      method: 'POST',
      body: JSON.stringify({
        faceScan: response.data.faceScan,
        sessionId: response.data.sessionId,
      }),
    });

    console.log('Verification result:', verificationResult);
  } catch (error) {
    console.error('Liveness check failed:', error);
  } finally {
    FAD_SDK.end();
  }
}

​
Best Practices

Lighting Conditions

Ensure adequate, even lighting. Avoid backlighting or harsh shadows on the face.

User Guidance

Provide clear instructions before starting. Show the instruction screen to set expectations.

Error Recovery

Allow users to retry easily. Provide specific feedback on why a check failed.

Privacy Notice

Inform users about biometric data collection and usage per privacy regulations.

​
Security Considerations

Always verify the faceScan data on your backend server. Never trust client-side verification alone.
  • The faceScan data is encrypted and should be verified server-side
  • Store audit trail images securely for compliance and debugging
  • Implement rate limiting to prevent abuse
  • Use HTTPS for all communications
  • Follow GDPR/CCPA guidelines for biometric data

​
Troubleshooting

  • Verify FaceTec credentials are correct
  • Check production key expiry date
  • Ensure domains in production key match your domain
  • Verify device key identifier is valid
  • Check camera permissions
  • Ensure HTTPS is used
  • Test on different browsers (Chrome, Safari, Firefox)
  • Verify WebGL support in browser
  • Improve lighting conditions
  • Remove glasses or face obstructions
  • Ensure face is centered in frame
  • Check camera quality

Build docs developers (and LLMs) love

Get started for freeTalk to us