---
title: Liveness (biometric selfie)
canonical: https://developer.unico.io/dual-api/developers/sdks-and-tools/web/web-sdk/capture-flow/capture-types/liveness
locale: en
generated_by: markdown-export
---

Biometric selfie capture with embedded liveness verification. The SDK guides the user until a biometrically valid frame is obtained via SmartFrames and returns the image as Base64 + JWT.

:::secondary[Capability]
This capture type uses the **Liveness** capability. For a conceptual overview of how Liveness works, refer to the Liveness capability page.
:::

## How it works

The SDK manages the full capture session:

1. Opens the camera with the SmartFrame overlay.
2. Guides the user to position their face within the frame.
3. Validates liveness — the session only completes when the user is physically present.
4. Returns an object with `base64` (preview) and `encrypted` (JWT for the API) via the `success` callback.

## Camera mode (smart vs normal)

Web exposes two camera modes via `SelfieCameraTypes`:

- `SelfieCameraTypes.NORMAL` — standard camera mode (manual capture).
- `SelfieCameraTypes.SMART` — smart camera mode with automatic capture and silhouette guidance.

When using `SMART`, you must also load the computer vision models via `setModelsPath` during initialization.

## Starting a liveness capture

****Step 2** — Build the camera and prepare the selfie session**

Build the camera instance and call `prepareSelfieCamera` passing the `UnicoConfig` and the desired `SelfieCameraTypes`:

  :::warning[Token expiry]
  The interval between generating `encrypted` and submitting it to the API must not exceed **10 minutes**.
  :::

  ```javascript
  const unicoCamera = unicoCameraBuilder.build();

  const config = new UnicoConfig()
    .setHostname("<YOUR_HOSTNAME>")
    .setHostKey("<YOUR_HOST_KEY>");

  unicoCamera.prepareSelfieCamera(
    config,
    SelfieCameraTypes.SMART
  ).then(cameraOpener => {
    cameraOpener.open(callback);
  }).catch(error => {
    console.error(error);
  });
  ```

  :::tip
  To optimize camera startup, you can separate the calls to `prepareSelfieCamera()` and `open()` — keeping the prepare step warm while the user navigates to the capture screen.
  :::

****Step 3** — (optional) Use inside an iFrame**

The Web SDK supports embedded Interactive Liveness in an iFrame via `prepareSelfieCameraForIFrame()`:

  ```javascript
  unicoCamera.prepareSelfieCameraForIFrame(
    config,
    SelfieCameraTypes.SMART
  ).then(cameraOpener => {
    cameraOpener.open(callback);
  }).catch(error => {
    console.error(error);
  });
  ```

  Implement the `<iframe>` element with the required permissions:

  ```html
  <iframe allow="fullscreen;camera;geolocation" allowFullScreen src="your_app_url"></iframe>
  ```

  :::warning[Method must match context]
  `prepareSelfieCameraForIFrame()` only works inside an iFrame — calling it outside an iFrame will cause the session to fail. Likewise, using `prepareSelfieCamera()` inside an iFrame results in error `73406`.
  :::

  :::warning[Fullscreen on iPhone]
  To perform the capture, the page must be in full-screen mode so the SDK can resize automatically. Apple restricts the use of full-screen APIs specifically on iPhones (iPads are acceptable). For captures on iPhones, manually configure the positioning of the iFrame.
  :::

:::note[iFrame error codes]
Two error codes may fire in an iFrame context: `73406` fires when camera initialization is blocked because `prepareSelfieCamera()` was called inside an iFrame — use `prepareSelfieCameraForIFrame()` instead; `73724` fires when the active session is cancelled because the camera session started inside an iFrame. See [Error handling](/dual-api/developers/sdks-and-tools/web/web-sdk/error-handling) for the full catalog.
:::

For the full result handling, see [Receiving the result](/dual-api/developers/sdks-and-tools/web/web-sdk/capture-flow/receiving-the-result).