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 plugin delegates to the underlying native SDKs:

The plugin opens the camera (Android or iOS) with the SmartFrame overlay.
The native SDK guides the user to position their face within the frame.
Validates liveness — the session only completes when the user is physically present.
Returns a ResultCamera object with base64 and encrypted (JWT) via the platform channel.

Camera mode (smart capture)

The SDK has intelligent framing and automatic capture enabled by default. Configure the camera mode in your builder as follows:

UnicoCheckCameraOpener _opener = _unicoCheck
    .setAutoCapture(autoCapture: true)
    .setSmartFrame(smartFrame: true)
    .build();

Starting a liveness capture

Step 1 — Implement UnicoListener

UnicoListener handles the SDK lifecycle callbacks. Implement the four mandatory methods:

Method	When it's called
`onErrorUnico(error)`	An error occurred during SDK operation
`onUserClosedCameraManually()`	The user manually closed the camera
`onSystemClosedCameraTimeoutSession()`	The 40-second session limit was reached
`onSystemChangedTypeCameraTimeoutFaceInference()`	No face detected for 13 seconds — switches to manual capture

class _MyHomePageState extends State<MyHomePage> implements UnicoListener {
  late UnicoCheckBuilder _unicoCheck;

  @override
  void onErrorUnico(UnicoError error) {}

  @override
  void onUserClosedCameraManually() {}

  @override
  void onSystemClosedCameraTimeoutSession() {}

  @override
  void onSystemChangedTypeCameraTimeoutFaceInference() {}
}

Mandatory listener methods

All four listener methods above must be created in your project (even without any logic). Otherwise, the project will not compile successfully.

Step 2 — Implement the selfie listeners on UnicoSelfie

Add the selfie callbacks to your state class:

Method	Description
`onSuccessSelfie(ResultCamera result)`	Capture succeeded — returns `ResultCamera` with `base64` (preview) and `encrypted` (JWT for the API)
`onErrorSelfie(UnicoError error)`	Capture failed — returns a `UnicoError` with code and description

Token expiry

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

@override
void onSuccessSelfie(ResultCamera result) { }

@override
void onErrorSelfie(UnicoError error) { }

Step 3 — Call openCameraSelfie

The openCameraSelfie method opens the camera. It takes the implementation of the UnicoSelfie listener:

_opener.openCameraSelfie(listener: this);

Monitoring data collection

The openCameraSelfie method provides an overload that accepts metadata via UnicoCheckPrepareInfo to assist in identifying the user session and the flow:

externalUserId (String, required) — User identifier within your system. Automatically hashed using SHA-256 before transmission.
useCase (String, optional) — Identifier for the context or flow currently running. Transmitted in plain text.

_opener.openCameraSelfie(
  listener: this,
  prepareInfo: UnicoCheckPrepareInfo(
    externalUserId: 'external_user_id',
    useCase: 'use_case', // optional
  ),
);

For the full result handling, see Receiving the result.