У каждой проверки в Web SDK есть два идентификатора, которые задаёте вы, и два, которые назначает система. Прочитайте этот раздел до подключения виджета: от того, как вы выберете clientKey и clientUser, зависит, сможете ли вы повторить проверку и найти все попытки одного человека.
| Идентификатор | Кто задаёт | Что обозначает |
|---|---|---|
clientKey | Вы | Одну попытку проверки |
clientUser | Вы | Человека в вашей системе |
clientId | Система | Человека, которого система узнала по лицу |
isClientNew | Система | Встречалось ли это лицо раньше |
clientKey — одна попытка
clientKey — идентификатор одной попытки проверки. Один ключ — одна сессия: она создаётся при первом запуске виджета с этим ключом и навсегда остаётся за ним.
- Создавайте новый
clientKeyдля каждого запуска проверки, в том числе для повторной проверки того же человека. - Ключ уникален в пределах вашего аккаунта, во всех его сценариях: ключ, уже использованный в одном сценарии, в другом сценарии того же аккаунта откроет ту же сессию.
- Строка до 36 символов. В виджет ключ передаётся только в зашифрованном виде — см. Работа с clientKey.
- Не используйте в качестве ключа идентификатор пользователя: у человека может быть несколько попыток, а ключ у попытки один.
Храните у себя таблицу «попытка → пользователь». По ней вы сопоставите вебхук или ответ API с человеком в своей системе:
| clientKey (ваша попытка) | clientUser (ваш пользователь) | Когда создана | Итог |
|---|---|---|---|
a7f3c2e1-0b4d-4e8a-9c21-5d6e7f809a1b | usr-0042 | 2026-03-02 10:15 | failed |
c94b1d07-2e3f-4a5b-8c6d-7e8f9a0b1c2d | usr-0042 | 2026-03-02 10:31 | success |
e1d2c3b4-a596-4877-8695-a4b3c2d1e0f9 | usr-0107 | 2026-03-03 09:02 | expired |
Здесь у пользователя 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);
},
}); Итог проверки принимайте на сервере по вебхуку или статусу сессии, а не по колбэкам в браузере.