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 utilities enables biometric enrollment (face and voice), liveness checks, and user consent.

We also have UI component library for React. You can you this SDK in combination with it.

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
DocAuth: You can check the validity of someones documents through our DocAuth API

Getting Started

Prerequisites

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

Obtain an API token from the Biometry service.
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);
}

You can find more information in our Github repository

biometry-react-components

React UI component library with tools to work with camera and microphone for easier integration of Biometry services.

NPM Link

Installation

npm install biometry-sdk

Peer Dependencies

This library requires React 16.8.0 or higher (supports React Hooks):

{
  "peerDependencies": {
    "react": ">=16.8.0",
    "react-dom": ">=16.8.0"
  }
}

Components

DocScan

Captures ID documents, driver license and etc. Suitable component for Biometry’s DocAuth.

import { DocScan } from 'biometry-react-components';

function DocumentCapture() {
  const handleCapture = (file: File) => {
    console.log('Captured document:', file);
    // Send file to your endpoint that will process DocAuth (we recommend this way, because you will not expose the API key on client side)
    // or
    // const response = await sdk.checkDocAuth(file, userFullName, { sessionId });
  };

  return <DocScan onCapture={handleCapture} />;
}

Props

Prop	Type	Default	Description
`onCapture`	`(file: File) => void`	required	Callback with captured image file
`rectWidth`	`number`	`640`	Width of camera area
`rectHeight`	`number`	`400`	Height of camera area
`className`	`string`	-	Custom CSS class
`style`	`React.CSSProperties`	-	Custom inline styles
`noShadow`	`boolean`	`false`	Remove shadow and border radius

FaceCapture

Captures facial images with an oval guidance overlay. Ideal for Face Match and Face Enrollment.

import { FaceCapture } from 'biometry-react-components';

function FaceCapture() {
  const handleCapture = (file: File) => {
    console.log('Captured face:', file);
    // Send file to your endpoint that will process DocAuth (we recommend this way, because you will not expose the API key on client side)
    // or
    // const response = await sdk.enrollFace(file, 'John Doe');
  };

  return <FaceCapture onCapture={handleCapture} />;
}

Props

Prop	Type	Default	Description
`onCapture`	`(file: File) => void`	required	Callback with captured image file
`rectWidth`	`number`	`360`	Width of camera area
`rectHeight`	`number`	`576`	Height of camera area
`className`	`string`	-	Custom CSS class
`style`	`React.CSSProperties`	-	Custom inline styles
`noShadow`	`boolean`	`false`	Remove shadow and border radius

FaceRecorder

Records video with facial guidance overlay. This component could be used for Process Video

import { FaceRecorder } from 'biometry-react-components';

function FaceRecorder() {
  const handleCapture = (file: File, phrase: string) => {
    console.log('Captured video:', file);
    console.log('Phrase:', phrase);
    // Send file to your endpoint that will process DocAuth (we recommend this way, because you will not expose the API key on client side)
    // or
    // const response = await sdk.processVideo(file, phrase, userFullName);
  };

  return <FaceRecorder onCapture={handleCapture} />;
}

Props

Prop	Type	Default	Description
`onCapture`	`(file: File) => void`	required	Callback with captured video file
`rectWidth`	`number`	`360`	Width of camera area
`rectHeight`	`number`	`576`	Height of camera area
`className`	`string`	-	Custom CSS class
`style`	`React.CSSProperties`	-	Custom inline styles
`noShadow`	`boolean`	`false`	Remove shadow and border radius

VoiceRecorder

Records audio with real-time waveform visualization and adaptive quality settings. Use this for Voice Enrollment

import { VoiceRecorder } from 'biometry-react-components';

function VoiceRecorder() {
  const handleCapture = (file: File, phrase: string) => {
    console.log('Captured audio:', file);
    console.log('Phrase:', phrase);
    // Send file to your endpoint that will process DocAuth (we recommend this way, because you will not expose the API key on client side)
    // or
    // const response = await sdk.enrollVoice(file, 'John Doe');
  };

  return <VoiceRecorder onCapture={handleCapture} />;
}

