OneSDKModules

IDV Module

The IDV Module provides an all-in-one solution for implementing OCR and Biometrics in your application’s onboarding flow. It seamlessly integrates with vendor SDKs and automatically handles all necessary API calls between FrankieOne and vendor systems.

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.

Vendor Implementations

1

Country Selection

Users select their country of origin

2

Document Selection

Users choose their identification document type

3

Document Upload

Users capture or upload their chosen document

4

Biometrics Process

System prepares for biometric capture

5

Biometric Capture

Users complete their biometric verification

Onfido provides a complete in-browser verification experience without requiring device switching.

Configuring Accepted Documents and Countries

Using Onfido, we can set document and country selection on document capture part of IDV. The customization options available all relate to the country and document type selection screen. By default, the selection screen is shown with the country selection being empty.

Depending on the customization options defined in this step, either the country or document type selection screens might not be shown:

  • The country selection screen will not be shown if only 1 country is selected or if only passports are allowed
  • The document selection screen will not be shown if only 1 document type is specified

Set Document & Country Selection

During the initialisation of OneSdk instance, you can specify accepted documents & countries.

1const oneSdk = await OneSdk({
2  // Session object containing authentication details
3  session: sessionObjectFromBackend,
4  // Set environment mode
5  mode: "production", 
6  recipe: {
7    idv: {
8      // Configure accepted document types and countries
9      documents: [
10        {
11          type: 'PASSPORT',
12          countries: ['NZL'], // New Zealand passports only
13        },
14        {
15          type: 'DRIVERS_LICENCE', 
16          countries: ['NZL'], // New Zealand driver's licenses only
17        },
18      ],
19      // Specify Onfido as the IDV provider
20      provider: {
21        name: "onfido"
22      }
23    }
24  }
25});
26
27// Initialize the IDV flow
28const idv = oneSdk.flow("idv");
29// Mount the IDV component to specified HTML element
30idv.mount("#html-element");

documents is an array of object, where:

1  // Type definition for OCR configuration options
2  type OCRRecipeOptions = {
3    // Optional array of accepted document types and countries
4    documents?: Array<{
5      type: DocumentType;     // Document type enum value
6      countries?: Array<string>; // ISO country codes
7    }>;
8    // Provider configuration
9    provider: {
10      name: 'onfido',  // Currently only supports Onfido
11    }
12  }
13
14  // Supported document type options
15  enum DocumentType = {
16    PASSPORT = 'PASSPORT'           // Standard passports
17    NATIONAL_HEALTH_ID = 'NATIONAL_HEALTH_ID'  // Health ID cards
18    NATIONAL_ID = 'NATIONAL_ID'     // National ID cards
19    DRIVERS_LICENCE = 'DRIVERS_LICENCE' // Driver's licenses
20  }
Due to provider limitations, only one country can be specified in the `countries` array.

For example, if you attempt to set different countries for different document types like this:

1      documents: [
2        {
3          type: 'PASSPORT',
4          countries: ['NZL'], // New Zealand passports
5        },
6        {
7          type: 'DRIVERS_LICENCE',
8          countries: ['SGP'], // Singapore driver's licenses - this will cause fallback
9        },
10      ],

Onfido will fallback to displaying the selection screen for the complete list of documents supported within the selection screens.

Event System

The IDV module uses an event-driven architecture to communicate state changes and results.

ready

Emitted when IDV is successfully mounted

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

Signals successful information detection

1idv.on('detection_complete', () => {
2  setMounted(false); // Clean up
3});
1idv.on('results', ({ checkStatus, document, entityId }) => {
2  switch(checkStatus) {
3    case 'COMPLETE':
4      // Handle successful verification
5      break;
6    case 'FAILED':
7      // Handle failed verification
8      break;
9  }
10});

The results event provides comprehensive verification outcomes, including document data and entity references.

1interface InputRequiredEvent {
2  information: {
3    entityId: string
4  },
5  checkStatus:
6    | 'AWAITING_DOCUMENT_UPLOAD_INVALID_TYPE'
7    | 'WAITING_DOC_UPLOAD'
8    | 'WAITING_SELFIE_UPLOAD'
9    | 'INCOMPLETE'
10    | 'INTERRUPTED'
11}
12
13idv.on('input_required', (information, checkStatus) => {
14  switch(checkStatus) {
15    case 'WAITING_SELFIE_UPLOAD':
16      console.log("Awaiting selfie capture");
17      break;
18    case 'WAITING_DOC_UPLOAD':
19      console.log("Awaiting document upload");
20      break;
21    // Handle other states...
22  }
23});

For Incode integrations, the ‘INTERRUPTED’ status typically indicates missing camera permissions.

1interface ErrorEvent {
2  message: string;
3  payload: object;
4}
5
6idv.on('error', (error) => {
7  console.error(`Error: ${error.message}`, error.payload);
8  // Implement your error handling logic
9});

For Incode integrations, refer to the Incode documentation for detailed error payload information.

Implementation Tips
  1. Always test the flow on both desktop and mobile devices
  2. Implement proper cleanup on component unmount
  3. Consider implementing retry logic for failed verifications
  4. Store the entityId for future reference