# Installation

This section describes how to connect the WebSDK to your project, what dependencies are required, and how to get started. The full list of parameters (including `schemaId`, `clientKey`, callbacks, and theme) is in the **“Parameters”** section. For details on the purpose and secure handling of `clientKey`, see **“Working with clientKey”**. To process results, use the KYC session status REST API.

***

## Quick start (plain HTML/JS)

The simplest method is to include the widget library via a `<script>` tag and call `window.KYCWidget.setupKYC(...)` on a button click.

**`index.html`**

```html
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <title>KYC Widget Example</title>
  <!-- Include widget library -->
  <script src="https://kyc.nv.global/lib/widget-lib.js" defer crossorigin="anonymous"></script>
</head>
<body>
  <button id="btn">Open KYC Widget</button>

  <!-- Widget initialization -->
  <script>
    const schemaId  = "SCHEMA_ID";            // required: ID of your verification schema
    const clientKey = "ENCRYPTED_CLIENT_KEY"; // required: client key (see clientKey)

    function openWidget() {
      if (!window.KYCWidget) {
        console.error("KYCWidget is not loaded yet");
        return;
      }

      window.KYCWidget.setupKYC({
        schemaId,                     // use schemaId (deprecated: scenarioId)
        clientKey,
        theme: "light",               // 'light' or 'dark'
        closeCb: () => console.log("CLOSE CALLBACK"),
        successCb: (payload) => {
          console.log("SUCCESS CALLBACK", payload);
          // payload contains session data; for detailed status use API /kyc/session/status
        },
      });
    }

    document.getElementById("btn").addEventListener("click", openWidget);
  </script>
</body>
</html>
```

> **Where to get `schemaId`?** It is the ID of your verification schema (scenario) — for example “passport + selfie with document”. You’ll find it in the dashboard when configuring a schema.

***

## Lazy loading script (plain JS)

If you want to load the library only on first use, use a dynamic loader:

```html
<script>
  function loadKYCWidgetScript(callback) {
    if (window.KYCWidget) { callback(); return; }
    if (document.getElementById("kyc-widget-script-id")) return;

    const s = document.createElement("script");
    s.id = "kyc-widget-script-id";
    s.src = "https://kyc.nv.global/lib/widget-lib.js";
    s.defer = true;
    s.crossOrigin = "anonymous";
    s.onload = callback;
    document.head.appendChild(s);
  }

  function openKYCWidget() {
    window.KYCWidget.setupKYC({
      schemaId:  "SCHEMA_ID",
      clientKey: "ENCRYPTED_CLIENT_KEY",
      theme: "light",
      closeCb: () => console.log("CLOSE CALLBACK"),
      successCb: (payload) => console.log("SUCCESS CALLBACK", payload),
    });
  }

  document.addEventListener("DOMContentLoaded", () => {
    const button = document.getElementById("open-widget-btn");
    loadKYCWidgetScript(() => { button.disabled = false; });
    button.addEventListener("click", openKYCWidget);
  });
</script>

<button id="open-widget-btn" disabled>Open KYC Widget</button>
```

***

## React: connecting via `<script>` (universal)

Suitable if you don’t want to use the npm package. Script is loaded dynamically:

```jsx
import { useState, useEffect, useCallback } from "react";

function App() {
  const [widgetLoaded, setWidgetLoaded] = useState(false);

  const openWidgetHandler = () => {
    window.KYCWidget.setupKYC({
      schemaId:  "SCHEMA_ID",
      clientKey: "ENCRYPTED_CLIENT_KEY",
      theme: "light",
      closeCb: () => console.log("CLOSE CALLBACK"),
      successCb: (payload) => console.log("SUCCESS CALLBACK", payload),
    });
  };

  const loadWidgetScript = useCallback(() => {
    if (window.KYCWidget || document.getElementById("kyc-widget-script-id")) {
      setWidgetLoaded(true);
      return;
    }
    const script = document.createElement("script");
    script.id = "kyc-widget-script-id";
    script.src = "https://kyc.nv.global/lib/widget-lib.js";
    script.defer = true;
    script.crossOrigin = "anonymous";
    script.onload = () => setWidgetLoaded(true);
    document.head.appendChild(script);
  }, []);

  useEffect(() => {
    loadWidgetScript();
  }, [loadWidgetScript]);

  return (
    <>
      {widgetLoaded && (
        <button onClick={openWidgetHandler}>Open KYC Widget</button>
      )}
    </>
  );
}

export default App;
```

***

## React: connecting via npm package

If you prefer a component approach, use the `kyc-widget` package.

1. Install:

```bash
npm i kyc-widget
```

2. Use component:

```jsx
import { useState } from "react";
import { KycWidget } from "kyc-widget";

function App() {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <>
      <button onClick={() => setIsOpen(true)}>Open</button>

      <KycWidget
        schemaId="SCHEMA_ID"
        clientKey="ENCRYPTED_CLIENT_KEY"
        isOpen={isOpen}
        closeCb={() => setIsOpen(false)}
        successCb={(payload) => console.log("SUCCESS CALLBACK", payload)}
      />
    </>
  );
}

export default App;
```

***

## What to pass into `setupKYC(...)`

Minimum:

* **`schemaId`** *(string, required)* — ID of your KYC schema/scenario;
* **`clientKey`** *(string, required)* — client key used to link your user/account to the KYC session;
* **`theme`** *(string, optional)* — `'light'` or `'dark'`;
* **`closeCb()`** — callback when widget closes;
* **`successCb(payload)`** — callback when verification completes; for detailed processing retrieve status via `/kyc/session/status`.

Full parameter list is in the **“Parameters”** section.

***

## `clientKey`: backend generation

`clientKey` is any string up to **36** characters; it’s used to associate your user ID with the KYC session. The key is encrypted on your backend using the “scenario secret key” and sent to the widget in encrypted form.

**Node.js (AES‑256‑CBC encryption example):**

```js
const crypto = require("crypto");

let clientKey = "anyString"; // up to 36 chars
const password = "scenarioSecretKey"; // scenario secret key (backend only)

const key = crypto.createHash("sha256").update(password).digest().subarray(0, 32);
const iv  = crypto.randomBytes(16);

const cipher = crypto.createCipheriv("aes-256-cbc", key, iv);
const encrypted = Buffer.concat([cipher.update(clientKey, "utf8"), cipher.final()]);

const encryptedBase64 = Buffer.concat([iv, encrypted]).toString("base64");
console.log(`Encrypted & Base64: ${encryptedBase64}`);
```

> Never store `scenarioSecretKey` in the browser; generate `clientKey` only on backend and pass only the encrypted value to frontend. Details are in **“Working with clientKey”**.

***

## Checking the result

After `successCb`, you can retrieve the full session status via REST API:

* **Check session status** — `/kyc/session/status`
* **Create session / process images** — `/kyc/session/create`, `/kyc/process`

Request examples and responses are in the KYC API section.

If the widget returns errors (e.g., “\[document] text fields not visible” or “\[fraud] image printed”), you can find error descriptions and handling recommendations in the error reference.

***
