Веб-захват

Проведите человека через захват в браузере, используя токен и ссылку, которые возвращает Human Plugin.

Markdown

Ваш бэкенд создаёт процесс в Human Plugin с потоком Journey. В ответе 201 есть три значения, которые нужны фронтенду:

Поле	Назначение
id	Идентификатор процесса Human Plugin. SDK принимает его как transactionId, и по нему ваш бэкенд читает результат
token	Запускает захват в Journeys SDK
link	Размещённая страница захвата

token и link возвращаются только при создании. Передайте их фронтенду в том же запросе или сохраните самостоятельно. См. Human Token Journey.

Требования

Захват выполняется в браузере и требует доступа к камере.

ОС	Chrome	Firefox	Safari	Samsung Internet	Opera	Edge
Windows	✅	✅	N/A	N/A	❌	❌
macOS	✅	✅	✅	N/A	❌	❌
Android	✅	❌	N/A	✅	❌	❌
iOS	✅	✅	✅	N/A	❌	❌

• Страницы должны отдаваться по HTTPS. Камера работает только в защищённом контексте.
• Для встроенного просмотра требуется Android 8 (API 26) или iOS 13 и новее.
• Браузеры внутри приложений социальных сетей не поддерживаются.

Выберите модель

Модель	Подходит для
Размещённая ссылка	Самая простая настройка. Без библиотеки: человек переходит по link и возвращается на ваш callbackUri
Journeys SDK	Захват открывается внутри вашей страницы, поэтому человек не покидает её

Размещённая ссылка

Передайте callbackUri в запросе на создание. Это страница, на которую человек возвращается по окончании захвата.

{
  "flow": "humantoken",
  "clientId": "client-a",
  "correlationId": "order-1001",
  "credential": { "type": "DUI_TYPE_NG_BVN", "value": "<document number>" },
  "callbackUri": "https://app.example.com/capture/done"
}

Затем направьте человека на link одним из двух способов:

• Перенаправление. Перейдите на link. По окончании человек будет возвращён на callbackUri.
• Новая вкладка. Откройте link через window.open(), дождитесь, пока вкладка дойдёт до callbackUri, и закройте её.

Когда человек вернулся, сообщите об этом вашему бэкенду, который вызывает GET /v1/processes/{id}.

Journeys SDK

SDK открывает захват в iFrame на вашей странице. Он работает с любым фреймворком (React, Angular, Vue) или с обычным JavaScript.

Прежде чем начать, попросите службу поддержки Unico зарегистрировать ваши домены. Они должны использовать HTTPS.

1. Установите

npm install unico-journey-sdk

SDK следует семантическому версионированию, поэтому минорные обновления и обновления патчей безопасно устанавливать. Поддерживайте SDK в актуальном состоянии: исправления безопасности и ошибок выходят в новых версиях.

2. Разрешите SDK в ваших заголовках

Пропустите этот шаг, если ваша страница не отправляет заголовки Content-Security-Policy и Permissions-Policy. В противном случае добавьте:

Content-Security-Policy:

frame-src https://*.unico.io https://*.unico.app;
script-src https://idpay.unico.io;
style-src https://idpay.unico.io;
connect-src https://api.cadastro.unico.app;

Permissions-Policy:

camera=(self "https://human-token.unico.io" "https://cadastro.unico.app" "https://id.unico.io" "https://retry.unico.io" "https://ultimatum.unico.io"),
geolocation=(self "https://human-token.unico.io" "https://cadastro.unico.app" "https://id.unico.io" "https://retry.unico.io" "https://ultimatum.unico.io")

3. Инициализируйте

Вызовите init, как только станет известно, что нужен захват. Он выполняет предварительную загрузку захвата.

import { ByUnicoSDK } from 'unico-journey-sdk';

ByUnicoSDK.init({ token });

4. Откройте захват

Параметр	Обязателен	Значение
transactionId	Да	id из Human Plugin
token	Да	token из ответа на создание
onFinish	Да	Вызывается, когда захват завершён или человек его закрыл
onWidgetVisibilityChange	Нет	Вызывается, когда захват показан или скрыт

ByUnicoSDK.open({
  transactionId: id, // the Human Plugin id
  token,
  onFinish: ({ type }) => {
    if (type === 'FINISH') {
      // The capture ended. Ask your back-end to read the outcome.
    }
    // type === 'CLOSE': the person closed it before the end.
  },
  // Optional: hide your own overlays while the capture is visible.
  onWidgetVisibilityChange: (visible) => {},
});

// To close it yourself:
ByUnicoSDK.close();

onFinish получает:

Поле	Описание
type	'FINISH', если захват завершён, 'CLOSE', если человек закрыл его раньше
transaction.redirectUrl	Куда направить человека дальше. Присутствует только для 'FINISH'

предупреждение

onFinish сообщает, что захват завершён, но не как именно. Результат можно получить только через GET /v1/processes/{id} на вашем бэкенде.

Используйте onFinish также для перехода человека на следующий экран и чтобы не создавать новый процесс сразу же, если он начнёт заново.

Устранение неполадок

• Поток ломается или ведёт себя странно. Убедитесь, что ни один из ваших скриптов не изменяет iFrame SDK в DOM.
• Захват выглядит иначе. Общие правила CSS, например селекторы по тегам, могут затрагивать iFrame. Собственные идентификаторы и классы SDK начинаются с unico.
• Неожиданные ошибки после обновления. Устанавливайте SDK только через npm или yarn и никогда не редактируйте его файлы.

Тестирование

Закройте DevTools браузера, прежде чем тестировать захват от начала до конца. Открытые DevTools блокируют отправку.

Неподдерживаемые конфигурации

• SDK внутри мобильного WebView. В приложении откройте link. См. руководства для Android, iOS, Ionic, React Native и Flutter.
• Собственный <iframe>, указывающий на захват. Используйте SDK, который сам управляет iFrame.