Подключение

KYC Widget

Браузерный флоу верификации личности: съёмка документа, селфи и liveness-проверка (антиспуфинг). Есть четыре способа интеграции:

Тег <script> в обычном JavaScript-приложении — window.KYCWidget.setupKYC({...})
npm-пакет kyc-widget-nv в React-приложении — <KycWidget ... />
Тег <script> в React-приложении
Прямая ссылка (без интеграции) — https://kyc.neuro-vision.ru

Параметры конфигурации

Параметр	Тип	Обязательный	По умолчанию	Описание
scenarioId	`string`	Да*	—	Уникальный идентификатор сценария из раздела «KYC/AML» личного кабинета (*не требуется при использовании `taskId`)
clientKey	`string`	Да*	—	Уникальная строка (максимум 36 символов), которая передаётся в зашифрованном виде; пример кода шифрования доступен в личном кабинете в разделе «KYC/AML» (*не требуется при использовании `taskId`)
clientUser	`string`	Нет	—	Идентификатор пользователя на стороне клиента, максимум 36 символов. Не обязан быть уникальным: передавайте одно и то же значение в разных сессиях, чтобы потом поиском по нему найти все сессии (попытки) этого пользователя
taskId	`string`	Нет	—	Идентификатор задачи верификации, заранее созданной через API. Если задан, виджет открывает эту задачу напрямую, а `scenarioId`/`clientKey` не нужны
isOpen	`boolean`	Да*	—	Видимость виджета (*обязателен только для React-компонента)
theme	light	dark	Нет	настройка сценария
stickySession	`boolean`	Нет	`false`	«Липкие» сессии: виджет запоминает `clientKey` для сценария (в localStorage, на 15 минут). Повторное открытие в этом окне продолжает предыдущую сессию, даже если передан другой `clientKey`
closeCb	`function`	Нет	—	Колбэк при закрытии виджета
successCb	`function`	Нет	—	Колбэк при успешной верификации. Получает результат сессии в виде JSON-строки
finalizedCb	`function`	Нет	—	Колбэк при открытии виджета для сессии, которая уже была финализирована ранее. Получает `{ status }`
topOffset	`number`	Нет	`0`	Отступ сверху в пикселях
bottomOffset	`number`	Нет	`0`	Отступ снизу в пикселях
blurHost	`boolean`	Нет	`false`	Если `true`, фон виджета рендерится как «матовое стекло» поверх страницы хоста (без фоновой картинки и правой blur-панели) — страница хоста просвечивает через полупрозрачный размытый слой
mountElementId	`string`	Нет	—	Только для интеграции через script-тег (`widget-lib.js`). Если задан, виджет монтируется инлайн внутрь элемента с этим id, а не поверх всей страницы. Виджет заполняет хост-элемент (`width/height: 100%`), поэтому задайте элементу явные размеры. См. пример ниже. Не поддерживается внутри cross-origin iframe — браузер заблокирует камеру; в этом случае вызывается `closeCb`, чтобы хост мог сбросить своё состояние. Не вызывайте `setupKYC` внутри `closeCb` — повторные детекты iframe зациклятся

Payload колбэка successCb

successCb получает результат верификации в виде JSON-строки. Точный набор полей зависит от шагов сценария (шаг с документом приходит как "type": "document", liveness — как "type": "liveness" и т.д.). Сокращённый пример:

{
  "sessionId": "098d57-...",
  "status": "success",
  "errors": [],
  "results": [
    {
      "type": "liveness",
      "status": "success",
      "errors": [],
      "tries": 1,
      "startedAt": "2026-07-19T09:41:37.590Z",
      "faces": ["https://..."],
      "video": "https://..."
    }
  ],
  "schemaId": "3676-...",
  "clientKey": "46d1c-...",
  "clientUser": "",
  "createdAt": "2026-07-19T09:41:37.000Z",
  "secondsToLive": 0
}

1. Пример интеграции в JavaScript-приложение через script-тег (index.html)

Создайте кнопку с начальным состоянием загрузки.
Загрузите скрипт динамически и активируйте кнопку по готовности.
Вызовите window.KYCWidget.setupKYC() по клику на кнопку.

Файл: index.html

  <body>
    <button id="btn" disabled>Загрузка...</button>

    <script>
      const btn = document.getElementById("btn");

      const script = document.createElement("script");
      script.src = "https://kyc.neuro-vision.ru/lib/widget-lib.js";
      script.onload = () => {
        btn.disabled = false;
        btn.textContent = "Открыть KYC-виджет";
      };
      script.onerror = () => {
        btn.textContent = "Не удалось загрузить KYC-виджет";
      };
      document.body.appendChild(script);

      const openWidget = () => {
        window.KYCWidget.setupKYC({
          scenarioId: "scenarioId",
          clientKey: "clientKey",
          clientUser: "clientUser",
          theme: "light",
          stickySession: true,
          topOffset: 0,
          bottomOffset: 0,
          // Необязательный. Если задан, виджет монтируется ВНУТРЬ элемента
          // с этим id (инлайн-блок), а не поверх всей страницы. Элемент
          // должен существовать в DOM. При закрытии элемент очищается.
          // ⚠️ Не открывайте страницу хоста внутри cross-origin <iframe> —
          // браузер заблокирует getUserMedia, и камера не запустится.
          // mountElementId: "kyc-here",
          closeCb: () => console.log("CLOSE CALLBACK"),
          successCb: (sessionJson) => console.log("SUCCESS CALLBACK", sessionJson),
          finalizedCb: ({ status }) => console.log("FINALIZED CALLBACK", status),
        });
      };

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

