# Onboarding (KYC/KYB)

## Getting started

This guide explains how to integrate the Footprint onboarding flow for KYC (Know Your Customer) and KYB (Know Your Business) into your JavaScript/TypeScript applications.

**Note:** Make sure you have `@onefootprint/footprint-js` version 5.0.0 or higher installed for the onboarding integration to work properly.

The default behavior launches the onboarding flow within a modal. For an inline integration option, see the [Inline Integration](#inline-integration) section below.

1. **Create an onboarding session token**:
   * Obtain onboarding session token, e.g., `obtok_UxM6Vbvk2Rcy1gzcSuXgk3sj3L9I0pAnNH`. Read [this article](/articles/guide/definitive-integration-guide#the-end-to-end-integration-step-3-create-an-onboarding-session-token).

2. **Initialize the Footprint Flow**:
   * Trigger Footprint, for example, when a button is clicked. Then, pass the `onboardingSessionToken` and `onComplete` callback to the `initialize` method.

```javascript
import "@onefootprint/footprint-js/dist/footprint-js.css";
import { onboarding } from "@onefootprint/footprint-js";

const App = () => {
  const launch = () => {
    onboarding.initialize({
      onboardingSessionToken: "obtok_UxM6Vbvk2Rcy1gzcSuXgk3sj3L9I0pAnNH",
      onComplete: (validationToken) => {
        console.log(validationToken);
      },
    });
  };

  return (
    <button type="button" onClick={launch}>Launch Footprint</button>
  );
}
```

3. **Handle Completion:**
   * Once the user completes the flow, you'll receive the validationToken through the `onComplete` callback. Post this token to your backend for further processing.

Click [here](https://github.com/onefootprint/examples/tree/master/idv/frontend-vite-vanilla) to check out a full example.

## Listening to events

Footprint provides several events based on actions performed by the user. To listen to events, pass them from either the `initialize` (modal) or `initializeInline` method.

```typescript
import { onboarding } from "@onefootprint/footprint-js";

onboarding.initialize({
  onboardingSessionToken: "obtok_UxM6Vbvk2Rcy1gzcSuXgk3sj3L9I0pAnNH",
  onComplete: (validationToken) => {
    console.log(validationToken);
  },
  onError: (error) => {
    console.log(error);
  },
  onAuth: (validationToken) => {
    console.log(validationToken);
  },
  onCancel: () => {
    console.log("User canceled the flow");
  },
  onClose: () => {
    console.log("User closed the flow");
  },
});
```

## Inline Integration

**Note:** The `initializeInline` method is supported from version 5.1.0 onwards.

For use cases where you prefer to embed the onboarding flow directly within your page instead of using a modal, you can use the `initializeInline` method.

**Note:** The inline integration requires a container element in your DOM where the flow will be rendered.

```javascript
import "@onefootprint/footprint-js/dist/footprint-js.css";
import { onboarding } from "@onefootprint/footprint-js";

const App = () => {
  const launchInline = () => {
    onboarding.initializeInline({
      onboardingSessionToken: "obtok_UxM6Vbvk2Rcy1gzcSuXgk3sj3L9I0pAnNH",
      containerId: "footprint-container",
      onComplete: (validationToken) => {
        console.log(validationToken);
      },
    });
  };

  return (
    <div>
      <button type="button" onClick={launchInline}>Launch Footprint Inline</button>
      <div id="footprint-container" style={{ height: '600px', width: '100%' }}></div>
    </div>
  );
}
```

The inline integration supports the same event handlers and customization options as the modal version. Make sure to provide adequate height for the container element (recommended minimum: 600px).

## Setting a custom appearance

You can customize the appearance of the onboarding flow by passing an `appearance` object to either the `initialize` (modal) or `initializeInline` method.

```typescript
import { onboarding } from "@onefootprint/footprint-js";

onboarding.initialize({
  onboardingSessionToken: "obtok_UxM6Vbvk2Rcy1gzcSuXgk3sj3L9I0pAnNH",
  onComplete: (validationToken) => {
    console.log(validationToken);
  },
  appearance: {
    variables: {
      borderRadius: "8px",
      colorSuccess: "#10b981",
      colorError: "#F87171",
      buttonPrimaryBg: "#5550e9",
    },
  },
});
```

For more information, including a list of available variables, check out the [customization guide](/articles/integrate/customization).

## Available Props

| Variable                 | Description                                                                                                                                                                                                                                           |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `onboardingSessionToken` | The onboarding session token you created.                                                                                                                                                                                                             |
| `onComplete`             | Triggered after the user completes the onboarding flow. You'll receive a `validationToken` that your backend can exchange with Footprint to see the fp\_id, the login method used, and the KYC status.                                                |
| `onAuth`                 | Optional. Triggered after the user finishes logging in, before the user has finished fully onboarding. You'll receive a `validationToken` in this callback that your backend can exchange with Footprint to see the fp\_id and the login method used. |
| `onError`                | Optional. A function that is called when there was an unrecoverable error while initializing the onboarding flow. It takes in an error string argument with more details.                                                                             |
| `onCancel`               | Triggered when the user abandons the flow. This can be triggered when the user clicks on the close button inside our iframe                                                                                                                           |
| `onClose`                | Triggered when the user closes the flow (either completed or canceled).                                                                                                                                                                               |
| `appearance`             | Optional. A `FootprintAppearance` object that customizes the look of your integration                                                                                                                                                                 |
| `l10n`                   | Optional. Specifies the desired localization. More information [here](/articles/integrate/customization#localization-configuration).                                                                                                                  |
| `containerId`            | Required for inline integration only. The ID of the DOM element where the onboarding flow will be rendered.                                                                                                                                           |