Widget Workflow

Widget Workflow embeds the ready-to-use biometric verification interface directly into a web page. The backend creates a session for a preconfigured Workflow and passes the session_id to the browser. The browser loads the Biometric.Vision library, mounts the widget into a container, and handles its completion event.

A Workflow defines the technologies and their order. The widget handles the interface and runs these technologies, while the client system creates the session, hosts the widget, and processes the final state.

Integration boundaries¶

Four parties take part in the integration:

• the client system backend stores the API KEY, creates the session, and retrieves its final result;
• the browser receives only the session_id, loads the library, and provides a container for the widget;
• Biometric.Vision displays the interface and runs the Workflow technologies;
• the end user grants camera access and completes the verification.

sequenceDiagram
    title Embedding Widget Workflow into a web application

    participant API as Client system backend
    participant WEB as Browser
    participant WIDGET as Biometric.Vision
    participant USER as End user

    note over API,WEB: Workflow session created on the backend
    API-->>WEB: {session_id}
    WEB->>WIDGET: Load flow-widget.umd.js
    WEB->>WIDGET: FlowWidget.startSession({id, selector, ...})
    WIDGET->>USER: Verification interface
    USER->>WIDGET: Complete Workflow technologies
    WIDGET-->>WEB: finish {aborted, result?}
    WEB->>API: Completion notification
    API->>API: Verify final state

1. Prepare the container¶

The page must contain a container with a unique id. Give it explicit width and height values: the widget calculates its internal layout from the container's actual dimensions. Also set position: relative and allow scrolling.

A full-screen container is recommended on mobile devices. You can use fixed dimensions on desktop, but the container must still have an explicit width and height.

Serve the page in a secure HTTPS context so the browser can grant camera access. Request only the permissions required by the Workflow technologies.

2. Load and start the widget¶

Load the library from the Remote UI domain:

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

After the library loads, call FlowWidget.startSession. The method accepts these parameters:

Supported locale values: kz, en, ru, my, de, es, fa, fr, it, ja, kg, ko, pt. If localeList contains an unsupported language, selecting it displays the interface in English.

Enable shadow: true if the page's global styles distort the widget or the widget styles affect the page. Shadow DOM isolates the CSS while preserving camera and sensor access in the host-page context.

3. Complete example¶

This example accepts a ready-to-use session_id from the backend, registers the completion handler, and starts 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: 'en',
    shadow: true,
  })
</script>

4. Handle completion¶

After the client-side process finishes, the widget dispatches a finish event on the window object. Its data is available in event.detail:

The finish event belongs to the interface lifecycle. Do not make a trusted business decision from browser data alone: return control to the backend and retrieve the current session result. The event handler must work when result is absent.

If the Workflow has show_qr enabled and the camera is unavailable, or if always_mobile is enabled, the widget displays a QR code. The user continues verification on a mobile device while the widget tracks the session state. After completion on the mobile device, the widget dispatches the same finish event; no additional client-side logic is required.

Related sections¶

• Workflow
• Session creation and metadata
• Retrieving results
• Failure reasons
• Webhooks
• Persons