--- title: Интеграция Web-приложения description: Как реализовать интеграцию контракта Web & SDK на стороне клиента — редиректы и настройка iFrame SDK. canonical: https://developer.unico.io/ru/developers/sdks-and-tools/web/ locale: ru generated_by: markdown-export --- - [/ru/](/ru/) - [SDK и инструменты](/ru/developers/sdks-and-tools/overview) - Интеграция веб-приложения **На этой странице# Интеграция Web-приложения На этой странице описано, как работают сценарии Unico и какие модели интеграции доступны для их встраивания в приложение. **Сценарий** — это последовательность шагов, которые пользователь проходит для завершения проверки личности. Например: сделать фотографию документа и выполнить захват лица (Проверка живости). Unico берёт на себя весь пользовательский опыт. Усилия по интеграции минимальны: сценарий создаётся через **CreateProcess**, пользователь направляется в него, и в конце вы получаете результат. Всё, что происходит между этими шагами (экраны, инструкции, проверки), уже готово и поддерживается Unico. ## Две модели интеграции​ У каждого клиента свои потребности. Unico предлагает **две модели** для направления пользователя к сценарию. МодельПодходит для**Journeys SDK**Веб-приложения, которым нужен интегрированный и бесшовный опыт с сохранением пользователя в той же среде**Прямой доступ**Веб-потоки, где сценарий может выполняться вне основной страницы, или приложения, уже встраивающие WebView. Нативным приложениям следует предпочесть SDK для платформы Нативные приложенияЕсли ваше приложение является нативным мобильным приложением, мы рекомендуем использовать SDK для платформы, на которой оно построено ([Android](/ru/developers/sdks-and-tools/android/requirements), [iOS](/ru/developers/sdks-and-tools/ios/requirements) или [Flutter](/ru/developers/sdks-and-tools/flutter/requirements)), вместо веб-интеграции. 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**: УстановкаПакет `unico-journey-sdk` используется совместно платёжными сценариями IDPay и сценариями проверки личности. Для сценариев идентификации импортируйте класс `ByUnicoSDK`, как показано в шагах ниже.``` npm install unico-journey-sdk ``` Ранее idpay-b2b-sdkЭтот пакет ранее публиковался как `idpay-b2b-sdk`. Это тот же SDK под новым именем, сохраняющий ту же линию версий. Под новым именем доступны только версии **2.3.0 и новее** — полную историю см. в разделе [История изменений](/ru/developers/sdks-and-tools/web/resources/release-notes).Рекомендуемый способ установки Journeys SDK — через менеджер зависимостей, такой как **npm** или **yarn**, из пакета, доступного в **npm registry**. Помимо упрощения установки и управления зависимостями, такой подход даёт чёткий контроль над используемой версией и облегчает обновление при выходе каждой новой версии.SDK следует **семантическому версионированию (SemVer)**, то есть обновления patch и minor не вносят несовместимых изменений. Можно безопасно настроить проект на автоматическое получение этих обновлений. Изменения, которые могут потребовать доработок интеграции, выносятся в major-версии и всегда сопровождаются руководством по миграции.Поддерживайте SDK в актуальном состоянииОставаться на последней версии особенно важно по двум причинам. Первая — **безопасность**: патчи безопасности выпускаются всякий раз, когда выявляются уязвимости или появляется возможность усилить протокол связи. Использование устаревшей версии означает отказ от этих исправлений и подверженность потока излишним рискам. Вторая — **стабильность**: исправления ошибок распространяются тем же способом, и старые версии могут демонстрировать поведение, уже исправленное в более новых выпусках.Перед началом зарегистрируйте свои домены в команде поддержки Unico. Все домены должны использовать HTTPS.**Шаг 2**: Вызовите `init(options)`Инициализирует SDK и предварительно загружает скрипты, необходимые для корректной работы сценария, обеспечивая более плавный опыт для конечного пользователя. Вызывайте его как можно раньше в потоке.ПараметрОбязательныйОписание`token`ДаТокен процесса, возвращаемый API Create Process`env`НетУстановите `'uat'` только для тестовых сред``` import { ByUnicoSDK } from 'unico-journey-sdk';ByUnicoSDK.init({ token, // env: 'uat' // только для тестовых сред}); ``` **Шаг 3**: Вызовите `open(options)`Отображает iFrame и запускает сценарий для пользователя. С этого момента всё происходит автоматически внутри iFrame, без необходимости управлять какими-либо промежуточными шагами.ПараметрОбязательныйОписание`transactionId`ДаID процесса, возвращаемый API Create Process`token`ДаТокен процесса, возвращаемый API Create Process`onFinish`ДаCallback, выполняемый при завершении или закрытии сценария`onWidgetVisibilityChange`НетCallback, выполняемый при изменении состояния видимости виджетаСледующее взаимодействие с приложением происходит, когда сценарий завершается, независимо от того, завершил ли его пользователь или закрыл. В этот момент SDK вызывает callback **`onFinish`**, переданный как параметр в `open`. После этого приложение может вызвать API **`getProcess`**, чтобы проверить результат, или дождаться уведомления через **Webhook**, если предпочтителен асинхронный подход.Помимо запроса результата, рекомендуется использовать `onFinish` для управления состоянием фронтенда приложения: **Избегайте циклов.** Предотвратите немедленное и излишнее повторное создание процессов, если пользователь снова запускает поток сразу после завершения сценария. **Управление потоком.** Убедитесь, что пользователь направляется к следующему шагу приложения, чтобы он не застрял на экране без выхода после закрытия сценария. предупреждениеCallback `onFinish` сигнализирует, что пользователь завершил сценарий, но не гарантирует одобрения. Процесс мог завершиться отказом по одному из правил проверки Unico. Запрос через `getProcess` или получение уведомления через Webhook не являются необязательными: это единственные источники фактического результата, и поведение приложения должно основываться на них. `onFinish` нельзя использовать изолированно для определения того, был ли пользователь одобрен.Callback `onFinish` получает объект, описывающий, как завершился сценарий:ПолеТипОписание`type`stringКак завершился сценарий: `'FINISH'` (завершён) или `'CLOSE'` (пользователь закрыл до завершения)`transaction`object | undefinedПрисутствует, когда `type` равен `'FINISH'`; `undefined`, когда `type` равен `'CLOSE'``transaction.id`stringИдентификатор процесса (тот же `transactionId`, что был передан)`transaction.​redirectUrl`stringURL для перенаправления пользователя после сценарияОбработка callback **`onWidgetVisibilityChange`** необязательна и может быть нерелевантна для вашего сценария использования. Он вызывается всякий раз, когда меняется состояние видимости виджета, и полезен только в одном конкретном случае: некоторые сценарии отображаются с прозрачным фоном, оставляя страницу приложения видимой за интерфейсом. Приложения, которые показывают собственное модальное окно во время потока проверки (например, в рамках оркестрации между несколькими провайдерами KYC), могут в итоге отображать это окно позади виджета Unico, ухудшая визуальный опыт. В этом случае callback позволяет приложению скрывать любые дополнительные визуальные элементы, пока сценарий Unico активен, и восстанавливать их по его завершении. Если в вашем приложении нет интерфейса, который мог бы перекрывать виджет, его можно безопасно не использовать.``` ByUnicoSDK.open({ transactionId: '9bc22bac-1e64-49a5-94d6-9e4f8ec9a1bf', token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...', onFinish: ({ transaction, type }) => { if (type === 'FINISH') { // Сценарий завершён (transaction = { id, redirectUrl }): продолжите свой поток здесь. } // type === 'CLOSE' → пользователь закрыл до завершения; }, // Необязательно: нужно только если ваше приложение показывает интерфейс, способный перекрыть виджет. onWidgetVisibilityChange: (visible) => { // скрывайте или восстанавливайте своё модальное окно в зависимости от видимости виджета },});// Чтобы явно закрыть SDK в любой момент:ByUnicoSDK.close(); ``` Приведённая ниже диаграмма последовательности показывает, как использовать SDK и результат API для настройки iFrame:### Референс-приложение​ Язык / ФреймворкОписаниеРепозиторийNode.js (Express)Референс-приложение на Node.js, реализующее полный пользовательский путь с помощью Journeys SDK[GitHub — reference-apps/web](https://github.com/unico-labs/reference-apps/tree/main/web)### Безопасность​ Безопасность в этой модели построена слоями, начиная с протокола связи между SDK и приложением, выполняющимся внутри iFrame.При загрузке сценария обе стороны выполняют **рукопожатие (handshake)** для установления связи. В ходе этого процесса приложение Unico проверяет источник сообщения внедрения данных, полученного через `postMessage`, по закрытому списку авторизованных доменов, сегментированному по средам (UAT и PROD). Сообщения из неутверждённых источников немедленно отбрасываются, что не позволяет встраивать сценарий на неавторизованных страницах и устраняет поверхность атаки для таких уязвимостей, как **clickjacking**.Помимо проверки источника, поток продолжается только при наличии действительного токена транзакции: одноразового JWT, выпущенного и подписанного бэкендом Unico. Это гарантирует, что даже авторизованный источник не сможет работать с просроченным, повторно использованным или поддельным токеном.После рукопожатия токен внедряется в iFrame, и между сторонами больше не передаётся никакой конфиденциальной информации. Вся остальная связь служит лишь для управления интерфейсом (открытие, закрытие и переходы между экранами), не позволяя перехватить или раскрыть данные процесса во время сценария.Изоляция iFrame также защищает целостность скриптов Unico во время выполнения. Поскольку код выполняется в контексте, отделённом от страницы, внешние скрипты не могут получить к нему доступ или изменить его, что гарантирует выполнение сценария ровно так, как он был построен, без вмешательства.По замыслу CSP не используется в этой модели интеграции. Авторизованные домены являются частью конфигурации безопасности каждого клиента, и их публичное раскрытие в заголовках могло бы облегчить злоумышленникам составление карты инфраструктуры. Поскольку идентификация клиента происходит только в момент `init`, невозможно динамически внедрить эти домены в заголовки до этого момента, что делает CSP неприменимым без отказа от этой конфиденциальности. Все гарантии безопасности обеспечиваются протоколом рукопожатия, описанным выше.### Устранение неполадок, специфичных для SDK​ В этом разделе рассматриваются наиболее частые проблемы, возникающие при интеграции, и рекомендуемые способы их исследования.#### Непредвиденное поведение или прерванный поток​ Проверьте, не манипулирует ли какой-либо скрипт приложения iFrame напрямую в DOM. SDK создаёт iFrame и управляет им в `body` страницы, и любое внешнее изменение (области видимости, позиционирования или атрибутов) может нарушить жизненный цикл сценария и вызвать непредсказуемое поведение.#### Визуальный опыт отличается от ожидаемого​ Проверьте, не переопределяет ли какая-либо глобальная таблица стилей приложения свойства внутри iFrame. SDK создаёт iFrame и все его внутренние элементы с динамическими ID и классами с префиксом `unico`, что значительно снижает риск конфликта по селекторам ID или классов. Тем не менее правила CSS широкой области действия (например, селекторы тегов) могут затрагивать элементы внутри iFrame и изменять визуальный опыт, предоставляемый пользователю.#### Файлы библиотеки SDK изменены напрямую​ Проверьте, не был ли какой-либо файл библиотеки изменён вне менеджера зависимостей. Библиотекой следует управлять исключительно через **npm** или **yarn**, без прямого редактирования установленных файлов. Ручные изменения могут приводить к аномальному, труднодиагностируемому поведению и делают невозможной помощь со стороны поддержки Unico.Пользователь **перенаправляется на размещённую 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). В мобильных приложениях принято использовать **WebView**, чтобы открыть сценарий напрямую, без дополнительного редиректа. В этом случае `callbackUri` также принимает **deeplink**, что позволяет по завершении сценария открыть определённый экран в нативном приложении. Достаточно настроить deeplink как адрес возврата, и операционная система сама направит пользователя в нужное место. Этот подход с WebView подходит приложениям, которые уже его встраивают; полностью нативному приложению следует предпочесть SDK для платформы. #### Не держите DevTools открытыми во время тестов захвата​ Unico использует несколько механизмов для защиты своих сценариев, один из которых распознаёт открытые DevTools как возможный признак мошенничества и блокирует отправку. Закройте DevTools перед запуском сквозных (end-to-end) тестов захвата. Неподдерживаемые интеграцииМодели, описанные в этой документации (прямой доступ и Journeys SDK), являются единственными способами интеграции, официально поддерживаемыми Unico. Интеграции, отклоняющиеся от этих стандартов, могут вызывать непредвиденное поведение, сбои в потоке безопасности и прерывания сценария и не будут покрываться поддержкой Unico.Несколько примеров неподдерживаемых подходов: **Встраивание SDK внутрь WebView** в мобильных приложениях. В таких случаях правильный подход — использовать модель **прямого доступа**, открывая ссылку сценария напрямую в WebView, без задействования Journeys SDK. **Загрузка iFrame напрямую через HTML-тег `