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, UI components, and utilities enables biometric enrollment (face and voice), liveness checks, and user consent.
- Installation
- Basic Usage (Direct SDK Methods)
- Advanced Usage And Best Practices
- UI Components
- License
- More Information
- Quick Reference
Install the Biometry Web SDK via npm:
npm install biometry-sdkAfter 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');You can find an example in the example/ directory. The example demonstrates how you might integrate the BiometrySDK in a React component with the state.
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 IDYou 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).
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);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);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);
}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 }
);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);
}One common advanced scenario involves document authentication in enrollment face and face matching:
- Face Enrollment: Capture the user’s live face or the user uploads a picture of their identity document (front side with the face)
- Process Video: Capture the user’s live face
- Face Match: Compare the extracted face from the document with the user’s live face to verify identity.
Below is a possible flow (method names in your SDK may vary slightly depending on your integration setup):
// 1. Acquire user storage consent
await sdk.giveStorageConsent(true, userFullName);
// 2. Enroll or capture the user’s face
// (Either using enrollFace or processVideo, depending on your user flow)
const userFaceFile = new File([/* user selfie bytes */], 'image.jpg', { type: 'image/jpeg' });
const userVideoFile = new File([/* user selfie bytes */], 'video.mp4', { type: 'video/*' });
const enrollResponse = await sdk.enrollFace(userFaceFile, userFullName);
// 3. Acquire user authorization consent. It's required to use enrolled face for using biometric data.
await sdk.giveAuthorizationConsent(true, userFullName);
// 4. Face Match (Compare video face with user’s enrolled face)
const faceMatchResponse = await sdk.faceMatch(
userFaceFile,
userVideoFile,
userFullName
);
// 5. Evaluate the faceMatch result
if (faceMatchResponse.matchResult === 'match') {
console.log('User video face matches user’s live face. Identity verified!');
} else {
console.log('User video face does NOT match. Additional verification needed.');
}All SDK calls can throw errors for various reasons:
- Network/Connection Issues
- Invalid File Types
- No Face Detected (Face Enrollment)
- No Speech Detected (Voice Enrollment)
- Multiple Faces Detected (Face Enrollment)
- Liveness Check Failure (Process Video)
Always wrap calls in try/catch and provide user-friendly messages or fallback logic.
try {
const response = await sdk.faceMatch(...);
// handle success
} catch (error) {
// handle error
console.error('Face match error:', error);
}- Protect Your API Key: Avoid storing your API key in client-side code if possible. Use environment variables or server-side proxies.
- Obtain Explicit Consent: Ensure you have a transparent process for obtaining and storing user consent.
- Data Minimization: Only store data that is required for your use case.
- Regulatory Compliance: Check local regulations (GDPR, CCPA, etc.) for storing and processing biometric data.
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.
Option 1: Using npm (Recommended for full SDK usage)
- Install the SDK package via npm:
npm install biometry-sdk
- 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>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.
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>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.
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.
This project is licensed under the MIT License. See the LICENSE file for more details.
For more detailed information on Biometry’s API endpoints, parameters, and responses, visit the official Biometry API Documentation. If you have questions or need help, please reach out to our support team or create a GitHub issue.
-
UI Components:
-
<biometry-enrollment ...>(face enrollment) -
<process-video ...>(video enrollment) With these direct SDK methods, UI components, and advanced best practices (faceEnroll + faceMatch flows, reuse of video, error handling), you can build robust, privacy-conscious biometric solutions on your web application.
-