@zerohash-sdk/onboarding-js

A JavaScript SDK that enables frontend applications to seamlessly integrate with the Connect Onboarding product.

Connect Onboarding provides a secure, customizable KYC/onboarding flow for new users directly within your application.

Installation

Via NPM (recommended)

npm install @zerohash-sdk/onboarding-js

import { Onboarding } from '@zerohash-sdk/onboarding-js';

Via CDN

<script
  type="module"
  src="https://sdk.connect.xyz/onboarding-web/index.js"
></script>

Or import directly in your JavaScript code:

import { Onboarding } from 'https://sdk.connect.xyz/onboarding-web/index.js';

Getting Started

1. Import the Onboarding module

import { Onboarding } from '@zerohash-sdk/onboarding-js';

1.1 Or import via CDN

import { Onboarding } from 'https://sdk.connect.xyz/onboarding-web/index.js';

2. Initialize and render the widget

const onboarding = new Onboarding({
  jwt: 'your-jwt-token', // Obtain this from your backend
  env: 'prod', // or 'cert' for testing
  theme: 'auto', // 'auto' (default), 'light', or 'dark'
  onCompleted: ({ participantCode, kycStatus }) => {
    console.log('Onboarding completed:', participantCode, kycStatus);
  },
  onError: ({ errorCode, reason }) => {
    console.error('Onboarding error:', errorCode, 'Reason:', reason);
  },
  onClose: () => {
    console.log('Onboarding widget closed');
  },
  onEvent: ({ type, data }) => {
    console.log('Event received:', type, data);
  },
  onLoaded: () => {
    console.log('Onboarding widget loaded and ready');
  },
});

const container = document.getElementById('onboarding-container');
await onboarding.render(container);

// Update configuration dynamically
onboarding.updateConfig({ jwt: 'new-jwt-token' });

// Check if rendered
if (onboarding.isRendered()) {
  console.log('Widget is active');
}

// Clean up when done
onboarding.destroy();

2.1 Using TypeScript (optional)

import { Onboarding, OnboardingConfig } from '@zerohash-sdk/onboarding-js';

const config: OnboardingConfig = {
  jwt: 'your-jwt-token',
  env: 'cert',
  theme: 'dark',
  onCompleted: ({ participantCode, kycStatus }) => {
    console.log(participantCode, kycStatus);
  },
  onError: ({ errorCode, reason }) => {
    console.error(errorCode, reason);
  },
};

const onboarding = new Onboarding(config);
await onboarding.render(document.getElementById('onboarding-container')!);

API Reference

Configuration

| Prop | Type | Required | Default | Description | | ------------- | ------------------------------------------ | -------- | -------- | ----------------------------------------------- | | jwt | string | Yes | - | JWT token for authentication with Connect | | env | "prod" \| "cert" \| "dev" \| "local" | No | "prod" | Target environment | | theme | "auto" \| "light" \| "dark" | No | "auto" | Theme mode for the interface | | onCompleted | ({ participantCode, kycStatus }) => void | No | - | Callback when onboarding completes successfully | | onError | ({ errorCode, reason }) => void | No | - | Callback for error events | | onClose | () => void | No | - | Callback when the widget is closed | | onEvent | ({ type, data }) => void | No | - | Callback for general events | | onLoaded | () => void | No | - | Callback when the widget is loaded and ready |

Constructor

new Onboarding(config: OnboardingConfig)

Methods

render(container: HTMLElement): Promise<void>

await onboarding.render(document.getElementById('onboarding-container'));

updateConfig(config: Partial<OnboardingConfig>): void

onboarding.updateConfig({ jwt: 'new-token' });

destroy(): void

onboarding.destroy();

isRendered(): boolean

if (onboarding.isRendered()) {
  /* Widget is active */
}

getConfig(): OnboardingConfig

const config = onboarding.getConfig();

Callback Functions

onCompleted

onCompleted: ({ participantCode, kycStatus }) => {
  // participantCode: Unique participant identifier
  // kycStatus: KYC verification status string
};

onError

onError: ({ errorCode, reason }) => {
  // errorCode: 'network_error' | 'auth_error' | 'server_error' | etc.
  // reason: Human-readable error description
};

onClose

onClose: () => {
  /* Handle close event */
};

onEvent

onEvent: ({ type, data }) => {
  // type: Event type string
  // data: Event-specific data object
};

onLoaded

onLoaded: () => {
  /* Widget is fully loaded and ready */
};

Browser Support

• Chrome/Edge 90+
• Firefox 88+
• Safari 14+
• All modern browsers with Web Components support

More Information & Support

For comprehensive documentation or support about Connect, visit our Documentation Page.