SDK Initialization - frankieone

Overview

The OneSDK must be initialized before any modules can be used. The initialization process configures the SDK with your session token, sets the environment mode, and prepares all modules for use.

Import

import OneSdk from '@frankieone/one-sdk';

Method

`OneSdk(parameters)`

Initializes the OneSDK and returns a Promise that resolves to the SDK context object. OneSdk is the default export of the package and is itself the initialization function. Signature:

OneSdk(parameters: OneSdkRootParameters): Promise<OneSdkContext>

Parameters:

Parameter	Type	Required	Default	Description
`mode`	`string \| ModeOption`	No	`"production"`	SDK operational mode. Use `"production"` for live deployments, `"development"` when building and testing your integration, or `"dummy"` to explore the SDK with locally mocked responses (no backend required). The target environment (sandbox vs production) is determined by the customer credentials used to generate your session token. See SDK Modes for details. Can also be an object for advanced configuration.
`session`	`SessionOptions`	Conditional	-	Session configuration containing authentication token and persistence settings. Required when `mode` is `"production"` or `"development"`. Optional when `mode` is `"dummy"`.
`recipe`	`string \| PartialRecipe`	No	`"auto"`	Verification recipe configuration. Pass a string recipe name (e.g., `"kyc-basic"`) to use a predefined recipe, or pass a partial recipe object to customize configuration. When omitted, defaults to automatic recipe selection.
`telemetry`	`boolean`	No	`true`	Enable or disable telemetry. When `true` (default), the SDK sends diagnostic data to FrankieOne to help troubleshoot issues. It’s recommended to leave this enabled for easier support. Set to `false` to disable.
`devtools`	`boolean`	No	`false`	Enable developer tools overlay for debugging. When `true`, attaches debugging utilities to help inspect SDK state and behavior during development. Should only be enabled in development environments.
`individualLevel`	`string`	No	-	Controls the level of detail retrieved for entity data from the API. Use `'base64'` to include document scan images as base64-encoded strings, or `'meta'` to retrieve only metadata without images. See Individual Module for details.

When telemetry is enabled, the SDK automatically redacts sensitive values (e.g. tokens, API keys, secrets, clientID) from component options and recipe data before including them in telemetry events.

SessionOptions

Session configuration object. Required when mode is not "dummy".

Property	Type	Required	Default	Description
`token`	`string \| null`	Yes	-	Session authentication token. Your backend server obtains this token by calling the FrankieOne session API, then passes it to your frontend to initialize the SDK. This token authorizes the SDK to perform verification operations for a specific entity. Must be a valid JWT token string. Pass `null` only in special cases where the token will be set later.
`persist`	`boolean`	No	`false`	Enable session persistence across browser refreshes and page navigation. When `true`, the session token is stored in browser storage and automatically reused on next initialization. When `false`, a new session must be created each time. See Session Management for persistence details.
`appReference`	`string`	No	-	A reference string identifying the application integrating with OneSDK. This value is included in telemetry data sent to FrankieOne, allowing FrankieOne to distinguish which application under your account generated a given event. Useful when you have multiple applications using OneSDK on the same customer account. Recommended format: `"app-name-vX.Y.Z"` (e.g., `"my-kyc-app-v1.2.0"`).

Recipe Configuration

The recipe parameter controls how the SDK performs verification. You can pass either a string (recipe name) or an object (recipe configuration).

String Recipe Name

Pass a predefined recipe name to use standard verification workflows:

OneSdk({
  session: { token: 'your-token' },
  recipe: 'standard_kyc'
});

Common Recipe Names:

"auto" - Automatically selects appropriate recipe (default)
"default" - Standard verification flow
"standard_kyc" - Standard KYC verification
"full" - Full verification with all checks
"safe_harbour" - Safe harbour compliance checks
"safe_harbour_plus" - Enhanced safe harbour checks
"international" - International verification flow
"gov_id" - Government ID verification
"aml_only" - AML checks only
Custom recipe names configured by FrankieOne

Recipe Configuration Object

Pass a partial configuration object to customize the verification flow:

OneSdk({
  session: { token: 'your-token' },
  recipe: {
    name: 'standard_kyc',
    // Module-specific configurations can be added here
    // See individual module documentation for available options
  }
});

