Skip to main content
This guide walks you through setting up a minimal embedded IDV flow — from generating a session token to mounting the SDK in your page. Once you have this working, you can swap in any of the flow guides for more advanced journeys.
Instead of building from scratch, you can fork an existing flow from the public sample codes.

Prerequisites

  • A Customer ID and API Key from the FrankieOne portal
  • A backend endpoint that can generate session tokens (or use the inline fetch shown below for development only)
  • Node.js 16+ (for the React example)

Architecture

Solution Architecture
  1. Customer Web App — your application hosting OneSDK
  2. OneSDK — manages the verification UI/UX
  3. Incode IDV — handles document and biometric capture
  4. FrankieOne KYC — processes verification checks
  5. Portal — displays verification results

Full Implementation

Copy this into an .html file and open it in a browser. Replace the placeholder credentials with your own.
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>OneSDK Quick Start</title>
    <script src="https://assets.frankiefinancial.io/one-sdk/v1/oneSdk.umd.js"></script>
    <style>
      body { margin: 0; font-family: sans-serif; background: #fff; }
      #onesdk-container { width: 100%; height: 100vh; }
    </style>
  </head>
  <body>
    <div id="onesdk-container"></div>

    <script>
      async function startOneSDK() {
        try {
          // 1. Generate session token (move to your backend in production)
          const tokenResponse = await fetch(
            "https://backend.kycaml.uat.frankiefinancial.io/auth/v2/machine-session",
            {
              method: "POST",
              headers: {
                authorization: "machine " + btoa("<CUSTOMER_ID>:<CUSTOMER_CHILD_ID>:<API_KEY>"),
                "Content-Type": "application/json",
              },
              body: JSON.stringify({
                permissions: {
                  preset: "one-sdk",
                  reference: "quickstart-" + Date.now(),
                },
              }),
            }
          );
          const session = await tokenResponse.json();

          // 2. Initialize OneSDK
          const oneSdk = await OneSDK({
            session: session,
            mode: "development",
            recipe: {
              form: {
                provider: { name: "react" },
              },
            },
          });

          const appContainer = "#onesdk-container";

          // 3. Create form and IDV components
          const welcome = oneSdk.component("form", {
            name: "WELCOME",
            type: "ocr",
          });

          const consent = oneSdk.component("form", { name: "CONSENT" });

          const idv = oneSdk.flow("idv");

          // 4. Wire up welcome → consent → IDV
          welcome.on("form:welcome:ready", () => {
            consent.mount(appContainer);
          });

          consent.on("form:consent:ready", () => {
            idv.mount(appContainer);
          });

          idv.on("results", async ({ checkStatus }) => {
            if (checkStatus) {
              document.getElementById("onesdk-container").innerHTML =
                "<h2>Verification complete</h2>";
            }
          });

          idv.on("error", ({ message }) => {
            console.error("IDV error:", message);
          });

          // 5. Mount welcome screen to start
          welcome.mount(appContainer);
        } catch (error) {
          console.error("OneSDK initialization failed:", error);
        }
      }

      startOneSDK();
    </script>
  </body>
</html>

Step-by-Step Breakdown

1. Generate a Session Token

Your backend calls the /auth/v2/machine-session endpoint with your credentials and returns the session object to the frontend. See Session Management for details.

2. Initialize the SDK

Pass the session object to OneSDK() along with configuration options like mode and recipe. Include the recipe.form.provider configuration for the WELCOME and CONSENT screens. Create WELCOME and CONSENT form components to collect user consent before starting verification. Consent must be collected before the IDV flow can proceed.

4. Create a Flow or Component

Use sdk.flow("idv") to create an IDV flow, or create individual components like sdk.component("ocr") for more granular control.

5. Wire Up Events

Listen for events like form:welcome:ready, form:consent:ready, results, error, and loading to drive your UI transitions.

6. Mount to the DOM

Call .mount("#onesdk-container") on the welcome screen to start the flow. Each subsequent screen is mounted by event listeners.

Next Steps

eKYC Flow

Manual form-based KYC with document collection and fraud detection.

IDV Flow

Camera-based identity document verification with minimal setup.

IDV with Review

IDV flow with OCR review screen for data verification.

Split Flow

Separate OCR and Biometrics components for maximum control.

OCR Only

Document capture and data extraction without biometrics.

Document Upload

File-based document collection with upload screens.

Additional Resources

Sample Code

Browse reference implementations.

Live Demo

Try OneSDK in an interactive environment.

Test Data

Get test credentials and sample data.

Troubleshooting

  • Verify your Customer ID and API Key in the .env file
  • Check network connectivity to the FrankieOne API
  • Ensure you are using the correct endpoint (UAT vs production)
  • Confirm the mount target element exists in the DOM (e.g., #onesdk-container)
  • Check the browser console for initialization errors
  • Verify the session token has not expired
  • Always generate session tokens on your backend — never expose API keys in client code
  • Implement error handling for all SDK operations
  • Use test data during development