Biometrics by Steps Module

Overview

The Biometrics by Steps module provides a comprehensive, guided biometric verification workflow that combines ID validation with face biometrics. This module orchestrates multiple verification steps in a sequential manner, providing a complete identity verification solution with a streamlined user experience.

Key Features

Guided Workflow: Step-by-step verification process
ID Validation Integration: Built-in document verification
Face Biometrics: Advanced liveness detection and face matching
Backend Orchestration: Uses validation tokens from backend
Progress Tracking: Visual indicators for multi-step process
Flexible Configuration: Customize which steps are included
No Direct Token Required: Uses ID validation token
Comprehensive Results: Complete verification data in single response

Use Cases

Complete Onboarding

Full KYC process with document and biometric verification in one flow.

Account Recovery

Verify identity for account recovery or password reset scenarios.

High-Value Transactions

Multi-factor verification for sensitive operations or large transactions.

Compliance Verification

Meet regulatory requirements with comprehensive identity checks.

Hardware Requirements

Modern web browser with camera access
Device camera (mobile or desktop)
Good lighting conditions for optimal results
Stable internet connection
HTTPS protocol (required)

Installation

npm install @fad-producto/fad-sdk

Workflow Steps

The module typically includes the following steps:

Document Capture

Capture and validate government-issued ID documents (front and back).

Face Liveness

Perform liveness detection to ensure physical presence.

Face Matching

Match captured face with photo from ID document.

Validation

Backend validates all captured data and returns verification results.

The exact steps included depend on your backend configuration and the ID validation token provided.

Implementation

Import SDK

Import the FAD SDK:

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

Obtain ID Validation Token

Request an ID validation token from your backend:

async function getIdValidationToken(userId) {
  const response = await fetch('/api/biometrics/create-validation', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      userId,
      verificationType: 'full_biometric',
    }),
  });

  const data = await response.json();
  return data.idValidation;  // ID validation token
}

Initialize SDK Without Token

Create SDK instance without authentication token:

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

const FAD_SDK = new FadSDK(null, options);  // No token required

Start Biometric Workflow

Initiate the step-by-step verification process:

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

  const FAD_SDK = new FadSDK(null, options);
  
  try {
    // Get ID validation token from backend
    const idValidation = await getIdValidationToken(userId);

    // Start the biometric workflow
    const result = await FAD_SDK.startBiometrics(idValidation);

    console.log('Biometric verification completed:', result);

    // Send results to backend for final processing
    await submitVerificationResults(result);

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

Response Structure

{
  status: string,           // 'completed', 'failed', 'cancelled'
  validationId: string,     // Backend validation identifier
  results: {
    document: {
      front: string,        // Base64 image
      back?: string,        // Base64 image
      extracted: object,    // OCR data
      validation: object,   // Document validation results
    },
    face: {
      liveness: boolean,    // Liveness check result
      image: string,        // Base64 image
      quality: number,      // Quality score
    },
    matching: {
      score: number,        // Match score (0-100)
      matched: boolean,     // Whether face matches ID photo
    },
  },
  timestamp: string,        // Completion timestamp
  // Additional fields based on configuration
}

The exact response structure depends on your backend configuration and which verification steps were executed.

Error Handling

try {
  const result = await FAD_SDK.startBiometrics(idValidation);
} catch (ex) {
  if (ex.message.includes('Invalid validation')) {
    alert('Verification session expired. Please start again.');
    // Request new validation token
  }
}

Usage Examples

Complete Flow
With Progress Tracking
With Validation
With Retry Logic

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

async function performBiometricVerification(userId) {
  // 1. Request validation token from backend
  const tokenResponse = await fetch('/api/biometrics/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ userId }),
  });

  const { idValidation } = await tokenResponse.json();

  // 2. Initialize SDK
  const FAD_SDK = new FadSDK(null, {
    environment: FadSDK.getFadEnvironments().UATHA,
  });

  try {
    // 3. Execute biometric workflow
    const result = await FAD_SDK.startBiometrics(idValidation);

    if (result.status !== 'completed') {
      throw new Error(`Verification ${result.status}`);
    }

    // 4. Submit results to backend
    await fetch('/api/biometrics/complete', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        userId,
        result,
        timestamp: new Date().toISOString(),
      }),
    });

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

