OneSDK Implementation Guide — FrankieOne

This guide provides a conceptual overview of OneSDK integration with basic code examples. The code snippets shown are illustrative and need to be adapted into your specific framework and application architecture. For complete, working examples:

See our Framework Integration Guides for Angular, React, Vue.js, Next.js and other frameworks
Visit our GitHub repository for extensive sample code and reference implementations
Check out our Hosted Implementation Examples for end-to-end solutions hosted by FrankieOne

Core Modules Overview

Individual Module

Complete KYC workflow for individual verification, including document handling, address verification, and profile management.

Biometrics Module

Advanced biometric verification capabilities including facial recognition, liveness detection, and matching.

OCR Module

Intelligent document scanning and data extraction for IDs, passports, and other verification documents.

IDV Module

Comprehensive identity document verification with support for multiple document types across jurisdictions.

eKYC Form Module

Customizable electronic Know Your Customer forms with built-in validation and compliance checks.

Fraud Detection Module

Real-time fraud prevention and detection across multiple risk vectors.

OneSDK Modules Data Capture Flow

Quick Integration Guide

Install OneSDK

$ npm install @frankieone/one-sdk

Initialize the SDK

1 import OneSDK from "@frankieone/one-sdk";
2 
3 // fetch your token
4 const tokenResultRaw = await fetch(
5   "https://backend.kycaml.uat.frankiefinancial.io/auth/v2/machine-session",
6   {
7     method: "POST",
8     headers: {
9       authorization: "machine " + btoa(`${CUSTOMER_ID}:${API_KEY}`),
10       "Content-Type": "application/json",
11     },
12     body: JSON.stringify({
13       permissions: {
14         preset: "one-sdk",
15         // you can pass either your own unique customer reference
16         // or if entity already created/existed, you can pass it's ID here
17         reference: "customer-reference",
18         entityId: "abc-def-ghi",
19       },
20     }),
21   },
22 );
23 
24 const oneSdk = await OneSDK({
25   session: tokenResultRaw,
26   mode: "production",
27   recipe: {
28     ocr: {
29       maxDocumentCount: 3,
30     },
31   },
32 });

Configure Modules

1 // Example: Initialize Individual and Biometrics modules
2 const individual = oneSdk.individual();
3 const biometrics = oneSdk.component("biometrics");

Start Verification

1 // Example: Mounting Biometrics Component
2 biometrics.mount("#bio-el");
3 
4 biometrics.on("detection_complete", (event) => {
5   console.log("Biometric capture completed");
6 });
7 
8 biometrics.on("results", (results) => {
9   console.log("Verification results:", results);
10 });

Generating Token with Custom Permissions

To generate a token with custom permissions, you can supply list of permissions instead of a preset object in the request body.

1 const tokenResultRaw = await fetch(
2   "https://backend.kycaml.uat.frankiefinancial.io/auth/v2/machine-session",
3   {
4     method: "POST",
5     headers: {
6       authorization: "machine " + btoa(`${CUSTOMER_ID}:${API_KEY}`),
7       "Content-Type": "application/json",
8     },
9     body: JSON.stringify({
10       permissions: [
11         'update::applicant:reference:your-customer-reference',
12         'create::event'
13       ]
14     }),
15   },
16 );

Implementation Best Practices

Error Handling

1 try {
2   await individual.submit();
3 } catch (error) {
4   if (error.code === 'CONSENT_REQUIRED') {
5     // Handle missing consent
6   } else if (error.code === 'VALIDATION_ERROR') {
7     // Handle validation errors
8   }
9 }

Module Coordination

1 // Example: Coordinated verification flow
2 const verifyUser = async () => {
3   // 1. Capture basic information
4   await individual.setProfileType('standard_kyc');
5   
6   // 2. Perform document verification
7   const docResult = await idv.verifyDocument();
8   
9   // 3. Run biometric checks
10   const bioResult = await biometrics.verifyFace();
11   
12   // 4. Submit for final verification
13   return individual.submit();
14 };

Performance Optimization

Initialize modules only when needed and release resources after use. This is especially important for camera-based operations in the Biometrics and OCR modules.

Common Integration Scenarios

Basic KYC

Enhanced Verification

1 const basicKyc = async () => {
2   const individual = oneSdk.individual();
3   const idv = oneSdk.idv();
4 
5   await individual.addConsent('general');
6   await idv.captureDocument('PASSPORT');
7   return individual.submit();
8 };

Each module can be used independently or as part of a comprehensive verification flow. Check individual module documentation for detailed implementation guidelines.

Content Security Policy (CSP) Settings

You may need to adjust your Content Security Policy (CSP) settings to allow vendors’ scripts and resources to load correctly. Below are the additional CSP rules required based on the vendor you are integrating with:

Onfido

Incode

Refer to https://documentation.onfido.com/sdk/sdk-csp-guide/#content-security-policy

API Reference

Detailed API documentation for all OneSDK modules and methods.

Migration Guide

Guide for upgrading from previous versions of OneSDK.

Examples Repository

Sample implementations and integration patterns.

Support Portal

Technical support and implementation assistance.

1	import OneSDK from "@frankieone/one-sdk";
2
3	// fetch your token
4	const tokenResultRaw = await fetch(
5	"https://backend.kycaml.uat.frankiefinancial.io/auth/v2/machine-session",
6	{
7	method: "POST",
8	headers: {
9	authorization: "machine " + btoa(`${CUSTOMER_ID}:${API_KEY}`),
10	"Content-Type": "application/json",
11	},
12	body: JSON.stringify({
13	permissions: {
14	preset: "one-sdk",
15	// you can pass either your own unique customer reference
16	// or if entity already created/existed, you can pass it's ID here
17	reference: "customer-reference",
18	entityId: "abc-def-ghi",
19	},
20	}),
21	},
22	);
23
24	const oneSdk = await OneSDK({
25	session: tokenResultRaw,
26	mode: "production",
27	recipe: {
28	ocr: {
29	maxDocumentCount: 3,
30	},
31	},
32	});

1	// Example: Initialize Individual and Biometrics modules
2	const individual = oneSdk.individual();
3	const biometrics = oneSdk.component("biometrics");

1	// Example: Mounting Biometrics Component
2	biometrics.mount("#bio-el");
3
4	biometrics.on("detection_complete", (event) => {
5	console.log("Biometric capture completed");
6	});
7
8	biometrics.on("results", (results) => {
9	console.log("Verification results:", results);
10	});

1	try {
2	await individual.submit();
3	} catch (error) {
4	if (error.code === 'CONSENT_REQUIRED') {
5	// Handle missing consent
6	} else if (error.code === 'VALIDATION_ERROR') {
7	// Handle validation errors
8	}
9	}

1	// Example: Coordinated verification flow
2	const verifyUser = async () => {
3	// 1. Capture basic information
4	await individual.setProfileType('standard_kyc');
5
6	// 2. Perform document verification
7	const docResult = await idv.verifyDocument();
8
9	// 3. Run biometric checks
10	const bioResult = await biometrics.verifyFace();
11
12	// 4. Submit for final verification
13	return individual.submit();
14	};

1	const basicKyc = async () => {
2	const individual = oneSdk.individual();
3	const idv = oneSdk.idv();
4
5	await individual.addConsent('general');
6	await idv.captureDocument('PASSPORT');
7	return individual.submit();
8	};