# Web SDK

### Introduction

The VoveSDK for Web enables the straightforward integration of ID verification and KYC compliance into web applications. This SDK provides a simplified, JavaScript API, allowing developers to seamlessly integrate complex ID verification processes.

### Installation

To incorporate the VoveSDK into your web project, you can install it via npm or Yarn:

`npm install @vove-id/web-sdk`

or

`yarn add @vove-id/web-sdk`

This package includes all necessary dependencies, ensuring a hassle-free setup without the need for additional configurations.

### Usage

The core functionality of the VoveSDK is to facilitate ID verification through an easy-to-use function call. This function orchestrates the verification process, requiring a session token and an environment setting.

#### Starting ID Verification

To begin the ID verification process, utilize the `processIDMatching` function. This function needs a session token (provided by your backend server) and an environment setting. It returns a promise that resolves with the verification outcome.

**Function Signature**

```
const vove = new Vove();

vove.start({
  sessionToken: string,
  environment: VoveEnvironment,
  onVerificationComplete?: (status: VoveStatus) => void,
  publicKey: string
})
```

* `sessionToken`: A token from your backend, is required to start the ID verification session.
* `environment`: Determines the SDK's operation environment, either `VoveEnvironment.Production` or `VoveEnvironment.Sandbox`.
* `onVerificationComplete`: An optional callback is executed with the verification status.
*  publicKey:  you can find it in the dashboard (Client Information section)

**Example Usage**

```
import { Vove, VoveEnvironment } from '@vove-id/web-sdk';

const vove = new Vove();

vove.start({
  environment: VoveEnvironment.Production,
  sessionToken: 'your_session_token_here',
  onVerificationComplete: (status) => {
    console.log('Verification status:', status);
  },
  publicKey: 'your_public_key'
});
```

#### Handling Verification Results

The verification result is communicated through the `onVerificationComplete` callback:

* The callback is invoked with a status ("success", "pending", "canceled", or "failed"), indicating the verification outcome.
* There is no need to handle a Promise's resolve or reject states since the process completion is managed through the callback function.

```typescript
const vove = new Vove();

vove.start({
    environment: VoveEnvironment.Production,
    sessionToken: 'your_session_token_here',
    onVerificationComplete: (status) => {
        switch (status) {
            case 'success':
                console.log('Verification successful.');
                break;
            case 'pending':
                console.log('Verification pending.');
                break;
            case 'canceled':
                console.log('Verification canceled.');
                break;
            default:
                console.log('Unexpected status:', status);
        }
    },
    publicKey: 'your_public_key'
});
```

### API Reference

#### `start`

Begins an ID verification session.

Parameters:

* An object containing:
  * `sessionToken`: `string`: The session token for the verification process.
  * `environment`: `VoveEnvironment`: The SDK's operational environment.
  * `onVerificationComplete`: An optional callback that is invoked with the verification status.
  * publicKey: you can find it in the dashboard (Client Information section)

#### `VoveEnvironment`

An enumeration specifying the SDK's operating environment:

* `Production`: Use for production builds.
* `Sandbox`: Use for development or testing purposes.

## Link Integration: Using Query Parameters

In addition to the standard SDK integration, you can also integrate VoveSDK using a simple link with query parameters.

### How It Works

* **Parameter Conversion:**\
  All parameters normally passed to the SDK (such as `authToken`, `environment`, `publicKey`, etc.) can be provided directly in the URL as query parameters.
* **Callback Handling:**\
  The user is redirected to the provided URL with an additional `status` query parameter that indicates the verification result (e.g., `success`, `pending`, `canceled`, or `failed`).

### Example Integration Link

You can create a link like this:

<https://web.voveid.com/?authToken=YOUR_SESSION_TOKEN&environment=Production&publicKey=YOUR_PUBLIC_KEY&lg=en&enableVocalGuidance=false&showUI=true&redirectURL=https%3A%2F%2Fyourdomain.com%2Fverification-callback>

### Handling the Redirect

On your callback page (e.g., `https://yourdomain.com/verification-callback`), retrieve and process the verification status as follows:

```javascript
// Retrieve the status from the URL query parameters
const urlParams = new URLSearchParams(window.location.search);
const verificationStatus = urlParams.get('status');

if (verificationStatus === 'success') {
  // Handle successful verification
} else {
  // Handle failure or other statuses
}
```

### Hiding the Welcome and Summary Pages

You can control whether the SDK displays its built-in welcome and summary screens using the optional showUI parameter. By default, showUI is set to true, which enables these screens. To hide them and fully manage the user experience within your app, set showUI to false.

```typescript
vove.start({
    environment: VoveEnvironment.Production,
    sessionToken: 'your_session_token_here',
    onVerificationComplete: onVerificationComplete
    showUI: false
})
```

You can also control this behavior via a query parameter in the SDK URL:

```http
https://web.voveid.com/?authToken=YOUR_SESSION_TOKEN&showUI=true&environment=Production&publicKey=YOUR_PUBLIC_KEY
```

### Troubleshooting

Ensure the session token is correctly generated and passed, and the appropriate environment is selected based on your application's stage. For unresolved issues, contact support with detailed information about the problem, including error messages and steps leading up to the issue.

<br>