Face Liveness

Install and launch Face Liveness for Flutter. Learn prerequisites, CerttaLivenessConfiguration options, event streams, success and failure results, and error handling.

This guide covers caf_sdk 2.4.0 and above (Certta DevX). For the previous CafSdk sequential flow, see the legacy documentation.

Prerequisites

Before proceeding, ensure the Certta SDK is properly installed. If you haven't done this yet, please refer to our Installation Guide.

Installation Guide

Enable faceLiveness (and faceLivenessUI if you want the built-in UI) in caf-modules-config.json. You must include at least one liveness provider.

Starting Liveness

To start the Liveness flow, call certta.liveness.open() and pass a CerttaLivenessConfiguration object. Subscribe to eventStream before calling open() so you do not miss results.

Set useFaceLivenessUi to true to use the built-in Certta UI. When false, the SDK runs the headless Face Liveness module.

import 'dart:async';
import 'package:flutter/services.dart';
import 'package:caf_sdk/certta_sdk.dart';

final certta = CerttaSdk();

late final StreamSubscription<CerttaLivenessEvent> _livenessSub;

void listenToLiveness() {
  _livenessSub = certta.liveness.eventStream.listen((event) {
    if (event.success != null) {
      // Handle success — event.success!.response is a JWT
    } else if (event.failed != null) {
      // Handle business failure — see Handling Failures
    } else if (event.error != null) {
      // Handle technical error
    }
  });
}

Future<void> startLiveness() async {
  try {
    await certta.liveness.open(
      const CerttaLivenessConfiguration(
        maxRetryAttempts: 3,
        faceAuthEnabled: false,
        showLoading: true,
        useFaceLivenessUi: true,
      ),
    );
  } on PlatformException catch (e) {
    // Handle BRIDGE_EXCEPTION
  }
}

open() throws a PlatformException with code BRIDGE_EXCEPTION when the native mapper rejects the configuration.

CerttaLivenessConfiguration parameters

Parameter	Default	Description
maxRetryAttempts	3	Maximum retries after a failed capture attempt.
faceAuthEnabled	false	When enabled, the SDK performs face authentication.
showLoading	true	Shows loading indicators during processing when true.
useFaceLivenessUi	false	If enabled, the SDK uses the built-in Certta Face Liveness UI.
payFaceDebugMode	false	Enables debug mode for the PayFace (Fortface) provider. iOS only.

Understanding Liveness events and results

Ensure the JWT response is evaluated on the backend. This process must include validating the token's signature and verifying the isAlive and isMatch fields. Do not perform these validations on the client side.

CerttaLivenessEvent has exactly one populated field:

success (CerttaSuccess)

The capture and liveness pipeline succeeded. response is a JWT with the result data from the Liveness execution (for example captured images or validation results).

failed (CerttaLivenessFailure)

Liveness ran, but the outcome is a business failure.

Field	Description
type	Failure model: ImageCaptureFailure or FaceRecognitionFailure.
cause	Identifier for diagnostics or UX messaging (for example TOO_DARK).
description	Optional human-readable description from the native SDK.
response	Signed payload. Present for FaceRecognitionFailure when capture succeeded but recognition failed.

1. ImageCaptureFailure: problems during capture (environment, timeout, no face, provider-specific failure). There is typically no signed response.
2. FaceRecognitionFailure: capture succeeded, but face recognition / backend did not accept the result.

To understand and handle the cause of the failure, see Handling Failures.

error (CerttaError)

Triggered when a technical blocker prevents the SDK from starting or finishing the process, such as denied camera permissions, no internet connection, or hardware initialization failures.

Field	Description
type	Error identifier mapped from the native SDK.
cause	Additional context for the failure, when present.

Event	Typical cause
initializationError	configure not called, empty token or user ID, or invalid maxRetryAttempts.
permissionError	Camera (or related) permission denied.
networkError	Connectivity or server-side issues surfaced as network class errors.
securityError	Security checks failed.
unknownError	Other failures not mapped to a specific case.
cancelled	Occurs when the user abandons the flow before completion, such as by pressing the back button or sending the app to the background.