Интеграция Web-приложения

Эта страница описывает два подхода к клиентской интеграции для контракта Web & SDK: перенаправление пользователя на путь, размещённый на стороне Unico, и встраивание этого пути через iFrame SDK.

Перенаправление пользователя

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

1. Стандартное перенаправление

Перенаправьте пользователя напрямую на URL пути. Когда пользователь завершает процесс, Unico перенаправляет его обратно на URL, указанный при создании процесса.

2. Новая вкладка с window.open()

Откройте путь в новой вкладке браузера, чтобы пользователь оставался в отдельном контексте. Отслеживайте изменение URL на ваш возвратный URL и закрывайте вкладку после завершения процесса.

Подробнее об API window.open() см. в документации MDN.

iFrame

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

Интеграции, которые не соответствуют стандартам, описанным в данной документации, могут вызывать непредвиденные сбои и не будут поддерживаться службой поддержки Unico.

Примеры неподдерживаемых подходов: встраивание SDK внутри WebView или загрузка iFrame напрямую через HTML-тег.

Как начать

Шаг 1 — Установка

SDK by Unico использует тот же пакет, что и IDPay:

npm install idpay-b2b-sdk

совет

Устанавливайте без указания конкретной версии, чтобы менеджер пакетов автоматически получал последние минорные и патч-релизы.

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

Шаг 2 — Вызов init(options)

Инициализирует SDK и предварительно загружает ресурсы, обеспечивая более плавный опыт для конечного пользователя. Вызывайте этот метод как можно раньше в своём потоке.

Параметр	Обязательный	Описание
type	Да	Установите значение 'IFRAME' для потоков by Unico
token	Да	Токен процесса, возвращённый API создания процесса
env	Нет	Установите значение 'uat' только для тестовых сред

import { ByUnicoSDK } from "idpay-b2b-sdk";

ByUnicoSDK.init({
  type: 'IFRAME',
  token,
  // env: 'uat' // only for test environments
});

Шаг 3 — Вызов open(options)

Отображает предварительно загруженный iFrame и запускает обмен сообщениями между вашей страницей и путём Unico.

Параметр	Обязательный	Описание
transactionId	Да	ID процесса, возвращённый API создания процесса
token	Да	Токен процесса, возвращённый API создания процесса
onFinish	Да	Колбэк, выполняемый при завершении или закрытии пути

Колбэк onFinish получает объект процесса с ID транзакции, URL перенаправления и типом завершения.

ByUnicoSDK.open({
  transactionId: '9bc22bac-1e64-49a5-94d6-9e4f8ec9a1bf',
  token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',
  onFinish: (process) => {
    console.log('Process finished', process);
    // process.transaction.redirectUrl — use this to navigate the user
  },
});

// To close the SDK explicitly at any point:
ByUnicoSDK.close();

Приведённая ниже диаграмма последовательности демонстрирует, как использовать SDK и результат API для настройки iFrame:

Безопасность

Предпочтительнее использовать решение iFrame с токеном аутентификации вместо CSP

После тщательного анализа выбранный подход использует iFrame с токенами аутентификации, а не реализацию политики безопасности контента (CSP). Это решение было обусловлено требованиями безопасности и гибкостью, необходимой для удовлетворения потребностей клиентов.

Контекст и проблемы с CSP

Политика безопасности контента — мощный инструмент для защиты веб-приложений от XSS-атак и внедрения кода. Однако настройка политики CSP требует определения строгого списка доверенных доменов. Этот подход эффективен, когда домены фиксированы и предсказуемы, — но для клиентов, использующих динамические и переменные домены, такая жёсткая конфигурация создаёт значительные трудности.

Уязвимость при динамических доменах

Динамические домены представляют существенный риск безопасности при использовании CSP. Когда у клиента есть домены, которые часто меняются или создаются динамически, политика CSP должна постоянно обновляться для включения новых доменов. Это не только увеличивает накладные расходы на обслуживание, но и превращает каждый домен, указанный в политике, в потенциальную поверхность атаки при недостаточном управлении.

Решение с iFrame и токеном аутентификации

Для снижения этих рисков и обеспечения гибкости, требуемой клиентами, выбранное решение сочетает iFrame с токенами аутентификации, обеспечивая дополнительный уровень безопасности без необходимости в статическом списке доменов.

Как это работает:

• Безопасная аутентификация — каждый iFrame загружается с уникальным токеном аутентификации для каждой транзакции, гарантируя, что доступ к контенту могут получить только авторизованные пользователи. Токен проверяется в реальном времени.
• Изоляция контента — iFrame работает в отдельном контексте браузера, снижая риск взаимодействия между различными источниками и уменьшая вероятность потенциальных атак.
• Гибкость для динамических доменов — не полагаясь на статическую политику CSP, решение адаптируется к динамическим доменам клиентов без необходимости постоянного обновления политики.