> ## Documentation Index > Fetch the complete documentation index at: https://docs.frankieone.com/llms.txt > Use this file to discover all available pages before exploring further. # SDK Initialization > Complete reference for initializing the OneSDK ## 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 ```javascript theme={null} 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:** ```typescript theme={null} OneSdk(parameters: OneSdkRootParameters): Promise ``` **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](#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](/docs/sdk-reference/individual-module#module-options) 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](/docs/sdk-reference/sdk-initialization#generating-session-tokens), 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](/docs/sdk-reference/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: ```javascript theme={null} 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: ```javascript theme={null} 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](/docs/sdk-reference/form-module/configuration), [IDV Module](/docs/sdk-reference/idv-module), [OCR Module](/docs/sdk-reference/ocr-module), [Biometrics Module](/docs/sdk-reference/biometrics-module), and other module documentation for available options. | **Examples:** ```javascript theme={null} // 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:** ```typescript theme={null} enum SdkModes { DEV = 'development', PROD = 'production', DUMMY = 'dummy', } ``` ## Return Value Returns a `Promise` 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](/docs/sdk-reference/individual-module). | | `component()` | `ComponentFactory` | Dynamic component loader that creates instances of verification components. Accepts component name and options, returns component instance. Available components: [OCR Module](/docs/sdk-reference/ocr-module), [Biometrics Module](/docs/sdk-reference/biometrics-module), [Device Module](/docs/sdk-reference/device-module), [Form Module](/docs/sdk-reference/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](/docs/sdk-reference/idv-module). | | `session` | `SessionFacade` | Session management interface providing methods to query session state, entity information, and session metadata. See [Session Management Reference](/docs/sdk-reference/session-management). | | `emit()` | `(eventName, ...args) => void` | Emit custom global events. See [Event System Reference](/docs/sdk-reference/events). | | `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](/docs/sdk-reference/events). | | `off()` | `(eventName, callback) => void` | Remove previously registered event listener. Pass the exact same callback function reference used with `on()`. See [Event System Reference](/docs/sdk-reference/events). | ## Usage Examples ### Basic Initialization (Production) ```javascript theme={null} import OneSdk from '@frankieone/one-sdk'; const oneSDKInstance = await OneSdk({ mode: 'production', session: { token: 'your-session-token-here' } }); ``` ### Development Mode with DevTools ```javascript theme={null} const oneSDKInstance = await OneSdk({ mode: 'development', session: { token: 'your-dev-token', appReference: 'my-app-v1.2.3' }, devtools: true }); ``` ### Dummy Mode (No Backend Required) ```javascript theme={null} const oneSDKInstance = await OneSdk({ mode: 'dummy' }); ``` ### With Recipe (String Name) ```javascript theme={null} const oneSDKInstance = await OneSdk({ mode: 'production', session: { token: 'your-session-token' }, recipe: 'standard_kyc' }); ``` ### With Recipe (Object Configuration) ```javascript theme={null} 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 ```javascript theme={null} 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.** ```javascript theme={null} 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'); }); ``` ```javascript theme={null} /** * 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](/docs/embedded-flows/quick-start). ## Error Handling `OneSdk()` returns a Promise that will reject if initialization fails. Always wrap it in a try-catch block: ```javascript theme={null} 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. ```javascript theme={null} 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. ```javascript theme={null} oneSDKInstance.on('telemetry', (event) => { // For debugging purposes only console.log('Telemetry event:', event); }); ``` ### `error` Emitted when an error occurs. ```javascript theme={null} oneSDKInstance.on('error', (error) => { console.error('SDK error:', error); }); ``` ### `warning` Emitted for configuration warnings. ```javascript theme={null} oneSDKInstance.on('warning', (warning) => { console.warn('SDK warning:', warning.message); }); ``` ### Network Events The SDK monitors network connectivity: ```javascript theme={null} 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: ```javascript theme={null} 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: ```javascript theme={null} 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 1. **Always handle errors**: Wrap initialization in try-catch blocks to handle failures gracefully. 2. **Use environment variables**: Store tokens in environment variables, never hardcode them. 3. **Enable devtools in development**: Use `devtools: true` during development for better debugging. 4. **Set appReference**: Always provide an `appReference` to help track issues in logs. 5. **Listen to network events**: Monitor network connectivity to improve user experience. 6. **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](#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](/docs/sdk-reference/vendor-customizations#content-security-policy-csp-settings) for the full list. ## Related * [Individual Module](/docs/sdk-reference/individual-module) * [Session Management](/docs/sdk-reference/session-management) * [Event System](/docs/sdk-reference/events) * [Form Module](/docs/sdk-reference/form-module) * [IDV Module](/docs/sdk-reference/idv-module)