Recipe Object Structure:

Property	Type	Description
`name`	`string`	Recipe name (required when using object form)
Module configurations	`object`	Each module can add its own configuration properties. See Form Module Configuration, IDV Module, OCR Module, Biometrics Module, and other module documentation for available options.

Examples:

// Basic recipe by name
recipe: 'standard_kyc'

// Recipe object with name only
recipe: {
  name: 'standard_kyc'
}

// Custom recipe configuration (module-specific options depend on your recipe)
recipe: {
  name: 'custom_kyc',
  // Module-specific configurations added by recipe
}

Recipe configuration is typically managed by FrankieOne. The SDK will fetch and merge the recipe configuration from the server with any recipe options you pass during initialization.

SDK Modes

The SDK supports three operational modes:

Mode	Value	Description
Production	`"production"`	For live, production deployments. Makes real API calls to FrankieOne. Requires a session token. Use this with your production customer credentials.
Development	`"development"`	For use during integration and testing. Makes real API calls to FrankieOne, just like production. Requires a session token. Use this mode while building and testing your integration before going live. Note that the target environment (sandbox vs production) is determined by the customer credentials used to generate your session token, not by this mode setting — ensure your credentials match the environment you intend to test against.
Dummy	`"dummy"`	Runs the SDK entirely with locally mocked responses — no API calls are made and no session token is required. Use this mode to explore OneSDK’s UI components and flows in complete isolation, without needing any backend integration or FrankieOne account. Ideal for prototyping and getting familiar with the SDK before connecting to a real environment.

Type Definition:

enum SdkModes {
  DEV = 'development',
  PROD = 'production',
  DUMMY = 'dummy',
}

Return Value

Returns a Promise<OneSdkContext> that resolves to the SDK context object.

OneSdkContext

The SDK context provides access to all modules and SDK functionality:

Property	Type	Description
`individual()`	`() => IndividualModuleContext`	Factory function that returns the Individual (KYC) module context for managing individual identity verification. Provides methods for collecting and submitting personal information, documents, addresses, and consents. See Individual Module Reference.
`component()`	`ComponentFactory`	Dynamic component loader that creates instances of verification components. Accepts component name and options, returns component instance. Available components: OCR Module, Biometrics Module, Device Module, Form Module.
`flow()`	`FlowFactory`	Dynamic flow loader that creates instances of verification flows (pre-built multi-step processes). Accepts flow name and options, returns flow instance. Use this to access the IDV Module.
`session`	`SessionFacade`	Session management interface providing methods to query session state, entity information, and session metadata. See Session Management Reference.
`emit()`	`(eventName, ...args) => void`	Emit custom global events. See Event System Reference.
`on()`	`(eventName, callback) => void`	Register event listener for global SDK events (error, warning, loading, network events, etc.). Events are not fully typed. See Event System Reference.
`off()`	`(eventName, callback) => void`	Remove previously registered event listener. Pass the exact same callback function reference used with `on()`. See Event System Reference.

Usage Examples

Basic Initialization (Production)

import OneSdk from '@frankieone/one-sdk';

const oneSDKInstance = await OneSdk({
  mode: 'production',
  session: {
    token: 'your-session-token-here'
  }
});

Development Mode with DevTools

const oneSDKInstance = await OneSdk({
  mode: 'development',
  session: {
    token: 'your-dev-token',
    appReference: 'my-app-v1.2.3'
  },
  devtools: true
});

Dummy Mode (No Backend Required)

const oneSDKInstance = await OneSdk({
  mode: 'dummy'
});

With Recipe (String Name)

const oneSDKInstance = await OneSdk({
  mode: 'production',
  session: {
    token: 'your-session-token'
  },
  recipe: 'standard_kyc'
});

With Recipe (Object Configuration)

const oneSDKInstance = await OneSdk({
  mode: 'production',
  session: {
    token: 'your-session-token'
  },
  recipe: {
    name: 'standard_kyc',
    // Example: OCR module configuration
    ocr: {
      provider: {
        name: 'incode'
      },
      modes: ['auto']
    }
  }
});

With Token Persistence

const oneSDKInstance = await OneSdk({
  mode: 'production',
  session: {
    token: 'your-session-token',
    persist: true  // Token will be stored and reused
  }
});

