Quick Start Guide

This guide will walk you through creating a complete biometric authentication flow using FAD SDK’s Liveness-3D module. You’ll learn the core patterns that apply to all FAD SDK modules.

This tutorial assumes you’ve already installed FAD SDK. If not, complete the installation first.

What You’ll Build

By the end of this tutorial, you’ll have a working biometric authentication flow that:

Initializes the FAD SDK with proper configuration
Captures a 3D liveness scan to prevent spoofing
Handles errors and edge cases gracefully
Displays the captured biometric data
Properly cleans up resources

Step-by-Step Implementation

Set up your credentials

First, create a constants file to store your API credentials. This keeps sensitive data separate from your logic.

TypeScript
JavaScript

Create constants.ts:

// Liveness-3D (FaceTec) credentials
export const CREDENTIALS = {
  deviceKeyIdentifier: 'YOUR_DEVICE_KEY',
  baseURL: 'https://your-api-endpoint.com',
  publicFaceScanEncryptionKey:
    '-----BEGIN PUBLIC KEY-----\n' +
    'YOUR_PUBLIC_KEY_HERE' +
    '\n-----END PUBLIC KEY-----',
  productionKeyText: {
    domains: 'your-domain.com',
    expiryDate: '2026-12-31',
    key: 'YOUR_PRODUCTION_KEY',
  },
};

export const TOKEN = 'YOUR_FAD_SDK_TOKEN';

// Optional customization
export const CONFIGURATION = {
  views: {
    instructions: true,
  },
  customization: {
    fadCustomization: {
      colors: {
        primary: '#A70635',
        secondary: '#A70635',
        tertiary: '#363636',
        successful: '#5A9A92',
      },
    },
  },
};

Create constants.js:

// Liveness-3D (FaceTec) credentials
export const CREDENTIALS = {
  deviceKeyIdentifier: 'YOUR_DEVICE_KEY',
  baseURL: 'https://your-api-endpoint.com',
  publicFaceScanEncryptionKey:
    '-----BEGIN PUBLIC KEY-----\n' +
    'YOUR_PUBLIC_KEY_HERE' +
    '\n-----END PUBLIC KEY-----',
  productionKeyText: {
    domains: 'your-domain.com',
    expiryDate: '2026-12-31',
    key: 'YOUR_PRODUCTION_KEY',
  },
};

export const TOKEN = 'YOUR_FAD_SDK_TOKEN';

// Optional customization
export const CONFIGURATION = {
  views: {
    instructions: true,
  },
  customization: {
    fadCustomization: {
      colors: {
        primary: '#A70635',
        secondary: '#A70635',
        tertiary: '#363636',
        successful: '#5A9A92',
      },
    },
  },
};

Replace the placeholder values with your actual credentials. Contact your FAD SDK provider to obtain these values.

Import and initialize the SDK

Import FAD SDK and your credentials, then create an SDK instance.

npm / TypeScript
Vanilla JavaScript

import FadSDK from '@fad-producto/fad-sdk';
import { CREDENTIALS, CONFIGURATION, TOKEN } from './constants';

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

  // Create SDK instance
  const FAD_SDK = new FadSDK(TOKEN, options);

  // SDK is now ready to use
}

initProcess();

import FadSDK from './web-sdk/fad-sdk.min.js';
import { CREDENTIALS, CONFIGURATION, TOKEN } from './constants.js';

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

  // Create SDK instance
  const FAD_SDK = new FadSDK(TOKEN, options);

  // SDK is now ready to use
}

initProcess();

The getFadEnvironments() method returns available environments (UATHA, PRODUCTION, etc.). Choose the appropriate environment for your use case.

Start the liveness detection process

Use the SDK instance to start the biometric process. All SDK methods return Promises, so use async/await or .then()/.catch().

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

  const FAD_SDK = new FadSDK(TOKEN, options);

  try {
    // Start the Liveness-3D process
    const facetecResponse = await FAD_SDK.startFacetec(
      CREDENTIALS,
      CONFIGURATION
    );

    // Process completed successfully
    console.log('Process completed');
    console.log(facetecResponse);

    // Extract results
    const img = facetecResponse.data.auditTrail[0];
    const imgLowQuality = facetecResponse.data.lowQualityAuditTrail[0];
    const faceScan = facetecResponse.data.faceScan;

    // Display results (see next step)
  } catch (ex) {
    // Handle errors (see step 4)
    console.error(ex);
  } finally {
    // Always clean up resources
    FAD_SDK.end();
  }
}

initProcess();

The response structure varies by module. Check the module-specific documentation for detailed response schemas.

Handle errors gracefully

