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 — calling it outside an iFrame will cause the session to fail. Likewise, using prepareSelfieCamera() inside an iFrame results in error 73406.

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.

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 for the full catalog.

For the full result handling, see Receiving the result.