Skip to main content

Liveness (biometric selfie)

Markdown

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:

  1. The plugin opens the camera (Android or iOS) with the SmartFrame overlay.
  2. The native SDK 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 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:

MethodWhen it's called
onErrorUnico(error)An error occurred during SDK operation
onUserClosedCameraManually()The user manually closed the camera
onSystemClosedCameraTimeoutSession()The session timeout was reached (default 45 seconds)
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:

MethodDescription
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.

class _MyHomePageState extends State<MyHomePage>
implements UnicoSelfie {

@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);
🇧🇷 Smart Revalidation on ApiOnly (Native SDK + API)

To use Smart Revalidation on ApiOnly (Native SDK + API), open the camera passing UnicoIDSmartOptions with the reference process and the use case. It requires Flutter plugin 4.65.0 or later. For the accepted useCase values, see Smart Revalidation. For the fields, see the Capture API.

_opener.openCameraSelfie(
listener: this,
idSmartOptions: UnicoIDSmartOptions(
referenceProcessId: 'reference_process_id',
useCase: 'use_case',
),
);
  • Approved by silent authentication: the camera does not open, and onSuccessSelfie returns the encrypted JWT with no image. The base64 preview comes empty.
  • Escalated to facial biometry: the camera opens and the result is the same as a regular capture.
  • No reference process: the camera runs the regular capture, without Smart Revalidation.

For the full result handling, see Receiving the result.