FAD SDK provides specific error codes for different failure scenarios. Handle these to improve user experience.

try {
  const facetecResponse = await FAD_SDK.startFacetec(
    CREDENTIALS,
    CONFIGURATION
  );
  // ... handle success
} catch (ex) {
  console.error(ex);

  // Handle specific error codes
  if (ex.code === FadSDK.Errors.Facetec.Session.CAMERA_NOT_RUNNING) {
    alert('Camera not supported. Please try another device.');
  } else if (ex.code === FadSDK.Errors.Facetec.Session.INITIALIZATION_NOT_COMPLETED) {
    // Restart the component
    console.log('Initialization failed, restarting...');
  } else if (ex.code === FadSDK.Errors.Facetec.Status.TIMEOUT) {
    alert('Process timed out. Please try again.');
  } else {
    // Generic error handling
    alert(`An error occurred: ${JSON.stringify(ex)}`);
  }
} finally {
  FAD_SDK.end();
}

Error Response Structure

All errors follow this structure:

interface ResponseError<T> {
  code: T;      // Module-specific error code
  error: string; // Human-readable error message
}

Each module has its own error codes. Consult the module-specific documentation for a complete list of error codes and their meanings.

Display results in your UI

Create a simple HTML structure to display the captured biometric data.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>FAD SDK - Liveness Detection</title>
  </head>
  <body>
    <h1>Liveness Detection</h1>
    
    <div id="container-result" style="display: none;">
      <div>
        <p><strong>Face Image (High Quality):</strong></p>
        <img id="image-high" width="300px" alt="Face" />
      </div>

      <div>
        <p><strong>Face Image (Low Quality):</strong></p>
        <img id="image-low" width="300px" alt="Face Low Quality" />
      </div>
    </div>

    <script src="app.js" type="module"></script>
  </body>
</html>

Update your JavaScript to populate the images:

try {
  const facetecResponse = await FAD_SDK.startFacetec(
    CREDENTIALS,
    CONFIGURATION
  );

  console.log('Process completed');

  // Extract image data
  const img = facetecResponse.data.auditTrail[0];
  const imgLowQuality = facetecResponse.data.lowQualityAuditTrail[0];

  // Display results
  const containerResult = document.getElementById('container-result');
  const imageHigh = document.getElementById('image-high');
  const imageLow = document.getElementById('image-low');

  containerResult.style.display = 'flex';
  imageHigh.src = 'data:image/png;base64,' + img;
  imageLow.src = 'data:image/png;base64,' + imgLowQuality;
} catch (ex) {
  // ... error handling
}

Clean up resources

Always call end() in the finally block to properly release resources:

try {
  const response = await FAD_SDK.startFacetec(CREDENTIALS, CONFIGURATION);
  // ... handle success
} catch (ex) {
  // ... handle errors
} finally {
  // CRITICAL: Always clean up
  FAD_SDK.end();
}

Failing to call FAD_SDK.end() may result in memory leaks and can prevent subsequent SDK operations from working correctly.

Complete Example

Here’s the full implementation combining all steps:

import FadSDK from '@fad-producto/fad-sdk';
import { CREDENTIALS, CONFIGURATION, TOKEN } from './constants';

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

  const FAD_SDK = new FadSDK(TOKEN, options);

  try {
    const facetecResponse = await FAD_SDK.startFacetec(
      CREDENTIALS,
      CONFIGURATION
    );

    // PROCESS_COMPLETED
    console.log('Process completed');
    console.log(facetecResponse);

    const img = facetecResponse.data.auditTrail[0];
    const imgLowQuality = facetecResponse.data.lowQualityAuditTrail[0];
    const faceScan = facetecResponse.data.faceScan;

    // Display results
    const containerResult = document.getElementById('container-result');
    const imageId = document.getElementById('image-id') as HTMLImageElement;
    const imageFace = document.getElementById('image-face') as HTMLImageElement;

    containerResult.style.display = 'flex';
    imageId.src = 'data:image/png;base64, ' + img;
    imageFace.src = 'data:image/png;base64, ' + imgLowQuality;
  } catch (ex) {
    // PROCESS_ERROR
    console.log(ex);
    if (ex.code === FadSDK.Errors.Facetec.Session.CAMERA_NOT_RUNNING) {
      alert('Camera not supported, try another device');
    } else if (ex.code === FadSDK.Errors.Facetec.Session.INITIALIZATION_NOT_COMPLETED) {
      // Restart component
    } else {
      console.log(JSON.stringify(ex));
    }
  } finally {
    FAD_SDK.end();
  }
}

initProcess();

Common Patterns Across All Modules

