Connection - NeuroVision

This section describes how to connect the WebSDK to your project, what dependencies are required, and how to get started. A full list of parameters (including schemaId, clientKey, callbacks, and theme) can be found in the “Parameters” section. For more information on the purpose and secure use of clientKey, see “Working with clientKey”. Use the KYC session status REST API to process the results.

Quick Start (Plain HTML/JS)

The simplest way is to connect the widget library with a <script> tag and call window.KYCWidget.setupKYC(...) on button click.

`index.html`

<!DOCTYPE html>
<html lang="ru">
<head>
  <meta charset="UTF-8" />
  <title>KYC Widget Example</title>
  <!-- Подключаем библиотеку виджета -->
  <script src="https://kyc.neuro-vision.ru/lib/widget-lib.js" defer crossorigin="anonymous"></script>
</head>
<body>
  <button id="btn">Open KYC Widget</button>

  <!-- Инициализация виджета -->
  <script>
    const schemaId  = "SCHEMA_ID";          // required: Your verification scheme (scenario) ID
    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 specifically (deprecated name: scenarioId)
        clientKey,                   // transmit
        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 the /kyc/session/status API
        },
      });
    }

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

Where to get schemaId? This is the identifier of your KYC schema (scenario) — for example, “passport + selfie with document”. You will see it in the Personal Account when setting up the schema.

Option with “lazy” script loading (pure JS)

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

<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.neuro-vision.ru/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 pull an npm package. We load the script dynamically so as not to block rendering:

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.neuro-vision.ru/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-based approach, you can use the kyc-widget package.

Installation:

npm i kyc-widget

Using the component:

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 to `setupKYC(...)`

Bare minimum:

schemaId *(string, required)* — the identifier of your KYC schema/scenario;
clientKey *(string, required)* — the client key to associate your account with the KYC session;
theme *(string, optional)* — 'light' or 'dark';
closeCb() — widget close callback;
successCb(payload) — success callback; for in-depth processing, get detailed status via the /kyc/session/status API.

See the “Parameters” section for a full list of parameters and types.

`clientKey`: generation on the backend

clientKey is an arbitrary string of up to 36 characters, which is convenient for passing your user ID through, to then map the KYC result to your data model. The key is encrypted on your server with a “script secret key” and transmitted to the widget in encrypted form.

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

const crypto = require("crypto");

let clientKey = "anyString"; // up to 36 characters
const password = "scenarioSecretKey"; // script secret (stored only on backend)

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 the server and pass the already encrypted value to the frontend. Details are in the section “Working with clientKey”.

Check the result

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

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

Examples of requests and responses are provided in the KYC API section.

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

Quick Start (Plain HTML/JS)

index.html