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.

For detailed event documentation and advanced configurations, refer to the complete Biometrics Event Reference.

Built with