The pattern you just learned applies to all FAD SDK modules:

Initialize

const FAD_SDK = new FadSDK(token, options);

Start Process

const response = await FAD_SDK.startModuleName(credentials, config);

Handle Results

// Access response.data for module-specific results
console.log(response.data);

Handle Errors

catch (ex) {
  // Check ex.code against FadSDK.Errors.ModuleName.*
}

Clean Up

finally {
  FAD_SDK.end();
}

Available SDK Methods

Now that you understand the core pattern, explore other modules:

Method	Module	Description
`startRegula()`	Capture-id&R	Document capture with Regula
`startAcuant()`	Capture-id&A	Document capture with Acuant
`startFacetec()`	Liveness-3D	3D liveness detection
`startSignature()`	Signature	Signature capture with video
`startVideoagreement()`	Videoagreement	Video recording with captions
`startVideotaping()`	Videotaping	Video with ID detection
`startCaptureId()`	Capture-id	Mexican document capture
`startIdentyFace()`	Liveness-3D&I	Identy liveness detection
`startIdentyFingerprints()`	Fingerprints&I	Fingerprint capture
`startLivenessToc()`	Liveness&T	TOC liveness detection

Each method requires module-specific credentials and configuration. Refer to individual module documentation for details.

Try Another Module: Document Capture

Let’s quickly see how the same pattern applies to document capture:

import FadSDK from '@fad-producto/fad-sdk';
import { TOKEN, CREDENTIALS, CONFIGURATION } from './capture-constants';

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

  const FAD_SDK = new FadSDK(TOKEN, options);
  
  try {
    const idData = true;  // Extract OCR data
    const idPhoto = true; // Extract face photo from ID

    const regulaResponse = await FAD_SDK.startRegula(
      CREDENTIALS,
      FadSDK.Constants.Regula.CaptureType.CAMERA_SNAPSHOT,
      idData,
      idPhoto,
      CONFIGURATION
    );

    if (regulaResponse.event === FadSDK.Constants.EventModule.MODULE_CLOSED) {
      alert('Module closed by the user');
      return;
    }

    console.log('Document captured');
    
    // Access document images
    const frontImage = regulaResponse.data.id.front;
    const backImage = regulaResponse.data.id.back;
    const facePhoto = regulaResponse.data.idPhoto;
    const ocrData = regulaResponse.data.idData.ocr;

    // Display in your UI
    document.getElementById('id-front').src = frontImage;
    document.getElementById('id-back').src = backImage;
    document.getElementById('face-photo').src = facePhoto;
    console.log('OCR:', ocrData);
  } catch (ex) {
    if (ex.code === FadSDK.Errors.Regula.CAMERA_PERMISSION_DENIED) {
      alert('Camera permission denied');
    } else if (ex.code === FadSDK.Errors.Regula.ID_PHOTO_NOT_FOUND) {
      alert('Face photo not found on document');
    } else if (ex.code === FadSDK.Errors.Regula.OCR_NOT_FOUND) {
      alert('Could not extract OCR data');
    } else {
      alert(JSON.stringify(ex));
    }
  } finally {
    FAD_SDK.end();
  }
}

captureDocument();

Next Steps

You now have a working FAD SDK integration! Here’s what to explore next:

Explore Modules

Learn about all available modules and their capabilities

Customization

Customize colors, fonts, and UI to match your brand

Error Handling

Deep dive into error codes and recovery strategies

Production Deployment

Best practices for deploying to production

Need Help?

Check out the example implementations in the FAD SDK repository for more complete examples of each module.

Remember to replace all placeholder credentials with your actual production credentials before deploying to production. Never commit credentials to version control.

Getting Started

Core Concepts

Modules

Integration Guides

Quick Start

Quick Start Guide

What You’ll Build

Step-by-Step Implementation

Error Response Structure

Complete Example

Common Patterns Across All Modules

Available SDK Methods

Try Another Module: Document Capture

Next Steps

Explore Modules

Customization

Error Handling

Production Deployment

Need Help?

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Modules

Integration Guides

​Quick Start Guide

​What You’ll Build

​Step-by-Step Implementation

​Error Response Structure

​Complete Example

​Common Patterns Across All Modules

​Available SDK Methods

​Try Another Module: Document Capture

​Next Steps

Explore Modules

Customization

Error Handling

Production Deployment

​Need Help?

Build docs developers (and LLMs) love

Quick Start Guide

What You’ll Build

Step-by-Step Implementation

Error Response Structure

Complete Example

Common Patterns Across All Modules

Available SDK Methods

Try Another Module: Document Capture

Next Steps

Need Help?