Интеграция Web-приложения
На этой странице описывается, как работают путешествия (journeys) Unico и какие модели интеграции доступны для их встраивания в приложение.
Путешествие (journey) — это набор шагов, которые пользователь проходит для завершения верификации личности. Например: фотографирование документа и выполнение захвата лица (liveness).
Unico управляет всем опытом. Усилия по интеграции минимальны: путешествие создается через CreateProcess, пользователь направляется к нему, и результат получается в конце. Всё промежуточное — экраны, инструкции, валидации — уже создано и поддерживается Unico.
Две модели интеграции
У каждого клиента разные потребности. Unico предлагает две модели для направления пользователя к путешествию.
| Модель | Лучше всего подходит для |
|---|---|
| Прямой доступ | Мобильные приложения, уже использующие WebView, или веб-потоки, где путешествие может происходить за пределами основной страницы |
| Journeys SDK | Веб-приложения, которым нужен интегрированный бесшовный опыт, удерживающий польз ователя в той же среде |
- Прямой доступ
- Journeys SDK
Пользователь перенаправляется на ссылку, размещённую Unico, где проходит путешествие. По завершении
он возвращается на URL, определённый при создании процесса (параметр callbackUri).
Это самый простой подход: он не требует установки библиотеки и хорошо работает, когда путешествие не нужно проводить внутри собственной страницы приложения. С другой стороны, перевод пользователя за пределы среды клиента, как правило, создаёт больше трения и, соответственно, более высокий процент отказов.
После создания процесса ответ API включает URL путешествия, размещённого Unico. Есть два распространённых способа направить пользователя:
- Стандартный редирект. Пользователь перенаправляется непосредственно на URL путешествия. По завершении
Unico перенаправляет его обратно на
callbackUri, определённый при создании процесса. - Новая вкладка с
window.open(). Путешествие открывается в новой вкладке браузера, удерживая пользователя в отдельном контексте. В этом случае рекомендуется отслеживать изменение URL наcallbackUriи закрывать вкладку после завершения процесса. Подробности об API см. в документации MDN.
В мобильных приложениях обычно используется WebView для прямого открытия путешествия без
дополнительного перенаправления. В этом случае callbackUri также принимает deeplink, позволяя
завершению путешествия запустить открытие конкретного экрана в нативном приложении.
Просто настройте deeplink как место назначения для возврата, и операционная система обеспечит
маршрутизацию пользователя в нужное место.
Путешествие происходит внутри самого приложения, не выводя пользователя из его контекста. Journeys SDK устанавливается в приложение и используется для открытия путешествия при необходимости.
Это рекомендуемый путь для более интегрированного и бесшовного опыта, удерживающего пользователя в той же среде на протяжении всего процесса, что, как правило, снижает трение и отказы в потоке.
Unico предоставляет библиотеку JavaScript, совместимую с современными браузерами, позволяющую интегрировать путешествие практически в любое приложение всего несколькими строками кода.
Совместимость
Библиотека разработана для вписывания в любой проект без трения, независимо от используемого стека:
- Любое веб-приложение. Распространяется в формате UMD, работает при импорте через современные бандлеры (такие как webpack или Vite). Совместима с любым фреймворком (React, Angular, Vue) или чистым JavaScript.
- Современные браузеры. Библиотека уже включает необходимые полифиллы для функций, таких как
Promises и
async/await, расширяя совместимость также на более старые версии браузеров. - Стандартные веб-API. Путешествие работает на нативных возможностях браузера, без зависимости от плагинов ил и внешних библиотек в проекте.
Как SDK работает внутри
Когда путешествие открывается, SDK вставляет iFrame на страницу и берёт контроль над всем визуальным опытом с этого момента. Экраны, скрипты и ресурсы каждого шага работают внутри этого iFrame, с момента начала пользователем до завершения процесса.
Это архитектурное решение намеренное: изоляция iFrame гарантирует, что путешествие Unico не вмешивается в стили или поведение приложения. Ни один скрипт не попадает во внешний контекст, ни одно правило CSS не конфликтует со стилями приложения. Результат — последовательный опыт для конечного пользователя и минимальное влияние на продукт клиента.
Поскольку Unico отвечает за создание и управление iFrame, улучшения путешествия — будь то производительность, опыт или валидация — доставляются автоматически всем пользователям, без необходимости изменений в интегрированном приложении. Интеграция всегда будет работать с л учшими доступными оптимизациями, без необходимости отслеживать или реагировать на каждое обновление платформы.
Начало работы
Шаг 1 — Установка
Пакет idpay-b2b-sdk используется совместно между платёжными путешествиями IDPay и путешествиями
верификации личности. Для случаев использования идентификации импортируйте класс ByUnicoSDK, как показано в шагах ниже.
npm install idpay-b2b-sdk
Рекомендуемый способ установки Journeys SDK — через менеджер пакетов, такой как npm или yarn, из пакета, доступного в npm registry. Помимо упрощения установки и управления зависимостями, этот подход обеспечивает чёткий контрол ь над используемой версией и упрощает обновление при публикации новой версии.
SDK следует семантическому версионированию (SemVer), что означает, что патч- и минорные обновления не вносят критических изменений. Безопасно настроить проект на автоматическое получение этих обновлений. Изменения, которые могут потребовать обновления интеграции, зарезервированы для мажорных версий и всегда сопровождаются руководством по миграции.
Оставаться на последней версии особенно важно по двум причинам. Первая — безопасность: патчи безопасности публикуются при обнаружении уязвимостей или возможностей для усиления протокола связи. Использование устаревшей версии означает пропуск этих исправлений и подвержение потока ненужному риску. Вторая — стабильность: исправления ошибок распространяются тем же способом, и более старые версии могут демонстрировать поведение, уже исправленное в более новых релизах.
Перед началом зарегистрируйте свои домены в службе поддержки Unico. Все домены должны использовать HTTPS.
Шаг 2 — Настройка CSP и Permissions-Policy
Если ваша страница уже отправляет заголовки Content-Security-Policy или Permissions-Policy, добавьте следующие директивы, чтобы iFrame, скрипты и доступ к камере SDK работали корректно.
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");
Если ваша страница не отправляет заголовки CSP или Permissions-Policy, вы можете пропустить этот шаг — браузер не применяет ограничений по умолчанию.
Шаг 3 — Вызов init(options)
Инициализирует SDK и предварительно загружает скрипты, необходимые для корректной работы путешествия, создавая более плавный опыт для конечного пользователя. Вызывайте это как можно раньше в потоке.
| Параметр | Обязателен | Описание |
|---|---|---|
token | Да | Токен процесса, возвращённый API Create Process |
env | Нет | У становите 'uat' только для тестовых сред |
import { ByUnicoSDK } from 'idpay-b2b-sdk';
ByUnicoSDK.init({
token,
// env: 'uat' // only for test environments
});
Шаг 4 — Вызов open(options)
Отображает iFrame и запускает путешествие для пользователя. С этого момента всё происходит автоматически внутри iFrame, без необходимости управлять какими-либо промежуточными шагами.
| Параметр | Обязателен | Описание |
|---|---|---|
transactionId | Да | ID процесса, возвращённый API Create Process |
token | Да | Токен процесса, возвращённый API Create Process |
onFinish | Да | Коллбэк, выполняемый при завершении или закрытии путешествия |
onWidgetVisibilityChange | Нет | Коллбэк, выполняемый при изменении состояния видимости виджета |
Следующее взаимодействие с приложением происходит, когда путешествие заканчивается, независимо от того,
завершил ли пользователь его или закрыл. В этот момент SDK вызывает коллбэк onFinish, переданный
как параметр в open. Оттуда приложение может вызвать API getProcess для проверки результата
или дождаться уведомления Webhook, если предпочтителен асинхронный подход.
Помимо запроса результата, рекомендуется использовать onFinish для управления состоянием
фронтенда приложения:
- Избегайте циклов. Предотвращайте немедленное и ненужное повторное создание процессов, если пользователь снова запускает поток сразу после завершения путешествия.
- Управление потоком. Убедитесь, что пользователь направлен на следующий шаг приложения, избегая тупикового экрана после закрытия путешествия.
Коллбэк onFinish сигнализирует о том, что пользователь завершил путешествие, но не гарантирует
одобрение. Процесс мог завершиться с ошибкой по одному из правил валидации Unico.
Запрос через getProcess или получение уведомления Webhook не являются необязательными: это
единственные источники фактического результата, и поведение приложения должно основываться на них.
onFinish не должен использоваться изолированно для определения, был ли пользователь одобрен.
Коллбэк onFinish получает объект, описывающий, как завершилось путешествие:
| Поле | Тип | Описание |
|---|---|---|
type | string | Как завершилось путешествие: 'FINISH' (завершено) или 'CLOSE' (пользователь закрыл до завершения) |
transaction | object | undefined | Присутствует, когда type равен 'FINISH'; undefined, когда type равен 'CLOSE' |
transaction.id | string | Идентификатор процесса (совпадает с переданным transactionId) |
transaction.redirectUrl | string | URL для перенаправления пользователя после путешествия |
Обработка коллбэка onWidgetVisibilityChange является необязательной и может быть нерелевантной
для вашего случая использования. Он вызывается при каждом изменении состояния видимости виджета и
полезен только в конкретном сценарии: некоторые путешествия отображают прозрачный фон, сохраняя
страницу приложения видимой за опытом. Приложения, показывающие пользовательское модальное окно во
время потока верификации (например, в рамках оркестрации между несколькими провайдерами KYC), могут
отображать это модальное окно позади виджета Unico, ухудшая визуальный опыт. В этом случае коллбэк
позволяет приложению подавлять любые дополнительные визуальные элементы, пока путешествие Unico активно,
и восстанавливать их после его завершения. Если у вашего приложения нет UI, который мог бы
перекрывать виджет, вы можете безопасно его опустить.
ByUnicoSDK.open({
transactionId: '9bc22bac-1e64-49a5-94d6-9e4f8ec9a1bf',
token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
onFinish: ({ transaction, type }) => {
if (type === 'FINISH') {
// Journey completed (transaction = { id, redirectUrl }) — continue your flow here.
}
// type === 'CLOSE' → user closed before finishing;
},
// Optional: only needed if your app shows UI that could overlap the widget.
onWidgetVisibilityChange: (visible) => {
// suppress or restore your modal based on widget visibility
},
});
// To close the SDK explicitly at any point:
ByUnicoSDK.close();
Диаграмма последовательности ниже демонстрирует, как использовать SDK и результат API для настройки iFrame:
Примеры приложений
| Язык / Фреймворк | Описание | Репозиторий |
|---|---|---|
| Angular | PoC на Angular, реализующий Journeys SDK | GitHub — unico-cbu-poc-angular |
| JS Vanilla | PoC на JS Vanilla, реализующий Journeys SDK | GitHub — unico-cbu-poc-js |
| React | PoC на React, реализующ ий Journeys SDK | GitHub — unico-cbu-poc-react |
| Vue JS | PoC на Vue JS, реализующий Journeys SDK | GitHub — unico-cbu-poc-vuejs |
Безопасность
Безопасность в этой модели построена послойно, начиная с протокола коммуникации между SDK и приложением, работающим внутри iFrame.
При загрузке путешествия обе стороны выполняют рукопожатие (handshake) для установления связи.
В этом процессе приложение Unico проверяет источник сообщения инъекции данных, полученного через
postMessage, по закрытому списку авторизованных доменов, сегментированному по среде (UAT и PROD).
Сообщения от неодобренных источников немедленно отбрасываются, предотвращая встраивание путешествия
в неавторизованные страницы и устраняя поверхность атаки для уязвимостей, таких как clickjacking.
Помимо проверки источника, поток продолжается только при наличии действи тельного токена транзакции: одноразового JWT, выпущенного и подписанного бэкендом Unico. Это гарантирует, что даже авторизованный источник не сможет работать с истёкшим, повторно использованным или поддельным токеном.
После рукопожатия токен внедряется в iFrame, и между двумя сторонами не передаётся конфиденциальная информация. Вся оставшаяся коммуникация служит только для управления интерфейсом — открытие, закрытие и переходы экранов — предотвращая перехват или утечку данных процесса во время путешествия.
Изоляция iFrame также защищает целостность скриптов Unico во время выполнения. Поскольку код работает в контексте, отделённом от страницы, он не может быть доступен или изменён внешними скриптами, гарантируя, что путешествие выполняется точно так, как было создано, без вмешательства.
CSP и Permissions-Policy
Если ваша страница отправляет заголовки Content-Security-Policy или Permissions-Policy, убедитесь, что следующие директивы присутствуют, чтобы iFrame, скрипты и доступ к камере SDK работали корректно.
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");
Если ваша страница не отправляет эти заголовки, браузер не применяет ограничений по умолчанию и никакая настройка не требуется.
Устранение неполадок, специфичных для SDK
В этом разделе рассматриваются наиболее распространённые проблемы, возникающие при интеграции, и рекомендуемые способы их исследования.
Неожиданное поведение или нарушенный поток
Проверьте, не манипулирует ли какой-либо скрипт приложения напрямую iFrame в DOM. SDK создаёт
и управляет iFrame в body страницы, и любое внешнее изменение — будь то области видимости,
позиционирования или атрибутов — может нарушить жизненный цикл путешествия и вызвать
непредсказуемое поведение.
Визуальный опыт отличается от ожидаемого
Проверьте, не переопределяет ли какая-либо глобальная таблица стилей приложения свойства внутри iFrame.
SDK создаёт iFrame и все его внутренние элементы с динамическими ID и классами с префиксом
unico, что значительно снижает риск конфликта через селекторы ID или классов. Тем не менее,
широкие правила CSS — такие как селекторы тегов — могут достигать элементов внутри iFrame и
изменять визуальный опыт, предоставляемый пользователю.
Файлы библиотеки SDK изменены напрямую
Проверьте, не был ли какой-либо файл библиотеки изменён за пределами менеджера пакетов. Библиотека должна управляться исключительно через npm или yarn, без прямых правок установленных файлов. Ручные изменения могут привести к аномальному поведению, которое трудно воспроизвести, и не позволят службе поддержки Unico оказать помощь.
Не держите DevTools открытыми во время тестов захвата
Приложение Unico использует Capture SDK (unico-webframe) для захвата лица, который обнаруживает открытые DevTools как потенциальный сигнал мошенничества и блокирует отправку. Закройте DevTools перед выполнением сквозных тестов захвата.
Модели, описанные в этой доку ментации — прямой доступ и Journeys SDK — являются единственными подходами интеграции, официально поддерживаемыми Unico. Интеграции, отклоняющиеся от этих стандартов, могут вызвать неожиданное поведение, сбои потоков безопасности и прерывания путешествий, и не будут покрыты поддержкой Unico.
Примеры неподдерживаемых подходов:
- Встраивание SDK в WebView в мобильных приложениях. В этих случаях правильный подход — использовать модель прямого доступа, открывая ссылку путешествия непосредственно в WebView без привлечения Journeys SDK.
- Загрузка iFrame напрямую через HTML-тег
<iframe>, минуя Journeys SDK. iFrame является внутренней деталью реализации SDK и не должен создаваться вручную. Правильный подход — использовать Journeys SDK, который управляет жизненным циклом iFrame безопасно и в рамках ожидаемых стандартов.
Если есть какие-либо сомнения относительно того, соответствует ли подход поддерживаемому стандарту, обратитесь к документации или свяжитесь со службой поддержки перед продолжением реализации.