Идентификаторы проверки: clientKey и clientUser

У каждой проверки в Web SDK есть два идентификатора, которые задаёте вы, и два, которые назначает система. Прочитайте этот раздел до подключения виджета: от того, как вы выберете clientKey и clientUser, зависит, сможете ли вы повторить проверку и найти все попытки одного человека.

ИдентификаторКто задаётЧто обозначает
clientKeyВыОдну попытку проверки
clientUserВыЧеловека в вашей системе
clientIdСистемаЧеловека, которого система узнала по лицу
isClientNewСистемаВстречалось ли это лицо раньше

clientKey — одна попытка

clientKey — идентификатор одной попытки проверки. Один ключ — одна сессия: она создаётся при первом запуске виджета с этим ключом и навсегда остаётся за ним.

  • Создавайте новый clientKey для каждого запуска проверки, в том числе для повторной проверки того же человека.
  • Ключ уникален в пределах вашего аккаунта, во всех его сценариях: ключ, уже использованный в одном сценарии, в другом сценарии того же аккаунта откроет ту же сессию.
  • Строка до 36 символов. В виджет ключ передаётся только в зашифрованном виде — см. Работа с clientKey.
  • Не используйте в качестве ключа идентификатор пользователя: у человека может быть несколько попыток, а ключ у попытки один.

Храните у себя таблицу «попытка → пользователь». По ней вы сопоставите вебхук или ответ API с человеком в своей системе:

clientKey (ваша попытка)clientUser (ваш пользователь)Когда созданаИтог
a7f3c2e1-0b4d-4e8a-9c21-5d6e7f809a1busr-00422026-03-02 10:15failed
c94b1d07-2e3f-4a5b-8c6d-7e8f9a0b1c2dusr-00422026-03-02 10:31success
e1d2c3b4-a596-4877-8695-a4b3c2d1e0f9usr-01072026-03-03 09:02expired

Здесь у пользователя usr-0042 две попытки: первая завершилась отказом, вторую вы запустили с новым ключом.


clientUser — человек в вашей системе

clientUser — идентификатор человека в вашей системе, строка до 36 символов. Параметр необязательный.

  • Он не уникален для сессии: передавайте одно и то же значение во все попытки одного человека, так попытки объединяются в группу.
  • clientUser запоминается при первом запуске ключа. Если позже открыть ту же сессию с другим clientUser, у сессии останется первое значение.
  • По clientUser можно удалить данные всех сессий человека методом уничтожения сессии в REST API.
  • При сравнении с эталонной сессией через REST API передаётся тот же clientUser, что был у эталонной сессии в виджете.

Не передавайте персональные данные ни в clientKey, ни в clientUser — ни ФИО, ни телефон, ни email, ни номер документа. Оба значения остаются в сессии и в журнале даже после уничтожения её данных. Используйте собственный непрозрачный идентификатор, например UUID или внутренний номер.


Когда запускать проверку и когда повторять

Когда запустить проверку и нужна ли повторная попытка, решаете вы. Повторная попытка — это всегда новый clientKey с тем же clientUser.

Ограничения системы, в которых вы это решаете:

  • Попытки внутри шага. В одной сессии у каждого шага (съёмка документа, селфи, liveness) ограниченное число попыток. Пользователь переснимает кадр в той же сессии, новый ключ для этого не нужен.
  • Попытки исчерпаны. Если пользователь исчерпал попытки шага, сессия завершается отказом; для всех шагов, кроме liveness, в errors приходит код [general] too many tries. Продолжить такую сессию нельзя: чтобы проверить человека ещё раз, запустите новую попытку с новым clientKey.
  • Время жизни сессии. Сессия, которую не завершили вовремя, получает статус expired. Для новой проверки — новый clientKey.
  • «Липкие» сессии. Если включён параметр stickySession, виджет в течение 15 минут продолжает предыдущую сессию сценария, даже если передан другой clientKey. Если повторные попытки запускаются сразу одна за другой, не включайте stickySession.

Что будет при повторном запуске с тем же clientKey

Новая сессия по уже использованному ключу не создаётся. Виджет открывает сессию этого ключа в её текущем состоянии:

Состояние сессии ключаЧто происходит
Не завершена, время жизни не истеклоПользователь продолжает ту же попытку с того места, где остановился
Завершена успешно (success)Виджет сразу показывает экран результата, вызывается finalizedCb со статусом success
Завершена отказом, в том числе после исчерпания попытокЭкран результата, finalizedCb с итоговым статусом сессии
Истекло время жизниЭкран истёкшей сессии, finalizedCb со статусом expired
Данные сессии уничтоженыНовая сессия не создаётся; для новой проверки нужен новый ключ

clientId и isClientNew — назначает система

clientId и isClientNew система назначает сама, передать их в виджет или в API нельзя. Они приходят в результате сессии, в вебхуке и в ответе статуса сессии.

  • clientId — идентификатор человека, которого система узнала по лицу. Он заполняется после успешного прохождения всех шагов и сравнения лиц, если к сценарию подключена база лиц. До этого и в сценариях без поиска по лицу clientId пустой.
  • isClientNew — true, если лицо встретилось впервые, false, если система нашла этого человека среди прежних проверок.

clientId не заменяет clientUser: clientUser — ваш идентификатор человека, clientId — результат сравнения лиц.


Пример запуска

На сервере создайте ключ новой попытки, запишите пару «попытка → пользователь» и зашифруйте ключ секретным ключом сценария, как описано в разделе Работа с clientKey. В браузер передайте только зашифрованный ключ.

// Сервер: новая попытка для пользователя usr-0042
const crypto = require("crypto");

const clientKeyRaw = crypto.randomUUID(); // новый ключ на каждый запуск
await attempts.insert({ clientKey: clientKeyRaw, clientUser: "usr-0042" });
const encryptedClientKey = encryptClientKey(clientKeyRaw); // AES-256-CBC секретным ключом сценария
// Браузер: запуск виджета
window.KYCWidget.setupKYC({
  scenarioId: "3f2a9c1e-5b7d-4e8f-a012-3456789abcde",
  clientKey: encryptedClientKey, // зашифрованный ключ этой попытки
  clientUser: "usr-0042",        // тот же у всех попыток пользователя
  closeCb: () => console.log("Виджет закрыт"),
  successCb: (sessionJson) => console.log("Проверка пройдена", sessionJson),
  finalizedCb: ({ status }) => {
    // Ключ уже использован. Для новой проверки запросите у сервера новый clientKey.
    console.log("Сессия этого ключа уже завершена:", status);
  },
});

Итог проверки принимайте на сервере по вебхуку или статусу сессии, а не по колбэкам в браузере.