biometry-sdk

Overview

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.

Table of Contents:

- Installation
- Basic Usage (Direct SDK Methods)
- Sessions
- Consents
- 1.1 Give Authorization Consent
- 1.2 Give Storage Consent
- Face Enrollment
- Voice Enrollment
- Process Video
- Face Match
- DocAuth
- Advanced Usage And Best Practices
- Typical FaceMatch Flow
- Error Handling
- Header Retrieval
- Security And Privacy Considerations
- License
- More Information
- Quick Reference

Installation

Install the Biometry Web SDK via npm:
``bash
npm install biometry-sdk
`

Basic Usage (Direct SDK Methods)

After installing, import and instantiate the BiometrySDK:
`typescript
import { BiometrySDK } from 'biometry-sdk';

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

$3

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.

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.

Note: Use sessions generated by Biometry for API calls. Biometry sessions always have sess_ prefix. Do not use own uuids or any other values.

Example:
`javascript
const response = await sdk.startSession(); // returns uuid with sess_ prefix
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 in X-Session-Id header 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

$3

You must obtain user authorization consent before performing any biometric operations (Face Recognition, Voice Recognition, etc.):
`javascript
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).

$3

You must obtain user consent before storing biometric data (Face Enrollment, Voice Enrollment):
`javascript
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:
`javascript
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:
`javascript
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:
`javascript
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);
}
`

$3

Use matchFaces to compare a reference image (e.g., a document or a captured selfie) with a face from a video:
`javascript
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:
`javascript
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 }
);
`

$3


DocAuth is a way to authenticate a user's document. It is useful when you want to authenticate a user's document.
`javascript
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, inHouseCheck: true });
console.log('DocAuth Response:', response);
} catch (error) {
console.error('Error checking document:', error);
}
`

Advanced Usage And Best Practices

$3

One common advanced scenario involves document authentication in enrollment face and face matching:
1. Face Enrollment: Capture the user's live face or the user uploads a picture of their identity document (front side with the face)
2. Process Video: Capture the user's live face
3. 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):
`javascript
// 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.');
}
`

$3

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.
`javascript
try {
const response = await sdk.faceMatch(...);
// handle success
} catch (error) {
// handle error
console.error('Face match error:', error);
}
`

$3

In addition to the response body, all SDK calls also return response headers.
This is useful for retrieving metadata such as request and session IDs, or debugging information.

Each API call returns an object of type:

`ts
export interface ApiResponse {
body: T;
headers: Record;
}
`
For example, when calling the processVideo method, you can access both the response data and headers:
`ts
try {
const response = await sdk.processVideo(videoFile, "12345678", "John Doe");

// Access the response body
console.log("Process video result:", response.body);

// Access headers (e.g., request ID)
console.log("Request ID:", response.headers["x-request-id"]);
} catch (error) {
console.error("Process video failed:", error);
}
``
This pattern applies to all SDK methods, so you can always extract useful metadata from headers in addition to the main response.

$3

1. Protect Your API Key: Avoid storing your API key in client-side code if possible. Use environment variables or server-side proxies.
2. Obtain Explicit Consent: Ensure you have a transparent process for obtaining and storing user consent.
3. Data Minimization: Only store data that is required for your use case.
4. Regulatory Compliance: Check local regulations (GDPR, CCPA, etc.) for storing and processing biometric data.

License

This project is licensed under the MIT License. See the LICENSE file for more details.

More Information

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.