Liveness (biometric selfie)

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.

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 1 — Implement the callback object

The Web SDK uses a callback object — passed to open() — to handle success and error events. Both handlers are mandatory:

Handler	When it's called
on.success(obj)	Capture completed successfully — receives an object with base64 and encrypted
on.error(error)	An error occurred during the session — receives an ErrorBio

const callback = {
  on: {
    success: (obj) => {
      console.log(obj.base64);
      console.log(obj.encrypted);
    },
    error: (error) => {
      console.error(error);
    }
  }
};

Mandatory callback

The callback object is mandatory. If not properly implemented (covering both success and error events), the SDK raises an exception that, if not handled, is displayed in the user's console.

Step 2 — Build the camera and prepare the selfie session

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

Token expiry

The interval between generating encrypted and submitting it to the API must not exceed 10 minutes.

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():

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

Implement the <iframe> element with the required permissions:

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

Method must match context

prepareSelfieCameraForIFrame() only works inside an iFrame — using it outside results in error 73724. Likewise, using prepareSelfieCamera() inside an iFrame also results in error 73724.

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.

For the full result handling, see Receiving the result.