iOS Liveness¶

Overview¶

BiometridStandardLiveness provides facial liveness detection capabilities for iOS. It supports two liveness providers: Face01 and Face06. The module handles the full liveness session lifecycle including initialization, capture, and result retrieval.

Prerequisites¶

BiometridStandardCore must be initialized first
iOS 13.0 or higher
Camera permission granted (add NSCameraUsageDescription to Info.plist)

Initialization¶

Create an instance of BiometridStandardLiveness by providing a callback that contains provider configuration and handles liveness events.

import BiometridStandard

class MyLivenessCallback: BiometridStandardLivenessCallback {
    var sessionApi: HeaderOptions? = HeaderOptions(url: "providers/custom/face01/", headers: ["biometrid-credential": "biometrid-credential"], process: "processToken")
    var validateApi: HeaderOptions? = HeaderOptions(url: "processes/", headers: ["biometrid-credential": "biometrid-credential"], process: "processToken")
    var productionKey: String = "your-production-key"
    var token: String = "your-token"
    var publicKey: String = "your-public-key"
    var customization: FaceLivenessCustomization? = nil
    var i18n: [AnyHashable: Any]? = nil
    var data: [String?: Any]? = nil

    func livenessFailure(error: BiometridErrorInfo) {
        // Handle liveness error
    }

    func livenessState(state: LivenessState) {
        // Handle state changes (Started, Stopped)
    }

    func livenessResult(response: BiometridLivenessResponse?) {
        // Handle liveness result
    }

    func livenessSuccess() {
        // Handle liveness success
    }
}

let callback = MyLivenessCallback()
let liveness = BiometridStandardLiveness(livenessCallback: callback)

Available Methods¶

initialise / initialiseFace06¶

Initializes and starts the liveness provider. After successful initialization, the liveness session starts automatically. You must choose one of the two providers.

Face01Face06

func initialise(viewController: UIViewController)

Initializes the Face01 liveness provider. On successful initialization, the SDK automatically calls startLiveness internally to begin the liveness session.

Parameter	Type	Description
`viewController`	`UIViewController`	The presenting view controller for the liveness UI

Lifecycle:

initialise(viewController:) is called
SDK initializes the Face01 provider
On success, startLiveness(viewController) is triggered automatically
livenessState(.started) callback fires
User completes the liveness check
livenessSuccess() and livenessResult(response:) callbacks fire
livenessState(.stopped) callback fires

Example:

let liveness = BiometridStandardLiveness(livenessCallback: callback)
liveness.set(retry: true, attempts: 3, auditTrail: true)
liveness.initialise(viewController: self) // initializes and starts the liveness session

func initialiseFace06(customization: Face06Customization?)

Initializes the Face06 liveness provider. On successful initialization, the SDK automatically calls startFace06 internally to begin the liveness session.

Parameter	Type	Description
`customization`	`Face06Customization?`	Optional customization for the Face06 UI

Lifecycle:

initialiseFace06(customization:) is called
SDK initializes the Face06 provider
On success, startFace06(customization) is triggered automatically
livenessState(.started) callback fires
User completes the liveness check
livenessSuccess() callback fires (via genuinePresence)
livenessState(.stopped) callback fires

Example:

let liveness = BiometridStandardLiveness(livenessCallback: callback)
liveness.set(retry: true, attempts: 3, auditTrail: true)
liveness.initialiseFace06(customization: nil) // initializes and starts the Face06 liveness session

set¶

func set(retry: Bool, attempts: Int32, auditTrail: Bool)

Configures liveness session parameters. Call this before initialise or initialiseFace06.

Parameter	Type	Default	Description
`retry`	`Bool`	`true`	Whether to allow retries on failure
`attempts`	`Int32`	`6`	Maximum number of retry attempts
`auditTrail`	`Bool`	`true`	Whether to include audit trail images

getResponse¶

func getResponse()

Retrieves the liveness session result. The result is delivered through the livenessResult callback method.

Callback Interface¶

BiometridStandardLivenessCallback¶

protocol BiometridStandardLivenessCallback {
    var sessionApi: HeaderOptions? { get }
    var validateApi: HeaderOptions? { get }
    var productionKey: String { get }
    var token: String { get }
    var publicKey: String { get }
    var customization: FaceLivenessCustomization? { get }
    var i18n: [AnyHashable: Any]? { get }
    var data: [String?: Any]? { get }
    func livenessFailure(error: BiometridErrorInfo)
    func livenessState(state: LivenessState)
    func livenessResult(response: BiometridLivenessResponse?)
    func livenessSuccess()
}

Property	Type	Description
`sessionApi`	`HeaderOptions?`	API endpoint and headers for session management
`validateApi`	`HeaderOptions?`	API endpoint and headers for validation
`productionKey`	`String`	Production license key for the liveness provider
`token`	`String`	Authentication token for the device
`publicKey`	`String`	Public key for secure communication
`customization`	`FaceLivenessCustomization?`	Optional UI customization
`i18n`	`[AnyHashable: Any]?`	Optional internationalization strings
`data`	`[String?: Any]?`	Optional additional data for the session

Method	Description
`livenessFailure(error:)`	Called when the liveness session fails
`livenessState(state:)`	Called when the liveness session state changes
`livenessResult(response:)`	Called with the liveness result data
`livenessSuccess()`	Called when the liveness check completes successfully

