Face Liveness

Install and configure Face Liveness for iOS with CafSDK's. Learn requirements, session setup, face liveness flow, UI configuration, delegates, theming, and support.

This guide covers version 7.0.0 and above. For versions below 7.0.0, please see the legacy documentation.

Overview

This guide covers the SDK installation, session initialization, and how to trigger the Face Liveness flow.

Prerequisites

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

Starting the Face Liveness

To initiate the liveness flow, use the singleton instance and provide the required configuration parameters. Use the completion handler to manage the session events and results.

CerttaLiveness.shared.open(
    from: self, // This is the view controller and the delegate
    configuration: LivenessConfiguration(
        maxRetryAttempts: 3,
        faceAuthEnabled: false,
        showLoading: true,
        useFaceLivenessUi: true 
    )
) 

---

LivenessConfiguration Parameters

All parameters have defaults; override only what you need.

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

Understanding Liveness Events & Results

The CerttaLiveness.instance.open() assignes your controller to a delegate that you need to declare those methods:

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.

extension CerttaViewController: CerttaLivenessDelegate, CerttaDelegate {
    func didFinish(signedResponse: String) {
        let out = formView.outputView
        out.text += "✅ Capture completed successfully\n"    
    }

    func didFail(_ failure: LivenessFailure) {
    let out = formView.outputView
    switch failure {
    case .faceRecognitionFailure(let result, let cause):
        out.text += "❌ Liveness failed (face): cause=\(cause), result=\(result)\n\n"
    case .imageCaptureFailure(let message):
        out.text += "❌ Liveness failed (capture): \(message)\n\n"
        }
    }
  
    func didFinishWith(_ error: CerttaError) {
        let out = formView.outputView
        switch error {
        case .initializationError(let message): out.text += "❌ Error: \(message)\n\n"
        case .permissionError(let message): out.text += "❌ Error: permission - \(message)\n\n"
        case .securityError(let message): out.text += "❌ Error: security - \(message)\n\n"
        case .unknownError(let message): out.text += "❌ Error: \(message)\n\n"
        case .networkError(let message): out.text += "❌ Error: network - \(message)\n\n"
        }
    }
    func didLog(level: String, message: String) {
        print("level: \(level), message: \(message)")
    }
}

didFinish(signedResponse: String)

The string is the signed result from the module. Your backend or CAF integration documentation defines how to validate, decode, and store it. Do not log the full token in production builds.

didFail(_ failure: LivenessFailure)

There are two types of LivenessFailure:

Case	When
.imageCaptureFailure(String)	Problems during capture (environment, timeout, no face, provider-specific messages, etc.). The string is intended for diagnostics or UX messaging.
.faceRecognitionFailure(response: String, cause: String)	Capture succeeded but face recognition / backend did not accept the result. cause explains the rejection and result is the signed payload

didFinishWith(_ 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.

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.

CerttaError conforms to LocalizedError. Use localizedDescription (or message) in alerts.

didLog(level: String, message: String)

Used for progress and informational events, for example:

• Loading / Loaded states: messages you can map to UI or analytics.

---

Permissions and user experience

• Request camera access before opening Face Liveness if your app flow allows it; otherwise the SDK may return permissionError.
• Ensure good lighting and copy that explains why the user must complete a short live capture.

---

Colors Theming

• Certta: use the session colorConfiguration and useFaceLivenessUi in LivenessConfiguration to customize the Face Liveness UI.
• Dark / light mode: build CafColorConfiguration using UITraitCollection.current.userInterfaceStyle if you need different palettes

Certta.shared.setColorConfiguration(CafColorConfiguration(
        primaryColor: "#FFFFFF",
        secondaryColor: "#222222",
        contentColor: "#FFFFFF",
        backgroundColor: "#000000",
        mediumColor: "#555555",
        dialogBackgroundColor: "#1C1C1E",
        dialogBorderColor: "#E5E5E7"
      )
)

Property	Type	Description	Format
primaryColor	String	Primary buttons, highlights.	Hex code (e.g., #FF0000)
secondaryColor	String	Secondary elements, borders.	Hex code
contentColor	String	Text and icons.	Hex code
backgroundColor	String	Screen background.	Hex code
mediumColor	String	Neutral elements (e.g., progress bars).	Hex code
dialogBackgroundColor	String	Dialog and popup background color.	Hex code
dialogBorderColor	String	Dialog and popup border color.	Hex code

---

Release notes

See Changelog for versions, breaking changes, and minimum Xcode / iOS.

---

Technical Support and Usage Tips

For more details and advanced usage scenarios, refer to the following resources:

• GitHub Repository: access the source code, issue tracking, and release notes in the CafSDK GitHub repository.
• FAQs and Troubleshooting: check our FAQ section for common issues and troubleshooting tips.
• Support: for additional assistance, contact our support team or join our developer community forum.

We continuously update the documentation as new features and improvements are released. Stay up to date for future updates!