async function verificationWithProgress(userId) {
  const progressSteps = [
    { step: 'init', label: 'Initializing...' },
    { step: 'document', label: 'Capturing ID...' },
    { step: 'liveness', label: 'Verifying liveness...' },
    { step: 'matching', label: 'Matching face...' },
    { step: 'complete', label: 'Finalizing...' },
  ];

  const FAD_SDK = new FadSDK(null, {
    environment: FadSDK.getFadEnvironments().UATHA,
  });

  try {
    // Show progress
    updateProgress(progressSteps[0]);

    // Get token
    const idValidation = await getIdValidationToken(userId);
    updateProgress(progressSteps[1]);

    // Start workflow
    const result = await FAD_SDK.startBiometrics(idValidation);

    // Check result
    if (result.status === 'completed') {
      updateProgress(progressSteps[4]);
      showSuccess('Verification completed!');
      return result;
    } else {
      showError(`Verification ${result.status}`);
      return null;
    }
  } catch (error) {
    showError('Verification failed: ' + error.message);
    throw error;
  } finally {
    FAD_SDK.end();
  }
}

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

  try {
    const idValidation = await getIdValidationToken(userId);
    const result = await FAD_SDK.startBiometrics(idValidation);

    if (result.status !== 'completed') {
      throw new Error('Verification not completed');
    }

    // Validate results
    const validation = validateResults(result);

    if (!validation.valid) {
      throw new Error(validation.errors.join(', '));
    }

    // Additional checks
    if (result.results.matching.score < 80) {
      throw new Error('Face match score too low');
    }

    if (!result.results.face.liveness) {
      throw new Error('Liveness check failed');
    }

    console.log('All validations passed');
    return result;
  } finally {
    FAD_SDK.end();
  }
}

function validateResults(result) {
  const errors = [];

  if (!result.results.document) {
    errors.push('Document data missing');
  }

  if (!result.results.face) {
    errors.push('Face data missing');
  }

  if (!result.results.matching) {
    errors.push('Matching data missing');
  }

  return {
    valid: errors.length === 0,
    errors,
  };
}

async function verifyWithRetry(userId, maxRetries = 2) {
  let attempt = 0;

  while (attempt <= maxRetries) {
    const FAD_SDK = new FadSDK(null, {
      environment: FadSDK.getFadEnvironments().UATHA,
    });

    try {
      console.log(`Verification attempt ${attempt + 1}/${maxRetries + 1}`);

      // Get fresh token for each attempt
      const idValidation = await getIdValidationToken(userId);

      const result = await FAD_SDK.startBiometrics(idValidation);

      if (result.status === 'completed') {
        console.log('Verification successful');
        return result;
      }

      if (result.status === 'cancelled') {
        console.log('User cancelled');
        return null;
      }

      // Failed, retry if attempts remaining
      attempt++;
      if (attempt <= maxRetries) {
        console.log('Retrying...');
        await new Promise(resolve => setTimeout(resolve, 2000));
      }

    } catch (error) {
      console.error(`Attempt ${attempt + 1} error:`, error.message);
      attempt++;

      if (attempt > maxRetries) {
        throw new Error(`Verification failed after ${maxRetries + 1} attempts`);
      }

      await new Promise(resolve => setTimeout(resolve, 2000));
    } finally {
      FAD_SDK.end();
    }
  }

  throw new Error('Max retries exceeded');
}

Backend Integration

Creating Validation Tokens

Your backend should provide an endpoint to create ID validation tokens:

// Backend example (Node.js/Express)
app.post('/api/biometrics/create-validation', async (req, res) => {
  const { userId, verificationType } = req.body;

  // Create validation token with FAD backend
  const idValidation = await fadBackend.createValidation({
    userId,
    steps: getVerificationSteps(verificationType),
    expiresIn: 3600,  // 1 hour
  });

  res.json({ idValidation });
});

Processing Results

Handle verification results on your backend:

app.post('/api/biometrics/complete', async (req, res) => {
  const { userId, result } = req.body;

  // Validate result authenticity
  const isValid = await fadBackend.validateResult(result);

  if (!isValid) {
    return res.status(400).json({ error: 'Invalid result' });
  }

  // Store verification data
  await db.saveVerification({
    userId,
    documentData: result.results.document,
    faceData: result.results.face,
    matchingScore: result.results.matching.score,
    timestamp: result.timestamp,
  });

  // Update user status
  await db.updateUserStatus(userId, 'verified');

  res.json({ success: true });
});

Verification Steps Configuration

Typical configurations for different use cases:

Basic Verification
Standard KYC
Enhanced Security

