KYC Widget

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

1. Тег <script> в обычном JavaScript-приложении — window.KYCWidget.setupKYC({...})
2. npm-пакет kyc-widget-nv в React-приложении — <KycWidget ... />
3. Тег <script> в React-приложении
4. Прямая ссылка (без интеграции) — 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)

1. Создайте кнопку с начальным состоянием загрузки.
2. Загрузите скрипт динамически и активируйте кнопку по готовности.
3. Вызовите 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-пакет

1. Установите npm-пакет kyc-widget-nv: npm i kyc-widget-nv.
2. Импортируйте в приложение: import { KycWidget } from "kyc-widget-nv".
3. Заведите переменную состояния для управления видимостью виджета.
4. Передайте пропсы компоненту 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-тег.

1. Загрузите скрипт виджета динамически в useEffect.
2. Отслеживайте состояние загрузки через useState.
3. Показывайте кнопку только после загрузки скрипта.
4. Вызовите 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/clientKey
  https://kyc.neuro-vision.ru/scenarioId/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