Generating Session Tokens

Session tokens must be generated on your backend server by calling the FrankieOne API. Never expose your API credentials in client-side code.

Backend (Node.js/Express)
Frontend

const express = require('express');
const app = express();

const CUSTOMER_ID = process.env.FRANKIE_CUSTOMER_ID;
const CUSTOMER_CHILD_ID = process.env.FRANKIE_CUSTOMER_CHILD_ID; // Optional
const API_KEY = process.env.FRANKIE_API_KEY;
const FRANKIE_BASE_URL = process.env.FRANKIE_BASE_URL || 'https://backend.kycaml.uat.frankiefinancial.io';

app.use(express.json());

/**
 * Generates a base64-encoded authorization token.
 * Format: base64(customerID:apiKey) or base64(customerID:customerChildID:apiKey)
 */
function getAuthToken() {
  const elements = [CUSTOMER_ID, CUSTOMER_CHILD_ID, API_KEY].filter(Boolean);
  return Buffer.from(elements.join(':')).toString('base64');
}

/**
 * Generates a OneSDK session token
 */
async function generateSessionToken(reference) {
  try {
    const response = await fetch(
      `${FRANKIE_BASE_URL}/auth/v2/machine-session`,
      {
        method: 'POST',
        headers: {
          'authorization': `machine ${getAuthToken()}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({
          permissions: {
            preset: 'one-sdk',
            reference: reference || `session-${Date.now()}`,
          },
        }),
      }
    );

    if (!response.ok) {
      throw new Error(`Failed to generate token: ${response.statusText}`);
    }

    return await response.json();
  } catch (error) {
    console.error('Token generation error:', error);
    throw error;
  }
}

/**
 * Endpoint to create a verification session
 */
app.post('/api/create-session', async (req, res) => {
  try {
    const { reference } = req.body;
    const session = await generateSessionToken(reference);

    res.json({
      token: session.token,
      sessionId: session.session_id
    });
  } catch (error) {
    res.status(500).json({
      error: 'Failed to generate session token',
      message: error.message
    });
  }
});

app.listen(3001, () => {
  console.log('Server running on http://localhost:3001');
});

/**
 * Fetches a session token from your backend
 */
async function createVerificationSession(reference) {
  try {
    const response = await fetch('/api/create-session', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        reference: reference || `user-${Date.now()}`
      })
    });

    if (!response.ok) {
      throw new Error('Failed to create session');
    }

    return await response.json();
  } catch (error) {
    console.error('Session creation error:', error);
    throw error;
  }
}

/**
 * Initialize OneSDK with the session token
 */
async function initializeSDK() {
  try {
    // Get session token from your backend
    const { token } = await createVerificationSession('user-123');

    // Initialize the SDK
    const sdk = await OneSdk({
      mode: 'production',
      session: { token }
    });

    console.log('SDK initialized successfully');
    return sdk;
  } catch (error) {
    console.error('SDK initialization failed:', error);
  }
}

// Usage
initializeSDK();

For the complete implementation with React hooks and error handling, see the Embedded OneSDK Quick Start.

Error Handling

OneSdk() returns a Promise that will reject if initialization fails. Always wrap it in a try-catch block:

try {
  const oneSDKInstance = await OneSdk({
    mode: 'production',
    session: { token: 'your-token' }
  });

  console.log('SDK initialized successfully');
} catch (error) {
  console.error('Failed to initialize SDK:', error);
  // Handle initialization error
}

Events

The SDK emits several events during and after initialization:

`resolved_root_config`

Emitted when the root configuration is resolved.

oneSDKInstance.on('resolved_root_config', (config) => {
  console.log('Configuration resolved:', config);
});

`telemetry`

Emitted for internal diagnostic data. Used by FrankieOne for troubleshooting and support.

Telemetry events are primarily for internal use by FrankieOne support. Event structure is not fully typed and may change.

oneSDKInstance.on('telemetry', (event) => {
  // For debugging purposes only
  console.log('Telemetry event:', event);
});

`error`

Emitted when an error occurs.

oneSDKInstance.on('error', (error) => {
  console.error('SDK error:', error);
});

`warning`

Emitted for configuration warnings.

oneSDKInstance.on('warning', (warning) => {
  console.warn('SDK warning:', warning.message);
});

Network Events

The SDK monitors network connectivity:

oneSDKInstance.on('network_offline', () => {
  console.log('Network connection lost');
});

oneSDKInstance.on('network_online', () => {
  console.log('Network connection restored');
});

Session Management

After initialization, you can access session information through the session property:

const sessionId = oneSDKInstance.session.getSessionId();
const entityId = oneSDKInstance.session.getEntityId();
const reference = oneSDKInstance.session.getReference();
const isPersisted = oneSDKInstance.session.isPersisted();

// Get extra session data
const extraData = oneSDKInstance.session.getExtraData();
console.log('Requested documents:', extraData.requestedDocuments);

// Get session expiration
const expirationEpoch = oneSDKInstance.session.getExpirationEpoch();

// Unpersist the session (remove from storage)
oneSDKInstance.session.unpersist();

JavaScript/TypeScript Usage

OneSDK provides type definitions for TypeScript projects, but full TypeScript support is not available for all APIs:

import OneSdk from '@frankieone/one-sdk';

// Initialize the SDK
const sdk = await OneSdk({
  mode: 'production',
  session: {
    token: 'your-token'
  }
});

// Access modules
const individualModule = sdk.individual();
const formComponent = sdk.component('form', options);
const idvFlow = sdk.flow('idv', options);

// Listen to events
sdk.on('error', (error) => {
  console.error('SDK error:', error);
});

// Access session information
const sessionId = sdk.session.getSessionId();
const entityId = sdk.session.getEntityId();

Best Practices

Always handle errors: Wrap initialization in try-catch blocks to handle failures gracefully.
Use environment variables: Store tokens in environment variables, never hardcode them.
Enable devtools in development: Use devtools: true during development for better debugging.
Set appReference: Always provide an appReference to help track issues in logs.
Listen to network events: Monitor network connectivity to improve user experience.
Use token persistence wisely: Only enable persist: true when appropriate for your use case.

Common Issues

Token expired or invalid

If the session token is expired or invalid, initialization will fail. Generate a fresh token from your backend and reinitialize the SDK. See the Generating Session Tokens example above.

CSP (Content Security Policy) errors

If you see CSP errors in the browser console, ensure your CSP headers allow the OneSDK resources:

Content-Security-Policy:
  script-src 'self' https://assets.frankiefinancial.io;
  style-src 'self' https://*.frankiefinancial.io;
  connect-src 'self' https://*.frankiefinancial.io https://*.frankieone.com;
  img-src 'self' https://*.frankiefinancial.io data:;
  font-src 'self' https://*.frankiefinancial.io data:;
  frame-src 'self' https://*.frankiefinancial.io https://*.frankie.one;

If you are using a third-party vendor (Onfido, Incode, Sumsub, etc.), additional vendor-specific domains are required. See Vendor CSP Settings for the full list.

​Overview

​Import

​Method

​OneSdk(parameters)

​SessionOptions

​Recipe Configuration

​String Recipe Name

​Recipe Configuration Object

​SDK Modes

​Return Value

​OneSdkContext

​Usage Examples

​Basic Initialization (Production)

​Development Mode with DevTools

​Dummy Mode (No Backend Required)

​With Recipe (String Name)

​With Recipe (Object Configuration)

​With Token Persistence

​Generating Session Tokens

​Error Handling

​Events

​resolved_root_config

​telemetry

​error

​warning

​Network Events

​Session Management

​JavaScript/TypeScript Usage

​Best Practices

​Common Issues

​Token expired or invalid

​CSP (Content Security Policy) errors

​Related

Overview

Import

Method

`OneSdk(parameters)`

SessionOptions

Recipe Configuration

String Recipe Name

Recipe Configuration Object

SDK Modes

Return Value

OneSdkContext

Usage Examples

Basic Initialization (Production)

Development Mode with DevTools

Dummy Mode (No Backend Required)

With Recipe (String Name)

With Recipe (Object Configuration)

With Token Persistence

Generating Session Tokens

Error Handling

Events

`resolved_root_config`

`telemetry`

`error`

`warning`

Network Events

Session Management

JavaScript/TypeScript Usage

Best Practices

Common Issues

Token expired or invalid

CSP (Content Security Policy) errors

Related