iOS SDK Reference

This page documents the public Swift API of the iLive iOS SDK: entry points, configuration, result types, and face comparison helpers. For a step-by-step integration walkthrough, see the iOS quickstart.

Installation

The SDK ships as two Swift targets: ILiveCore (engine, configuration, results) and ILiveUI (drop-in LivenessViewController). Both are distributed via Swift Package Manager and CocoaPods. See the quickstart for full setup.

Minimum deployment target: iOS 14.0.

import ILiveCore
import ILiveUI

Entry points

There are two ways to run a liveness session:

1. Drop-in UI — LivenessViewController from ILiveUI. A full-screen UIViewController that handles camera, guidance, challenges, and the result screen. SwiftUI callers can wrap it with UIViewControllerRepresentable.
2. Custom UI — LivenessEngine from ILiveCore. You drive the camera and UI; the engine consumes CVPixelBuffer frames and returns a verdict.

Top-level helpers live on the ILive class:

Drop-in UI: LivenessViewController

LivenessViewController is a plain UIViewController. Create it, set result callbacks, then present it modally.

import ILiveCore
import ILiveUI
 
let vc = LivenessViewController(config: ILiveConfig(), passiveMode: true)
vc.onResult = { result in
    if result.verdict == .pass {
        // result.icaoPhoto, result.faceEmbedding, result.attestation
    }
}
vc.modalPresentationStyle = .fullScreen
present(vc, animated: true)

For SwiftUI, wrap it with UIViewControllerRepresentable:

struct LivenessFlow: UIViewControllerRepresentable {
    let onResult: (LivenessResult) -> Void
    func makeUIViewController(context: Context) -> LivenessViewController {
        let vc = LivenessViewController()
        vc.onResult = onResult
        return vc
    }
    func updateUIViewController(_ vc: LivenessViewController, context: Context) {}
}

Custom UI: LivenessEngine

LivenessEngine exposes the capture pipeline without a bundled UI.

let engine = await LivenessEngine.create(config: ILiveConfig())
await engine.initialize()
 
// For each CVPixelBuffer from AVCaptureVideoDataOutput:
let tracking = engine.processFrame(pixelBuffer: pixelBuffer)
 
// Passive flow:
let result = await engine.evaluatePassiveVerdict()
engine.release()

Configuration: ILiveConfig

ILiveConfig is a value type with a memberwise initializer — pass only the fields you want to override.

Challenges and verdict thresholds

ChallengeType values: .blink, .turnLeft, .turnRight, .nod, .smile, .mouthOpen, .eyebrowRaise, .eyeFollow.

eyeFollow on iOS. The drop-in LivenessViewController does not currently render the moving-dot overlay that this challenge needs. To avoid showing users a prompt with no visible target, .eyeFollow is omitted from ILiveConfig.defaultChallengeTypes. The enum case is still public so sessions that ran with earlier defaults continue to compile, and callers who supply a custom UI can opt in by passing it explicitly in challengeTypes — the SDK emits an os_log warning when they do. eyeFollow remains fully supported on Android and Flutter; iOS parity will land when the overlay ships.

Voice prompts

Photo extraction

Security

Timeouts

var config = ILiveConfig(
    challengeCount: 4,
    passThreshold: 0.75,
    voicePromptsEnabled: true
)
config.attestationKeyBase64 = "MTIzNDU2Nzg5MDEyMzQ1Ng=="

Results: LivenessResult

Returned by evaluateVerdict() and evaluatePassiveVerdict(), and delivered via LivenessViewController.onResult.

Face recognition: ILive.compareFaces()

One-shot 1:1 face comparison. Returns nil if an image cannot be decoded or no face is found.

static func compareFaces(
    reference: Data,   // JPEG data
    probe: Data,       // JPEG data
    threshold: Float = FaceRecognition.defaultThreshold  // 0.45
) -> FaceMatchResult?
 
static func compareFaceWithEmbedding(
    referenceEmbedding: [Float],   // 512 floats from LivenessResult.faceEmbedding
    probe: Data,
    threshold: Float = 0.45
) -> FaceMatchResult?

FaceMatchResult: similarity: Float (cosine similarity, 0.0–1.0), isMatch: Bool (similarity >= threshold), threshold: Float.

// Compare an ID document photo against the captured liveness photo.
if let match = ILive.compareFaces(
    reference: idDocumentJpegData,
    probe: result.icaoPhoto!
), match.isMatch {
    // Same person, match.similarity
}
 
// Later: compare the stored embedding against a new selfie.
if let match = ILive.compareFaceWithEmbedding(
    referenceEmbedding: result.faceEmbedding!,
    probe: newSelfieJpegData
) {
    // ...
}

Error handling

The engine does not throw on evaluation — instead, failures surface via LivenessResult.verdict == .fail with failureReason set. Common reasons:

Camera permission is the caller's responsibility — ensure NSCameraUsageDescription is set and permission is granted before presenting LivenessViewController.

See also