OneSDKModules

Biometrics Module

The Biometrics Module enables selfie/video capture and comparison against previously captured ID documents. It automatically integrates with your configured Biometrics provider (Onfido or Incode).

Quick Implementation

1

Add HTML Element

First, add a container element to your HTML:

1<div id="biometrics"></div>

You may need to adjust your Content Security Policy (CSP) settings to allow the IDV module to function correctly. Refer to this page for more details.

2

Initialize Module

Create and mount the biometrics component:

1const biometrics = oneSdk.component("biometrics");
2biometrics.mount("#biometrics");
3

Handle Events

Set up event listeners for biometric operations:

1biometrics.on("detection_complete", (event) => {
2  console.log("Biometric capture completed");
3});
4
5biometrics.on("results", (results) => {
6  console.log("Verification results:", results);
7});

Provider-Specific Implementation

Implementation Flow
  1. Mount component
  2. User clicks “Upload Recording”
  3. Receive detection_complete event
  4. Background processing begins
  5. Receive results event
Example Usage
1const biometrics = oneSdk.component('biometrics');
2
3// Mount component
4biometrics.mount("#biometrics");
5
6// Handle recording upload
7biometrics.on('detection_complete', (event) => {
8  console.log('Recording uploaded');
9});

Biometrics Events

When the Biometrics component is successfully mounted, it will emit a ready event.

To listen to this event, use:

1  biometrics.on('ready', () => {
2    console.log('idv component is ready')
3  });

When the Biometrics component successfully detects your information, it will emit a detection_complete event. This event will be emitted immediately before results. To listen to this event, use:

1  biometrics.on('detection_complete', () => {
2    // programatically unmount your component
3    setMounted(false);
4  })

The end-user data is being submitted during this event. To listen to this event, use:

1biometrics.on('success', 
2  (checkStatus, document, entityId) => {
3    // you can extract information emitted from success event
4    // and use it to your own use
5  }
6)

where the data types for the parameters are:

1  checkStatus: 'COMPLETE' | 'FAILED',
2  document: Object
3  entityId: string

checkStatus will consist of either COMPLETE or FAILED, where

  • “COMPLETE”: The process and the check results are ready.

  • “FAILED”: The process is done but there was a genuine failure validating the captured ID and face.

document: the document object generated after the OCR extract

entityId: FrankieOne’s internal reference for the individual

The component has run unsuccessfully. You can handle this event using a custom loading spinner or additional styles. To listen to this event, use:

1biometrics.on("detection_failed", () => {
2  // programatically unmount your component
3  setMounted(false);
4});

To listen to this event, use:

1biometrics.on("input_required", (information, checkStatus) => {
2  if (checkStatus === "WAITING_SELFIE_UPLOAD") {
3    console.log("waiting for selfie capture");
4  }
5});

input_required will emit entityId and current status of the process, such as:

  • waiting for Document upload WAITING_DOC_UPLOAD
  • waiting for selfie upload WAITING_SELFIE_UPLOAD

  • uploaded document has invalid type AWAITING_DOCUMENT_UPLOAD_INVALID_TYPE

  • or the process is either incomplete or interrupted INCOMPLETE / INTERRUPTED.

For Incode, a lack of camera access permissions triggers the INTERRUPTED event.

On error events, we throw all events from vendor back to you. To listen to this event, use:

1biometrics.on('error', (e) => {
2console.log(e.message, e.payload)
3})

If you’re using Incode, the possible messages are: InternalServerError, OSVersionNotSupported, and browserNotSupported

Implementation Best Practices

Mobile Optimization
1<meta 
2  name="viewport" 
3  content="width=device-width, initial-scale=1.0" 
4  charset="UTF-8" 
5/>

Ensure proper viewport settings for mobile devices.

Error Handling
1biometrics.on('error', (error) => {
2  console.error('Biometrics error:', error);
3  // Implement user-friendly error handling
4});
Testing Tip

During development, test with both providers (if applicable) to ensure consistent behavior across different biometric implementations.