2. Пример интеграции в React-приложение через npm-пакет

Установите npm-пакет kyc-widget-nv: npm i kyc-widget-nv.
Импортируйте в приложение: import { KycWidget } from "kyc-widget-nv".
Заведите переменную состояния для управления видимостью виджета.
Передайте пропсы компоненту KycWidget (см. «Параметры конфигурации» выше).

Пакет не включает React в бандл — react и react-dom должны быть установлены в вашем приложении.

Файл: App.js

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

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

  return (
    <>
      <button onClick={() => setIsOpen(true)}>Открыть</button>

      <KycWidget
        scenarioId="scenarioId"
        clientKey="clientKey"
        clientUser="clientUser"
        isOpen={isOpen}
        stickySession={true}
        theme="light"
        topOffset={0}
        bottomOffset={0}
        closeCb={() => setIsOpen(false)}
        successCb={(sessionJson) => console.log("SUCCESS CALLBACK", sessionJson)}
        finalizedCb={({ status }) => console.log("FINALIZED CALLBACK", status)}
      />

    </>
  );
}

export default App;

3. Пример интеграции в React-приложение через script-тег

Используйте этот способ, если не можете установить npm-пакет и нужно загрузить виджет через script-тег.

Загрузите скрипт виджета динамически в useEffect.
Отслеживайте состояние загрузки через useState.
Показывайте кнопку только после загрузки скрипта.
Вызовите window.KYCWidget.setupKYC() по клику на кнопку.

Файл: App.js

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

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

  const openWidgetHandler = () => {
    window.KYCWidget.setupKYC({
      scenarioId: "scenarioId",
      clientKey: "clientKey",
      clientUser: "clientUser",
      theme: "light",
      topOffset: 0,
      bottomOffset: 0,
      // Необязательный. Если задан, виджет монтируется ВНУТРЬ элемента
      // с этим id (инлайн-блок), а не поверх всей страницы. Элемент
      // должен существовать в DOM. При закрытии элемент очищается.
      // ⚠️ Не открывайте страницу хоста внутри cross-origin <iframe> —
      // браузер заблокирует getUserMedia, и камера не запустится.
      // mountElementId: "kyc-here",
      closeCb: () => console.log("CLOSE CALLBACK"),
      successCb: (sessionJson) => console.log("SUCCESS CALLBACK", sessionJson),
      finalizedCb: ({ status }) => console.log("FINALIZED CALLBACK", status),
    });
  };

  const loadWidgetScript = useCallback(() => {
    const widgetScript = document.getElementById("kyc-widget-script");
    if (widgetScript) return;

    const script = document.createElement("script");
    script.id = "kyc-widget-script";
    script.src = 'https://kyc.neuro-vision.ru/lib/widget-lib.js';
    script.defer = true;
    script.crossOrigin = "anonymous";

    script.onload = () => {
      setWidgetLoaded(true);
    };

    script.onerror = () => {
      console.error("Не удалось загрузить скрипт KYC-виджета");
    };

    document.head.appendChild(script);
  }, []);

  useEffect(() => {
    if (window.KYCWidget) {
      setWidgetLoaded(true);
      return;
    }

    loadWidgetScript();
  }, [loadWidgetScript]);

  return (
    <>
      {widgetLoaded && (
        <button onClick={openWidgetHandler}>Открыть KYC-виджет</button>
      )}
    </>
  );
}

export default App;

4. Верификация по ссылке

Для прохождения верификации можно воспользоваться сервисом https://kyc.neuro-vision.ru напрямую.

Переход по ссылке следующего вида создаёт сессию:

  https://kyc.neuro-vision.ru/scenarioId/encrypted(clientKey)
  https://kyc.neuro-vision.ru/scenarioId/encrypted(clientKey)/clientUser

scenarioId: уникальный идентификатор сценария, его нужно получить в личном кабинете в разделе «KYC/AML».
clientKey: уникальная строка (максимум 36 символов), которая передаётся в зашифрованном виде; пример кода шифрования доступен в личном кабинете в разделе «KYC/AML». Зашифрованный ключ — это base64 (может содержать / и +), поэтому при построении ссылки его нужно URL-энкодить.
clientUser: необязательный. Идентификатор пользователя на стороне клиента, максимум 36 символов. Не обязан быть уникальным — передавайте одно значение в разных сессиях, чтобы потом найти все сессии (попытки) этого пользователя.

Для задач верификации, заранее созданных через API, используйте ссылку на задачу:

  https://kyc.neuro-vision.ru/taskId
  https://kyc.neuro-vision.ru/taskId/cu/clientUser