Next.js - frankieone

Quick Start Video

Setup Instructions

Create Next.js Project

npx create-next-app@latest my-next-app
cd my-next-app

Install Dependencies

npm install
npm install @frankieone/one-sdk

Configure Environment

Create a .env.local file with your OneSDK credentials:

NEXT_PUBLIC_CUSTOMER_ID=your_customer_id
NEXT_PUBLIC_API_KEY=your_api_key
NEXT_PUBLIC_CHILD_ID=your_child_id  # Optional

Implementation Guide

1. Create OneSDK Hook

Create a new file hooks/useOneSDK.js:

"use client";
import OneSdk from "@frankieone/one-sdk";
import { useEffect, useRef, useState } from "react";

const useOneSDK = ({ config }) => {
  const [oneSDKInstance, setOneSDKInstance] = useState(null);
  const [error, setError] = useState(null);
  const [loading, setLoading] = useState(false);
  const initializedRef = useRef(false);

  const generateToken = async () => {
    try {
      const credentials = btoa(
        `${process.env.NEXT_PUBLIC_CUSTOMER_ID}:${process.env.NEXT_PUBLIC_API_KEY}`
      );
      
      const response = await fetch(
        "https://backend.latest.frankiefinancial.io/auth/v2/machine-session",
        {
          method: "POST",
          headers: {
            authorization: `machine ${credentials}`,
            "Content-Type": "application/json",
          },
          body: JSON.stringify({
            permissions: {
              preset: "one-sdk",
              reference: `demo-${new Date().toISOString()}`,
            },
          }),
        }
      );
      
      return await response.json();
    } catch (error) {
      setError(error.message);
      return null;
    }
  };

  const initializeSDK = async () => {
    setLoading(true);
    try {
      const token = await generateToken();
      if (!token) return;

      const instance = await OneSdk({
        session: token,
        ...config,
      });
      
      setOneSDKInstance(instance);
    } catch (error) {
      setError(error.message);
    } finally {
      setLoading(false);
    }
  };

  useEffect(() => {
    if (!initializedRef.current) {
      initializeSDK();
      initializedRef.current = true;
    }
  }, [config]);

  return { oneSDKInstance, error, loading };
};

export default useOneSDK;

2. Create End-to-End Component

Create a new component file components/EndToEnd.js:

"use client";
import { useEffect } from "react";
import useOneSDK from "../hooks/useOneSDK";

const EndToEnd = () => {
  const config = {
    mode: "development",
    recipe: {
      form: {
        provider: {
          name: "react",
        },
      },
    },
  };

  const { oneSDKInstance, error, loading } = useOneSdk({ config });

  const initializeComponents = () => {
    if (!oneSDKInstance) return;

    // Initialize Components
    const components = {
      welcome: oneSDKInstance.component("form", {
        name: "WELCOME",
        type: "manual",
      }),
      consent: oneSDKInstance.component("form", {
        name: "CONSENT"
      }),
      document: oneSDKInstance.component("form", {
        name: "DOCUMENT",
        showPreps: true,
      }),
      biometrics: oneSDKInstance.component("biometrics"),
    };

    // Mount Welcome Component
    components.welcome.mount("#form-container");

    // Setup Event Handlers
    setupEventHandlers(components);
  };

  const setupEventHandlers = (components) => {
    const { welcome, consent, document, biometrics } = components;

    welcome.on("form:welcome:ready", () => {
      consent.mount("#form-container");
    });

    consent.on("form:consent:ready", () => {
      document.mount("#form-container");
    });

    // Add more event handlers as needed
  };

  useEffect(() => {
    if (oneSDKInstance) {
      initializeComponents();
    }
  }, [oneSDKInstance]);

  if (loading) {
    return <div>Loading OneSDK...</div>;
  }

  if (error) {
    return <div>Error: {error}</div>;
  }

  return <div id="form-container" />;
};

export default EndToEnd;

3. Add Component to Page

Update your page file (e.g., app/page.js):

import EndToEnd from '../components/EndToEnd';

export default function Home() {
  return (
    <main>
      <EndToEnd />
    </main>
  );
}

Component Configuration

Welcome Form
Document Form
Biometrics

const welcome = oneSDKInstance.component("form", {
  name: "WELCOME",
  type: "manual",
  descriptions: [
    { label: 'Welcome to our KYC process', style: {} },
    { label: 'Please follow the steps to verify your identity', style: {} },
  ],
});

const document = oneSDKInstance.component("form", {
  name: "DOCUMENT",
  showPreps: true,
  // Additional configuration options
});

const biometrics = oneSDKInstance.component("biometrics", {
  // Add your biometrics configuration here
});

Event Handling

Form Events

// Welcome Form Events
welcome.on("form:welcome:ready", () => {
  // Handle welcome form ready
});

welcome.on("form:welcome:failed", () => {
  // Handle welcome form failure
});

// Document Form Events
document.on("form:document:ready", async ({ inputInfo }) => {
  // Handle document form ready
  const docType = inputInfo.documentType;
  // Initialize OCR component
});

Biometrics Events

biometrics.on("detection_failed", () => {
  // Handle failed detection
});

biometrics.on("processing", () => {
  // Handle processing state
});

biometrics.on("results", (result) => {
  // Handle biometrics results
});

Best Practices

Error Handling

Always implement proper error handling for both SDK initialization and component events.

Loading States

Show appropriate loading states during initialization and between component transitions.

Event Cleanup

Properly clean up event listeners when components unmount to prevent memory leaks.

Security

Never expose credentials in client-side code. Use environment variables and server-side token generation.

Remember to handle cleanup in your components by implementing proper unmounting logic and removing event listeners when components are destroyed.

Troubleshooting

Common Issues

SDK Initialization Failed: Check your credentials and network connection
Component Mount Errors: Ensure the container element exists in the DOM
Event Handler Issues: Verify event names and handler implementations

Debug Tips

// Enable debug logging
const config = {
  mode: "development",
  debug: true,
  // ... other config options
};

// Listen to all events
oneSDKInstance.on("*", (event) => {
  console.log("Event:", event);
});

​Quick Start Video

​Setup Instructions

​Implementation Guide

​Component Configuration

​Event Handling

​Best Practices

Error Handling

Loading States

Event Cleanup

Security

​Troubleshooting

Quick Start Video

Setup Instructions

Implementation Guide

Component Configuration

Event Handling

Best Practices

Troubleshooting