Skip to content
Biometry

Web SDK

biometry-web-sdk

The biometry-web-sdk is a software development kit designed to simplify the integration of Biometry’s API services into your web application. Providing tools and UI components enables biometric enrollment (face and voice), liveness checks, and user consent.

Features

  • Consent management: Ask a permission to store their biometric data for authentication using Biometry.
  • Biometric Authentication: Easily authenticate users with biometric data such as voice and face recognition.
  • Face match: Compares extracted image from user’s personal document with the frame from video.
  • Video Processing: Upload and process video files for biometric verification

Getting Started

Prerequisites

Before you can start using the biometry-web-sdk package, you need to:

  1. Obtain an API token from the Biometry service.
  2. Ensure your client side environment is set up (any web framework).

Example

You can find an example in the example/ directory in the Github repository. The example demonstrates how you might integrate the BiometrySDK in a React component with the state.

Installation

To install simply run:

npm install biometry-sdk

Basic Usage (Direct SDK Methods)

After installing, import and instantiate the BiometrySDK:

import { BiometrySDK } from "biometry-sdk";


// Initialize the SDK with your API key
const sdk = new BiometrySDK("YOUR_API_KEY");

1. Sessions

Session is a way to group transactions together. It is useful when you want to group transactions that are related to each other. For example, you can start a session and then use the session ID to link transactions within a unified group.

const response = await sdk.startSession();
const sessionId = response.data;


const voiceFile = new File([/* voice audio bytes */], 'voice.wav', { type: 'audio/wav' });
const faceFile = new File([/* face image bytes */], 'face.jpg', { type: 'image/jpeg' });


// Use the session ID to link transactions within a unified group
await sdk.giveStorageConsent(true, 'John Doe', { sessionId });
await sdk.enrollFace(faceFile, 'John Doe', { sessionId });
await sdk.enrollVoice(voiceFile, 'John Doe', { sessionId });


// Go to the Results page in your dashboard and see the transactions grouped by the session ID

2. Consents

You must obtain user authorization consent before performing any biometric operations (Face Recognition, Voice Recognition, etc.):

await sdk.giveAuthorizationConsent(true, 'John Doe');
// or
sdk.giveAuthorizationConsent(true, 'John Doe').then(() => {
  console.log('Consent given');
});
  • The first argument (true) indicates that the user has granted consent.
  • The second argument is the user’s full name (used for record-keeping within Biometry).

You must obtain user consent before storing biometric data (Face Enrollment, Voice Enrollment):

await sdk.giveStorageConsent(true, 'John Doe');
// or
sdk.giveStorageConsent(true, 'John Doe').then(() => {
  console.log('Consent given');
});
  • The first argument (true) indicates that the user has granted consent.
  • The second argument is the user’s full name (used for record-keeping within Biometry).

3. Face Enrollment

Enroll a user’s face for future recognition or matching:

const faceFile = new File([/* face image bytes */], 'face.jpg', { type: 'image/jpeg' });


await sdk.giveStorageConsent(true, 'John Doe');
const faceResponse = await sdk.enrollFace(faceFile, 'John Doe');
console.log('Face Enrollment Response:', faceResponse);

4. Voice Enrollment

Enroll a user’s voice for future authentication checks:

const voiceFile = new File([/* voice audio bytes */], 'voice.wav', { type: 'audio/wav' });


await sdk.giveStorageConsent(true, 'John Doe');
const voiceResponse = await sdk.enrollVoice(voiceFile, 'John Doe');
console.log('Voice Enrollment Response:', voiceResponse);

5. Process Video

Process a user’s video for liveness checks and identity authorization:

const videoFile = new File([/* file parts */], 'video.mp4', { type: 'video/mp4' });
const phrase = "one two three four five six";
const userFullName = 'John Doe';


await sdk.giveAuthorizationConsent(true, userFullName);


try {
  const response = await sdk.processVideo(videoFile, phrase, userFullName);
  console.log('Process Video Response:', response);
} catch (error) {
  console.error('Error processing video:', error);
}

6. Face match

Use matchFaces to compare a reference image (e.g., a document or a captured selfie) with a face from a video:

const faceFile = new File([/* face image bytes */], 'face.jpg', { type: 'image/jpeg' });
const videoFile = new File([/* file parts */], 'video.mp4', { type: 'video/mp4' });
const userFullName = 'John Doe';


const faceMatchResponse = await sdk.faceMatch(
  faceFile,
  videoFile,
  userFullName
);

