--- title: Интеграция Web-приложения description: Как реализовать интеграцию контракта Web & SDK на стороне клиента — редиректы и настройка iFrame SDK. canonical: https://developer.unico.io/ru/human-token/integrations/web/web-integration/ locale: ru generated_by: markdown-export --- На этой странице описывается, как работают путешествия (journeys) Unico и какие модели интеграции доступны для их встраивания в приложение. **Путешествие (journey)** — это набор шагов, которые пользователь проходит для завершения верификации личности. Например: фотографирование документа и выполнение захвата лица (liveness). Unico управляет всем опытом. Усилия по интеграции минимальны: путешествие создается через **CreateProcess**, пользователь направляется к нему, и результат получается в конце. Всё промежуточное — экраны, инструкции, валидации — уже создано и поддерживается Unico. ## Две модели интеграции У каждого клиента разные потребности. Unico предлагает **две модели** для направления пользователя к путешествию. | Модель | Лучше всего подходит для | | ----------------- | ------------------------------------------------------------------------------------------------------------- | | **Прямой доступ** | Мобильные приложения, уже использующие WebView, или веб-потоки, где путешествие может происходить за пределами основной страницы | | **Journeys SDK** | Веб-приложения, которым нужен интегрированный бесшовный опыт, удерживающий пользователя в той же среде | ### Прямой доступ Пользователь **перенаправляется на ссылку, размещённую Unico**, где проходит путешествие. По завершении он возвращается на URL, определённый при создании процесса (параметр `callbackUri`). Это самый простой подход: он не требует установки библиотеки и хорошо работает, когда путешествие не нужно проводить внутри собственной страницы приложения. С другой стороны, перевод пользователя за пределы среды клиента, как правило, создаёт больше трения и, соответственно, более высокий процент отказов. После создания процесса ответ API включает URL путешествия, размещённого Unico. Есть два распространённых способа направить пользователя: - **Стандартный редирект.** Пользователь перенаправляется непосредственно на URL путешествия. По завершении Unico перенаправляет его обратно на `callbackUri`, определённый при создании процесса. - **Новая вкладка с `window.open()`.** Путешествие открывается в новой вкладке браузера, удерживая пользователя в отдельном контексте. В этом случае рекомендуется отслеживать изменение URL на `callbackUri` и закрывать вкладку после завершения процесса. Подробности об API см. в [документации MDN](https://developer.mozilla.org/en-US/docs/Web/API/Window/open). ```mermaid sequenceDiagram participant Unico as Unico backend service participant Backend as Customer backend server participant Frontend as Customer frontend application participant Hosted as Unico hosted frontend application Frontend->>Backend: start kyc flow Backend->>Unico: call createProcess Unico->>Backend: return Unico process info Backend->>Frontend: return Unico process info Frontend->>Hosted: redirect user to process url Note over Hosted: User journey Hosted->>Frontend: redirect user to callback url critical Get process result Frontend->>Backend: signals that journey was finished Backend->>Unico: call getProcess opt Webhook Note over Backend: In addition to getProcess, you can use the Webhook implementation to ensure a fallback in obtaining the process result. end end ``` В мобильных приложениях обычно используется **WebView** для прямого открытия путешествия без дополнительного перенаправления. В этом случае `callbackUri` также принимает **deeplink**, позволяя завершению путешествия запустить открытие конкретного экрана в нативном приложении. Просто настройте deeplink как место назначения для возврата, и операционная система обеспечит маршрутизацию пользователя в нужное место. ```mermaid sequenceDiagram participant Unico as Unico backend service participant Backend as Customer backend server participant App as Customer mobile application participant Hosted as Unico hosted frontend application App->>Backend: start kyc flow Backend->>Unico: call createProcess Unico->>Backend: return Unico process info Backend->>App: return Unico process info App->>Hosted: open the process url in a webview Note over Hosted: User journey Hosted->>App: redirect user to the deeplink (callback url) critical Get process result App->>Backend: signals that journey was finished Backend->>Unico: call getProcess opt Webhook Note over Backend: In addition to getProcess, you can use the Webhook implementation to ensure a fallback in obtaining the process result. end end ``` ### Journeys SDK Путешествие происходит **внутри самого приложения**, не выводя пользователя из его контекста. **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`, как показано в шагах ниже. ```bash npm install idpay-b2b-sdk ``` Рекомендуемый способ установки Journeys SDK — через менеджер пакетов, такой как **npm** или **yarn**, из пакета, доступного в **npm registry**. Помимо упрощения установки и управления зависимостями, этот подход обеспечивает чёткий контроль над используемой версией и упрощает обновление при публикации новой версии. SDK следует **семантическому версионированию (SemVer)**, что означает, что патч- и минорные обновления не вносят критических изменений. Безопасно настроить проект на автоматическое получение этих обновлений. Изменения, которые могут потребовать обновления интеграции, зарезервированы для мажорных версий и всегда сопровождаются руководством по миграции. :::tip[Поддержание SDK в актуальном состоянии] Оставаться на последней версии особенно важно по двум причинам. Первая — **безопасность**: патчи безопасности публикуются при обнаружении уязвимостей или возможностей для усиления протокола связи. Использование устаревшей версии означает пропуск этих исправлений и подвержение потока ненужному риску. Вторая — **стабильность**: исправления ошибок распространяются тем же способом, и более старые версии могут демонстрировать поведение, уже исправленное в более новых релизах. ::: Перед началом зарегистрируйте свои домены в службе поддержки 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"); ``` :::info Если ваша страница не отправляет заголовки CSP или Permissions-Policy, вы можете пропустить этот шаг — браузер не применяет ограничений по умолчанию. ::: ****Шаг 3** — Вызов `init(options)`** Инициализирует SDK и предварительно загружает скрипты, необходимые для корректной работы путешествия, создавая более плавный опыт для конечного пользователя. Вызывайте это как можно раньше в потоке. | Параметр | Обязателен | Описание | | --------- | -------- | ------------------------------------------------ | | `token` | Да | Токен процесса, возвращённый API Create Process | | `env` | Нет | Установите `'uat'` только для тестовых сред | ```javascript 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` для управления состоянием фронтенда приложения: - **Избегайте циклов.** Предотвращайте немедленное и ненужное повторное создание процессов, если пользователь снова запускает поток сразу после завершения путешествия. - **Управление потоком.** Убедитесь, что пользователь направлен на следующий шаг приложения, избегая тупикового экрана после закрытия путешествия. :::warning Коллбэк `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, который мог бы перекрывать виджет, вы можете безопасно его опустить. ```javascript 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: ```mermaid sequenceDiagram participant Unico as Unico backend service participant Backend as Customer backend server participant Frontend as Customer frontend application participant SDK as ByUnicoSDK Frontend->>Backend: start kyc flow Backend->>Unico: call createProcess Unico->>Backend: return Unico process info Backend->>Frontend: return Unico process info Note over Frontend: Initialize the Unico journey as soon as it is determined that the KYC flow is required critical Unico journey initialization Frontend->>SDK: byUnicoSDK.init SDK-->>Frontend: validates customer domain and initialize end critical Unico journey exhibition Frontend->>SDK: byUnicoSDK.open SDK-->>Frontend: show byUnico experience end Note over SDK: User journey critical Unico journey completion SDK-->>Frontend: call onFinish end critical Get process result Frontend->>Backend: signals that journey was finished Backend->>Unico: call getProcess opt Webhook Note over Backend: In addition to getProcess, you can use the Webhook implementation to ensure a fallback in obtaining the process result. end end ``` #### Примеры приложений | Язык / Фреймворк | Описание | Репозиторий | | --------------------- | ------------ | ---------- | | Angular | PoC на Angular, реализующий Journeys SDK | [GitHub — unico-cbu-poc-angular](https://github.com/unico-labs/unico-cbu-poc-angular) | | JS Vanilla | PoC на JS Vanilla, реализующий Journeys SDK | [GitHub — unico-cbu-poc-js](https://github.com/unico-labs/unico-cbu-poc-js) | | React | PoC на React, реализующий Journeys SDK | [GitHub — unico-cbu-poc-react](https://github.com/unico-labs/unico-cbu-poc-react) | | Vue JS | PoC на Vue JS, реализующий Journeys SDK | [GitHub — unico-cbu-poc-vuejs](https://github.com/unico-labs/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 перед выполнением сквозных тестов захвата. :::warning[Неподдерживаемые интеграции] Модели, описанные в этой документации — прямой доступ и Journeys SDK — являются единственными подходами интеграции, официально поддерживаемыми Unico. Интеграции, отклоняющиеся от этих стандартов, могут вызвать неожиданное поведение, сбои потоков безопасности и прерывания путешествий, и не будут покрыты поддержкой Unico. Примеры неподдерживаемых подходов: - **Встраивание SDK в WebView** в мобильных приложениях. В этих случаях правильный подход — использовать модель **прямого доступа**, открывая ссылку путешествия непосредственно в WebView без привлечения Journeys SDK. - **Загрузка iFrame напрямую через HTML-тег `