Widget Workflow

Widget Workflow встраивает готовый интерфейс биометрической проверки непосредственно в веб-страницу. Backend создаёт сессию заранее настроенного Workflow и передаёт браузеру session_id. Браузер загружает библиотеку Biometric.Vision, монтирует виджет в контейнер и обрабатывает событие завершения.

Workflow определяет состав и порядок технологий. Виджет отвечает за интерфейс и прохождение этих технологий, а клиентская система — за создание сессии, размещение виджета и обработку итогового состояния.

Границы интеграции¶

В интеграции участвуют четыре стороны:

• backend клиентской системы хранит API KEY, создаёт сессию и проверяет её итоговое состояние;
• браузер получает только session_id, загружает библиотеку и предоставляет контейнер для виджета;
• Biometric.Vision отображает интерфейс и выполняет технологии Workflow;
• конечный пользователь предоставляет доступ к камере и проходит проверку.

sequenceDiagram
    title Встраивание Widget Workflow в веб-приложение

    participant API as Backend клиентской системы
    participant WEB as Браузер
    participant WIDGET as Biometric.Vision
    participant USER as Конечный пользователь

    note over API,WEB: Сессия Workflow создана на backend
    API-->>WEB: {session_id}
    WEB->>WIDGET: Загрузка flow-widget.umd.js
    WEB->>WIDGET: FlowWidget.startSession({id, selector, ...})
    WIDGET->>USER: Интерфейс проверки
    USER->>WIDGET: Прохождение технологий Workflow
    WIDGET-->>WEB: finish {aborted, result?}
    WEB->>API: Уведомление о завершении
    API->>API: Проверка итогового состояния

1. Подготовка контейнера¶

Страница должна содержать контейнер с уникальным id. Задайте ему явные width и height: виджет рассчитывает внутреннюю разметку по фактическим размерам контейнера. Также установите position: relative и разрешите прокрутку.

Для мобильных устройств рекомендуется полноэкранный контейнер. На desktop можно использовать фиксированные размеры, но контейнер всё равно должен иметь явную ширину и высоту.

Страница должна работать в защищённом контексте HTTPS, чтобы браузер мог предоставить доступ к камере. Запрашивайте только разрешения, необходимые технологиям Workflow.

2. Загрузка и запуск виджета¶

Подключите библиотеку с домена Remote UI:

<script
  type="module"
  src="https://remote.biometric.vision/widget/flow-widget.umd.js"
></script>

После загрузки вызовите FlowWidget.startSession. Метод принимает следующие параметры:

Поддерживаемые значения locale: kz, en, ru, my, de, es, fa, fr, it, ja, kg, ko, pt. Если localeList содержит неподдерживаемый язык, при его выборе интерфейс отображается на английском.

Включите shadow: true, если глобальные стили страницы искажают виджет или стили виджета влияют на страницу. Shadow DOM изолирует CSS, сохраняя доступ к камере и другим датчикам в контексте хост-страницы.

3. Полный пример¶

Пример принимает готовый session_id от backend, регистрирует обработчик завершения и запускает Widget Workflow:

<style>
  html,
  body,
  .workflow-widget-shell {
    width: 100%;
    height: 100%;
    margin: 0;
  }

  #workflow-widget {
    width: 100%;
    height: 100%;
    position: relative;
    overflow: scroll;
  }
</style>

<div class="workflow-widget-shell">
  <div id="workflow-widget"></div>
</div>

<script
  type="module"
  src="https://remote.biometric.vision/widget/flow-widget.umd.js"
></script>

<script type="module">
  const sessionId = '<session_id>'

  window.addEventListener('finish', (event) => {
    const { aborted, result } = event.detail

    // Update the UI and ask your backend for the authoritative state.
    console.log({ aborted, result })
  }, { once: true })

  FlowWidget.startSession({
    id: sessionId,
    selector: '#workflow-widget',
    locale: 'ru',
    shadow: true,
  })
</script>

4. Обработка завершения¶

После завершения клиентской части виджет отправляет событие finish на объекте window. Данные доступны в event.detail:

Событие finish относится к жизненному циклу интерфейса. Не принимайте доверенное бизнес-решение только по данным из браузера: передайте управление backend и получите актуальный результат сессии. Обработчик события должен корректно работать при отсутствии result.

Если в Workflow включён show_qr и камера недоступна либо включён always_mobile, виджет показывает QR-код. Пользователь продолжает проверку на мобильном устройстве, а виджет отслеживает состояние сессии. После завершения на мобильном устройстве виджет отправляет то же событие finish; дополнительная клиентская логика не требуется.

Связанные разделы¶

• Workflow
• Создание сессии и метаданные
• Получение результата
• Причины отказа
• Webhooks
• Персоны