You can also reuse a video that was previously processed with the processVideo method by passing the same sessionId:

const sessionId = await sdk.startSession();


// First, process a video with a sessionId
const processVideoResponse = await sdk.processVideo(videoFile, phrase, userFullName, { sessionId });


// Later, reuse the same video for face matching by providing the sessionId
const faceMatchResponse = await sdk.faceMatch(
  faceFile,
  null, // No need to pass the video file again
  userFullName,
  true, // usePrefilledVideo
  { sessionId }
);

7. DocAuth

DocAuth is a way to authenticate a user’s document. It is useful when you want to authenticate a user’s document.

const sessionId = await sdk.startSession();


const documentFile = new File([/* file parts */], 'document.jpg', { type: 'image/jpeg' });
const userFullName = 'John Doe';


await sdk.giveAuthorizationConsent(true, userFullName, { sessionId });


try {
  const response = await sdk.checkDocAuth(documentFile, userFullName, { sessionId });
  console.log('DocAuth Response:', response);
} catch (error) {
  console.error('Error checking document:', error);
}

UI Components

In addition to direct SDK methods, the Biometry Web SDK offers reusable Web Components that handle user interactions (camera, video recording, error states) automatically. The Biometry Web SDK includes reusable, customizable web components for crucial features. These components are easy to embed into your application and handle the most common biometric operations with minimal setup.

Integration

Option 1: Using npm (Recommended for full SDK usage)

  1. Install the SDK package via npm:
    Terminal window
    npm install biometry-sdk
  2. Import the component in your index.js or equivalent JavaScript file:
    index.js
    import "./node_modules/biometry-sdk/dist/biometry-sdk.esm.js";

Option 2: Using CDN (Quick Integration)

<script
  type="module"
  src="https://cdn.jsdelivr.net/npm/biometry-sdk/dist/biometry-sdk.esm.js"
></script>

Face Enrollment Component

This component provides an intuitive interface for enrollment users with their cameras. It integrates directly with the BiometrySDK backend, managing camera capture, consent checks, and error handling.

Usage

Required attributes:

  • api-key: Your Biometry API key.
  • user-fullname: The user’s full name (used in data storage and consent).

Slots:

  • video: Your custom <video> element.
  • button: Custom capture button.
  • loading, success, error-no-face, error-multiple-faces, error-not-centered, error-other: Custom UI messages for different states.

Basic Usage

<biometry-enrollment api-key="your-api-key" user-fullname="John Doe">
</biometry-enrollment>

Advanced Usage

<biometry-enrollment api-key="your-api-key" user-fullname="John Doe">
  <video
    slot="video"
    autoplay
    playsinline
    style="width: 100%; border-radius: 10px;"
  ></video>
  <button slot="button" style="padding: 10px 20px; font-size: 16px;">
    Capture
  </button>


  <!-- Custom Status Messages -->
  <div slot="loading">Please wait while we process your photo...</div>
  <div slot="success">Congratulations! You have been enrolled.</div>
  <div slot="error-no-face">
    No face detected. Make sure your face is visible.
  </div>
  <div slot="error-multiple-faces">
    Multiple faces detected. Please try again alone.
  </div>
  <div slot="error-not-centered">
    Align your face with the center of the screen.
  </div>
  <div slot="error-other">Oops! Something went wrong. Please try again.</div>
</biometry-enrollment>

Process Video Component

The Process Video component enables you to record, upload, and process a video within your application. It integrates with Biometry’s services to check liveness and authorize the user.

Usage

Basic Usage

<process-video api-key="your-api-key" user-fullname="John Doe"></process-video>

Advanced Usage

<process-video api-key="eyJhb...apikey" user-fullname="John Doe">
  <!-- Custom video element -->
  <video slot="video" muted playsinline style="border-radius: 1rem;"></video>


  <!-- Custom buttons -->
  <button slot="record-button">Custom Record</button>
  <button slot="stop-button">Custom Stop</button>


  <!-- Custom file input -->
  <input slot="file-input" type="file" accept="video/*" />


  <!-- Custom submit button -->
  <button slot="submit-button">Custom Submit</button>


  <!-- Custom messages -->
  <div slot="loading">Processing...</div>
  <div slot="error">An error occurred. Please try again.</div>
  <div slot="success">Video submitted successfully!</div>
</process-video>

Note:

  • All default elements and messages are functional out-of-the-box.
  • Replace slots if you want to customize the UI or functionality.
  • Call giveConsent() before using any biometric methods to ensure compliance with data processing requirements.

You can find more information in our Github repository