Подключение

В этом разделе описано, как подключить WebSDK к вашему проекту, какие зависимости требуются и как начать работу. Полный список параметров (включая schemaId, clientKey, колбэки и тему) — в разделе «Параметры». Подробнее про назначение и безопасную работу с clientKey см. «Работа с clientKey». Для обработки результатов используйте REST API статусов KYC‑сессии.

Быстрый старт (чистый HTML/JS)

Самый простой способ — подключить библиотеку виджета <script>‑тегом и вызвать window.KYCWidget.setupKYC(...) по клику на кнопку.

`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";          // обязателен: ID вашей схемы (сценария) проверки
    const clientKey = "ENCRYPTED_CLIENT_KEY"; // обязателен: ключ клиента (см. clientKey)

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

      window.KYCWidget.setupKYC({
        schemaId,                    // используйте именно schemaId (устаревшее название: scenarioId)
        clientKey,                   //  передавать
        theme: "light",              // 'light' или 'dark'
        closeCb: () => console.log("CLOSE CALLBACK"),
        successCb: (payload) => {
          console.log("SUCCESS CALLBACK", payload);
          // payload содержит данные по сессии; для детального статуса используйте API /kyc/session/status
        },
      });
    }

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

Где взять schemaId? Это идентификатор вашей схемы (сценария) KYC — например, «паспорт + селфи с документом». Вы увидите его в ЛК при настройке схемы.

Вариант с «ленивой» загрузкой скрипта (чистый JS)

Если хотите загружать библиотеку только при первом открытии, используйте динамический лоадер:

<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: подключение через `<script>` (универсально)

Подходит, если не хотите тянуть npm‑пакет. Скрипт грузим динамически, чтобы не блокировать отрисовку:

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: подключение через npm‑пакет

Если вы предпочитаете компонентный подход, можно использовать пакет kyc-widget.

Установка:

npm i kyc-widget

Использование компонента:

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;

Что передать в `setupKYC(...)`

Минимально достаточно:

schemaId *(string, обязательно)* — идентификатор вашей схемы/сценария KYC;
clientKey *(string, обязательно)* — ключ клиента для сопоставления вашей учётной записи с сессией KYC;
theme *(string, опционально)* — 'light' или 'dark';
closeCb() — колбэк закрытия виджета;
successCb(payload) — колбэк успешного завершения; для углублённой обработки получите подробный статус через API /kyc/session/status.

Полный перечень параметров и типы смотрите в разделе «Параметры».

`clientKey`: генерация на backend

clientKey — произвольная строка до 36 символов, через неё удобно пробрасывать ID вашего пользователя, чтобы затем замэпить результат KYC на вашу модель данных. Ключ шифруется на вашем сервере «секретым ключом сценария» и передаётся в виджет в зашифрованном виде.

Node.js (пример шифрования AES‑256‑CBC):

const crypto = require("crypto");

let clientKey = "anyString"; // до 36 символов
const password = "scenarioSecretKey"; // секрет сценария (хранится только на 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}`);

Никогда не храните scenarioSecretKey в браузере; генерируйте clientKey только на сервере и передавайте в фронтенд уже зашифрованное значение. Подробности — в разделе «Работа с clientKey».

Проверка результата

После successCb вы можете получить полный статус сессии через REST API:

Проверить статус сессии — /kyc/session/status
Создать сессию / обработать изображения — /kyc/session/create, /kyc/process

Примеры запросов и ответы приведены в разделе API KYC.

Если в процессе виджет вернёт ошибки (например, «[document] text fields not visible» или «[fraud] image printed»), расшифровку кодов и рекомендации по обработке вы найдёте в справочнике ошибок.

Быстрый старт (чистый HTML/JS)

index.html