const steps = {
  document: {
    enabled: true,
    sides: ['front'],  // Front only
  },
  liveness: {
    enabled: true,
    mode: 'basic',
  },
  matching: {
    enabled: false,
  },
};

Duration: ~1-2 minutes

const steps = {
  document: {
    enabled: true,
    sides: ['front', 'back'],
    ocr: true,
  },
  liveness: {
    enabled: true,
    mode: 'standard',
  },
  matching: {
    enabled: true,
    threshold: 75,
  },
};

Duration: ~2-3 minutes

const steps = {
  document: {
    enabled: true,
    sides: ['front', 'back'],
    ocr: true,
    validation: 'enhanced',
  },
  liveness: {
    enabled: true,
    mode: 'advanced',
  },
  matching: {
    enabled: true,
    threshold: 85,
    multipleCaptures: true,
  },
};

Duration: ~3-5 minutes

Best Practices

Token Expiration

Set appropriate token expiration (30-60 minutes) to balance security and user experience.

Progress Indicators

Show clear progress indicators so users know what to expect and how long it will take.

Error Recovery

Implement clear error messages and easy retry mechanisms for failed steps.

User Guidance

Provide instructions before each step to improve success rates.

Quality Thresholds

Recommended thresholds for different security levels:

Security Level	Document Quality	Face Quality	Match Score
Basic	> 60%	> 60%	> 70
Standard	> 75%	> 75%	> 80
High	> 85%	> 85%	> 90
Maximum	> 90%	> 90%	> 95

Security Considerations

This module handles sensitive biometric and identity data. Implement comprehensive security measures.

Generate validation tokens server-side only
Use HTTPS for all communications
Validate results on backend before trusting
Implement rate limiting on token creation
Encrypt stored biometric data
Follow GDPR/CCPA compliance for biometric data
Maintain audit logs of all verifications
Set appropriate token expiration times
Never expose backend credentials client-side
Implement fraud detection mechanisms

Troubleshooting

Validation Token Invalid

Token may have expired (check expiration)
Token format incorrect
Backend service unavailable
Request new token from backend

Workflow Fails at Specific Step

Check error message for specific step
Verify hardware requirements for that step
Ensure good lighting/conditions
Review backend logs for validation issues

Face Matching Fails

Ensure person in selfie matches ID photo
Improve lighting conditions
Remove glasses/obstructions
Lower matching threshold if appropriate

Document Capture Issues

Ensure good lighting on document
Keep document flat and fully visible
Clean camera lens
Avoid glare on document surface

Monitoring and Analytics

Track these metrics for workflow optimization:

Completion Rate: Percentage of started verifications completed
Step Failure Rates: Which steps fail most often
Average Duration: Time to complete verification
Retry Rates: How often users retry steps
Quality Scores: Average quality of captures
Matching Scores: Distribution of face match scores

Fad Web 4 - Ticket-based workflow orchestration
Liveness-3D - Standalone liveness detection
Capture-id&R - Standalone document capture
Videotaping - Video-based ID verification

Getting Started

Core Concepts

Modules

Integration Guides

Biometrics by Steps Module

Overview

Key Features

Use Cases

Complete Onboarding

Account Recovery

High-Value Transactions

Compliance Verification

Hardware Requirements

Installation

Workflow Steps

Implementation

Response Structure

Error Handling

Usage Examples

Backend Integration

Creating Validation Tokens

Processing Results

Verification Steps Configuration

Best Practices

Token Expiration

Progress Indicators

Error Recovery

User Guidance

Quality Thresholds

Security Considerations

Troubleshooting

Monitoring and Analytics

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Modules

Integration Guides

​Overview

​Key Features

​Use Cases

Complete Onboarding

Account Recovery

High-Value Transactions

Compliance Verification

​Hardware Requirements

​Installation

​Workflow Steps

​Implementation

​Response Structure

​Error Handling

​Usage Examples

​Backend Integration

​Creating Validation Tokens

​Processing Results

​Verification Steps Configuration

​Best Practices

Token Expiration

Progress Indicators

Error Recovery

User Guidance

​Quality Thresholds

​Security Considerations

​Troubleshooting

​Monitoring and Analytics

​Related Modules

Build docs developers (and LLMs) love

Overview

Key Features

Use Cases

Hardware Requirements

Installation

Workflow Steps

Implementation

Response Structure

Error Handling

Usage Examples

Backend Integration

Creating Validation Tokens

Processing Results

Verification Steps Configuration

Best Practices

Quality Thresholds

Security Considerations

Troubleshooting

Monitoring and Analytics

Related Modules