> ## 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.
# Next.js
> This guide walks you through integrating OneSDK with Next.js, providing you with a solid foundation for building secure and efficient KYC workflows.
## Quick Start Video
## Setup Instructions
```bash theme={null}
npx create-next-app@latest my-next-app
cd my-next-app
```
```bash theme={null}
npm install
npm install @frankieone/one-sdk
```
Create a `.env.local` file with your OneSDK credentials:
```env theme={null}
NEXT_PUBLIC_CUSTOMER_ID=your_customer_id
NEXT_PUBLIC_API_KEY=your_api_key
NEXT_PUBLIC_CHILD_ID=your_child_id # Optional
```
## Implementation Guide
Create a new file `hooks/useOneSDK.js`:
```javascript theme={null}
"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;
```
Create a new component file `components/EndToEnd.js`:
```javascript theme={null}
"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 Loading OneSDK...
;
}
if (error) {
return Error: {error}
;
}
return ;
};
export default EndToEnd;
```
Update your page file (e.g., `app/page.js`):
```javascript theme={null}
import EndToEnd from '../components/EndToEnd';
export default function Home() {
return (
);
}
```
## Component Configuration
```javascript theme={null}
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: {} },
],
});
```
```javascript theme={null}
const document = oneSDKInstance.component("form", {
name: "DOCUMENT",
showPreps: true,
// Additional configuration options
});
```
```javascript theme={null}
const biometrics = oneSDKInstance.component("biometrics", {
// Add your biometrics configuration here
});
```
## Event Handling
```javascript theme={null}
// 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
});
```
```javascript theme={null}
biometrics.on("detection_failed", () => {
// Handle failed detection
});
biometrics.on("processing", () => {
// Handle processing state
});
biometrics.on("results", (result) => {
// Handle biometrics results
});
```
## Best Practices
Always implement proper error handling for both SDK initialization and
component events.
Show appropriate loading states during initialization and between component
transitions.
Properly clean up event listeners when components unmount to prevent memory
leaks.
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
* **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
```javascript theme={null}
// Enable debug logging
const config = {
mode: "development",
debug: true,
// ... other config options
};
// Listen to all events
oneSDKInstance.on("*", (event) => {
console.log("Event:", event);
});
```