Props

Prop	Type	Default	Description
`onCapture`	`(file: File) => void`	required	Callback with captured audio file
`rectWidth`	`number`	`360`	Width of component area
`rectHeight`	`number`	`undefined`	Height of component area (optional)
`className`	`string`	-	Custom CSS class
`style`	`React.CSSProperties`	-	Custom inline styles
`noShadow`	`boolean`	`false`	Remove shadow and border radius

Custom Hooks

useRecorder

A powerful hook for recording audio and video with adaptive quality settings and automatic format detection.

import { useRecorder } from 'biometry-react-components';

function CustomRecorder() {
  const mediaStream = // ... your media stream

  const {
    isRecording,
    startRecording,
    stopRecording,
    cancelRecording
  } = useRecorder(mediaStream, "video", (blob) => {
    console.log('Recording completed:', blob);
  });

  return (
    ...
  );
}

Parameters

Parameter	Type	Description
`stream`	`MediaStream \| null`	Media stream to record from
`type`	`"audio" \| "video"`	Type of media to record
`onStopRecording`	`(blob: Blob) => void`	Callback when recording stops

Returns

Property	Type	Description
`isRecording`	`boolean`	Current recording state
`startRecording`	`() => void`	Start recording function
`stopRecording`	`() => void`	Stop recording function
`cancelRecording`	`() => void`	Cancel recording function

usePermissions

Hook for managing camera and microphone permissions with adaptive quality constraints.

import usePermissions from 'biometry-react-components';

function PermissionManager() {
  const {
    permission,
    stream,
    stopStreamTracks,
    requestPermissions,
    isLoading
  } = usePermissions({ rectWidth: 1280, rectHeight: 720 });

  if (isLoading) return <div>Loading...</div>;

  if (!permission) {
    return <button onClick={requestPermissions}>Grant Permissions</button>;
  }

  return <div>Camera and microphone access granted!</div>;
}

Parameters

Parameter	Type	Default	Description
`rectWidth`	`number`	`1920`	Desired video width
`rectHeight`	`number`	`1080`	Desired video height

Returns

Property	Type	Description
`permission`	`boolean`	Permission granted status
`stream`	`MediaStream \| null`	Active media stream
`stopStreamTracks`	`() => void`	Stop all media tracks
`requestPermissions`	`() => Promise<void>`	Request camera/microphone permissions
`isLoading`	`boolean`	Loading state during permission request

useAudioPermissions

Specialized hook for audio-only permissions with optimized audio constraints.

import useAudioPermissions from 'biometry-react-components';

function AudioPermissionManager() {
  const {
    permission,
    stream,
    stopStreamTracks,
    requestPermissions,
    isLoading
  } = useAudioPermissions();

  if (isLoading) return <div>Loading...</div>;

  if (!permission) {
    return <button onClick={requestPermissions}>Grant Microphone Access</button>;
  }

  return <div>Microphone access granted!</div>;
}

Returns

Property	Type	Description
`permission`	`boolean`	Audio permission granted status
`stream`	`MediaStream \| null`	Active audio stream
`stopStreamTracks`	`() => void`	Stop all audio tracks
`requestPermissions`	`() => Promise<void>`	Request microphone permissions
`isLoading`	`boolean`	Loading state during permission request

Web SDK

biometry-web-sdk

Features

Getting Started

Prerequisites

Example

Installation

Basic Usage (Direct SDK Methods)

1. Sessions

2. Consents

2.1 Give Authorization Consent

2.2 Give Storage Consent

3. Face Enrollment

4. Voice Enrollment

5. Process Video

6. Face match

7. DocAuth

biometry-react-components

Installation

Peer Dependencies

Components

DocScan

Props

FaceCapture

Props

FaceRecorder

Props

VoiceRecorder

Props

Custom Hooks

useRecorder

Parameters

Returns

usePermissions

Parameters

Returns

useAudioPermissions

Returns