vult-kyc-widget

The client side construction for the KYC Widget

Local Development - Requirements

• NPM
• Node
• Typescript
• Yarn

Installation

Install the package using npm or yarn:

npm install vult-security-kyc
# or
yarn add vult-security-kyc

Usage

The package provides two ways to use the KYC Widget:

1. Generic Class Usage - Use the KYCWidget class directly for maximum flexibility
2. React Components - Use the pre-built React components (VULTIda and VULTIdv)

Generic Class Usage

The KYCWidget class can be used in any JavaScript/TypeScript application (not just React). This gives you full control over when and how the widget is initialized and started.

import { KYCWidget, IDV, IDA } from 'vult-security-kyc';

// Initialize ID Verification widget
const idvWidget = new KYCWidget({
    Session_Type: IDV, // or "IDVerification"
    env: "dev", // Options: "dev" | "development" | "stage" | "demo" | "prod" | "production"
    onComplete: (response) => {
        console.log("ID Verification completed", response);
        // Handle completion logic here
    },
    onDismiss: () => {
        console.log("Widget dismissed");
        // Handle dismissal logic here
    }
});

// Start ID Verification with a session ID
function startVerification(sessionId: string) {
    idvWidget.startIDVerify(sessionId);
}

// Initialize ID Authentication widget
const idaWidget = new KYCWidget({
    Session_Type: IDA, // or "IDAuthentication"
    env: "prod",
    onComplete: (response) => {
        console.log("ID Authentication completed", response);
    },
    onDismiss: () => {
        console.log("Widget dismissed");
    }
});

// Start ID Authentication with a session ID
function startAuthentication(sessionId: string) {
    idaWidget.startIDAuthenticate(sessionId);
}

// Close the widget programmatically
function closeWidget() {
    idvWidget.close(); // or idaWidget.close()
}

Configuration Interface:

interface KYCWidgetConfig {
    Session_Type: "IDVerification" | "IDAuthentication";
    env: "dev" | "development" | "stage" | "demo" | "prod" | "production";
    onComplete?: (response?: any) => void;
    onDismiss?: () => void;
}

IDA Component (ID Authentication)

For React applications, you can use the VULTIda component for ID Authentication. This component handles the widget lifecycle automatically.

import { useState } from 'react';
import { VULTIda } from 'vult-security-kyc/components';
import type { VULTProps } from 'vult-security-kyc/components';

function MyComponent() {
    const [sessionId, setSessionId] = useState<string>('');

    const handleComplete = () => {
        console.log('ID Authentication completed');
        // Handle completion logic
    };

    const handleDismiss = () => {
        console.log('Widget dismissed');
        // Handle dismissal logic
    };

    return (
        <div>
            <button onClick={() => setSessionId('your-session-id-here')}>
                Start ID Authentication
            </button>
            
            {sessionId && (
                <VULTIda
                    sessionId={sessionId}
                    environment="prod"
                    autoClose={true}
                    onComplete={handleComplete}
                    onDismiss={handleDismiss}
                />
            )}
        </div>
    );
}

VULTIda Props:

interface VULTProps {
    sessionId: string; // Required: The session ID for authentication
    environment: "dev" | "development" | "stage" | "demo" | "prod" | "production"; // Required
    autoClose?: boolean; // Optional: Automatically close widget on completion (default: true)
    onComplete?: () => void; // Optional: Callback when authentication completes
    onDismiss?: () => void; // Optional: Callback when widget is dismissed
}

IDV Component (ID Verification)

For React applications, you can use the VULTIdv component for ID Verification. This component handles the widget lifecycle automatically.

import { useState } from 'react';
import { VULTIdv } from 'vult-security-kyc/components';
import type { VULTProps } from 'vult-security-kyc/components';

function MyComponent() {
    const [sessionId, setSessionId] = useState<string>('');

    const handleComplete = () => {
        console.log('ID Verification completed');
        // Handle completion logic
    };

    const handleDismiss = () => {
        console.log('Widget dismissed');
        // Handle dismissal logic
    };

    return (
        <div>
            <button onClick={() => setSessionId('your-session-id-here')}>
                Start ID Verification
            </button>
            
            {sessionId && (
                <VULTIdv
                    sessionId={sessionId}
                    environment="dev"
                    autoClose={true}
                    onComplete={handleComplete}
                    onDismiss={handleDismiss}
                />
            )}
        </div>
    );
}

VULTIdv Props:

interface VULTProps {
    sessionId: string; // Required: The session ID for verification
    environment: "dev" | "development" | "stage" | "demo" | "prod" | "production"; // Required
    autoClose?: boolean; // Optional: Automatically close widget on completion (default: true)
    onComplete?: () => void; // Optional: Callback when verification completes
    onDismiss?: () => void; // Optional: Callback when widget is dismissed
}

Available Constants

The widget exposes the following constants for convenience:

• VultKYC.IDV - Shorthand for "IDVerification"
• VultKYC.IDA - Shorthand for "IDAuthentication"

Methods

startIDVerify(sessionId: string)

Starts an ID Verification session. Requires a valid session ID.

startIDAuthenticate(sessionId: string)

Starts an ID Authentication session. Requires a valid session ID.

close()

Manually closes the widget and cleans up event listeners. Useful for programmatic dismissal.

Notes

• The widget creates a full-screen modal overlay when started
• Users can dismiss the modal by clicking the backdrop (triggers onDismiss callback)
• The widget automatically handles window resizing and mobile viewport changes
• Make sure to use valid session IDs obtained from your backend API

Licensing

This project includes third-party libraries with their own licenses. Below is a summary of the third-party licenses included in this project:

• DOMPurify: Licensed under the Apache License 2.0. See third-party-licenses/DOMPurify/LICENSE for the full text.

For detailed licensing information and attributions, please refer to the third-party-licenses/ directory.