Data Models¶

BiometridLivenessResponse¶

class BiometridLivenessResponse {
    var auditTrail: String?
    var sessionId: String?
    var faceScan: String?
    var livenessId: String?
}

Property	Type	Description
`auditTrail`	`String?`	Base64-encoded audit trail image
`sessionId`	`String?`	Unique session identifier
`faceScan`	`String?`	Encrypted face scan data
`livenessId`	`String?`	Unique liveness check identifier

BiometridErrorInfo¶

class BiometridErrorInfo {
    var code: String?
    var message: String?
    var data: Any?
}

Enums¶

LivenessState¶

Case	Description
`started`	Liveness session has started
`stopped`	Liveness session has stopped

Error Handling¶

Errors are returned as BiometridErrorInfo objects through the livenessFailure callback. Error codes are prefixed with MSL (Liveness module).

Code	Description
`MSLSRIN001`	BiometridStandard SDK not initialized (Face01)
`MSLSRINF6001`	BiometridStandard SDK not initialized (Face06)

Note: The iOS callback uses BiometridErrorInfo (from the shared module) instead of the Android-specific ErrorInfo type, and returns BiometridLivenessResponse instead of LivenessResponse.

Usage Example¶

Face01Face06

import BiometridStandard

class LivenessViewController: UIViewController, BiometridStandardLivenessCallback {

    private var liveness: BiometridStandardLiveness?

    // MARK: - Callback Properties
    var sessionApi: HeaderOptions? = HeaderOptions(
        url: "providers/custom/face01/",
        headers: ["biometrid-credential": "biometrid-credential"],
        process: "processToken"
    )
    var validateApi: HeaderOptions? = HeaderOptions(
        url: "processes/",
        headers: ["biometrid-credential": "biometrid-credential"],
        process: "processToken"
    )
    var productionKey: String = "production-key"
    var token: String = "device-token"
    var publicKey: String = "public-key"
    var customization: FaceLivenessCustomization? = nil
    var i18n: [AnyHashable: Any]? = nil
    var data: [String?: Any]? = nil

    override func viewDidLoad() {
        super.viewDidLoad()

        liveness = BiometridStandardLiveness(livenessCallback: self)

        // Configure session parameters
        liveness?.set(retry: true, attempts: 3, auditTrail: true)

        // Initialize Face01 liveness provider
        liveness?.initialise(viewController: self)
    }

    // Call this to start the Face01 liveness session after initialization
    func startLiveness() {
        liveness?.initialise(viewController: self)
    }

    // Call this to retrieve the liveness result after success
    func fetchResult() {
        liveness?.getResponse()
    }

    // MARK: - Callback Methods
    func livenessFailure(error: BiometridErrorInfo) {
        print("Liveness failed: \(error.message ?? "")")
    }

    func livenessState(state: LivenessState) {
        switch state {
        case .started:
            print("Liveness session started")
        case .stopped:
            print("Liveness session stopped")
        default:
            break
        }
    }

    func livenessResult(response: BiometridLivenessResponse?) {
        guard let response = response else { return }
        // Get liveness data
        let sessionId = response.sessionId
        let auditTrail = response.auditTrail
    }

    func livenessSuccess() {
        print("Liveness check succeeded")
    }
}

import BiometridStandard

class LivenessViewController: UIViewController, BiometridStandardLivenessCallback {

    private var liveness: BiometridStandardLiveness?

    // MARK: - Callback Properties
    var sessionApi: HeaderOptions? = HeaderOptions(
        url: "providers/custom/face06/",
        headers: ["biometrid-credential": "biometrid-credential"],
        process: "processToken"
    )
    var validateApi: HeaderOptions? = HeaderOptions(
        url: "processes/",
        headers: ["biometrid-credential": "biometrid-credential"],
        process: "processToken"
    )
    var productionKey: String = "production-key"
    var token: String = "device-token"
    var publicKey: String = "public-key"
    var customization: FaceLivenessCustomization? = nil
    var i18n: [AnyHashable: Any]? = nil
    var data: [String?: Any]? = nil

    override func viewDidLoad() {
        super.viewDidLoad()

        liveness = BiometridStandardLiveness(livenessCallback: self)

        // Configure session parameters
        liveness?.set(retry: true, attempts: 3, auditTrail: true)

        // Initialize Face06 liveness provider
        liveness?.initialiseFace06(customization: nil)
    }

    // Call this to start the Face06 liveness session after initialization
    func startFace06() {
        liveness?.initialiseFace06(customization: nil)
    }

    // Call this to retrieve the liveness result after success
    func fetchResult() {
        liveness?.getResponse()
    }

    // MARK: - Callback Methods
    func livenessFailure(error: BiometridErrorInfo) {
        print("Liveness failed: \(error.message ?? "")")
    }

    func livenessState(state: LivenessState) {
        switch state {
        case .started:
            print("Liveness session started")
        case .stopped:
            print("Liveness session stopped")
        default:
            break
        }
    }

    func livenessResult(response: BiometridLivenessResponse?) {
        guard let response = response else { return }
        // Get liveness data
        let sessionId = response.sessionId
        let auditTrail = response.auditTrail
    }

    func livenessSuccess() {
        print("Liveness check succeeded")
    }
}