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 (JSON Web Token — a signed payload sent to your backend to call the REST API).

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 a ResultCamera object with base64 and encrypted (JWT).
Starting a liveness capture
Step 1 — Implement AcessoBioListener

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

MethodWhen it's called
onErrorAcessoBio(errorBio)An error occurred during SDK operation
onUserClosedCameraManually()The user manually closed the camera
onSystemClosedCameraTimeoutSession()The session time limit was reached — see Session limits
onSystemChangedTypeCameraTimeoutFaceInference()The face inference time limit was reached — switches to manual capture — see Session limits
val callback = object : AcessoBioListener {
override fun onErrorAcessoBio(errorBio: ErrorBio?) { }
override fun onUserClosedCameraManually() { }
override fun onSystemClosedCameraTimeoutSession() { }
override fun onSystemChangedTypeCameraTimeoutFaceInference() { }
}
Step 2 — Implement iAcessoBioSelfie

iAcessoBioSelfie handles the selfie capture result callbacks:

MethodDescription
onSuccessSelfie(result)Capture succeeded — returns ResultCamera with base64 (preview) and encrypted (JWT for the API)
onErrorSelfie(errorBio)Capture failed — returns an ErrorBio with code and description
Token expiry

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

val selfieListener = object : iAcessoBioSelfie {
override fun onSuccessSelfie(result: ResultCamera?) { }
override fun onErrorSelfie(errorBio: ErrorBio?) { }
}
Step 3 — Call prepareCamera

With unicoCheckCamera initialized and both listeners implemented, call prepareCamera passing the SDK config (the UnicoConfig created in Initialization) and a CameraListener:

  • onCameraReady — camera is ready; call open passing the selfieListener from Step 2.
  • onCameraFailed — camera preparation failed; handle the error message.
unicoCheckCamera
.prepareCamera(UnicoConfig(), object : CameraListener {
override fun onCameraReady(cameraOpener: UnicoCheckCameraOpener.Camera?) {
cameraOpener?.open(selfieListener)
}
override fun onCameraFailed(message: String?) { }
})

For the full result handling, see Receiving the result.

🇧🇷 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 Android SDK 6.13.0 or later. For the accepted useCase values, see Smart Revalidation. For the fields, see the Capture API.

Silent Revalidation

This section opens the camera with a reference process. For Silent Revalidation, which starts with startSilentValidation and the externalUserId, see Silent Revalidation.

override fun onCameraReady(cameraOpener: UnicoCheckCameraOpener.Camera?) {
cameraOpener?.open(
selfieListener,
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.