Implementation Guide¶

This document describes how to implement and use the IDLiveFaceCaptureIAD library for face capture and injection-attack detection (IAD).

Import¶

Import the framework in any file where you need to use it:

import IDLiveFaceCaptureIAD

Set the License Key¶

Before using IDLiveFaceCaptureIAD for face detection, you must set the license key. Typically, you’ll do this in your AppDelegate (or an equivalent initialization point) before presenting any capture controllers:

import IDLiveFaceCaptureIAD

do {
    try License.setLicense("YOUR_LICENSE_KEY", licenseType: .faceDetector)
} catch {
    // Handle error (e.g., show an alert or disable face capture features)
}

Instantiate the Capture Controller¶

Depending on your application's needs, you can choose from several initialization methods ranging from basic instantiation to more advanced custom configurations.

Basic Initialization¶

For the most straightforward setup, instantiate the controller with default options and set the delegate:

let vc = IDCameraController.instantiate()

Initialization with Auto-Capture and Oval Mask¶

To initialize the face capture controller with auto-capture and a visual oval mask overlay, use the instantiate() method and configure the desired detection settings:

func prepareFaceCaptureController() -> IDCameraController? {
    // Instantiate the camera controller
    guard let vc = IDCameraController.instantiate() else { return nil }

    // Configure face detector settings
    var faceDetectorSettings = FaceDetectorSettings()
    faceDetectorSettings.fireDelay = 1 // Delay (in seconds) before triggering capture

    // Choose detection engines to use
    var engines = FaceDetectorEngines()
    engines.insert(.nativeVision)       // Apple's Vision framework
    engines.insert(.faceDetectionSdk)   // IDLiveFaceDetection SDK
    faceDetectorSettings.useEngines(engines)

    // Enable auto-capture mode
    vc.captureMode = .auto

    // Display an oval mask overlay to guide user alignment
    vc.useOvalMask(true)

    // Apply the face detection settings
    vc.faceDetectorSettings = faceDetectorSettings

    // Prepare the controller for use with IAD
    vc.prepareForIAD()

    // Set the delegate to receive capture callbacks
    vc.delegate = self

    return vc
}

Note: Enabling the oval mask helps users correctly position their face within the frame. You can customize detection behavior by adjusting FaceDetectorSettings, such as the fireDelay, etc.

Implement Delegate Methods¶

To properly handle face capture events, your view controller should conform to the IDCameraControllerDelegate protocol. This allows you to respond to key events such as when the user captures an image, encounters an error, or finishes the capture session.

First, set your view controller as the delegate:

let vc = IDCameraController.instantiate()
vc.delegate = self

Then, implement the relevant delegate methods:

extension ViewController: IDCameraControllerDelegate {
    func cameraController(_ controller: IDLiveFaceCaptureIAD.IDCameraControllerBase, didCaptureImage image: IDLiveFaceCaptureIAD.IDImage) {
        // Called when the user captures a face image (either automatically or manually).
        // Use this method to handle the captured image — for example, dismiss the controller,
        // create an IAD bundle for processing, or move to the next step in your flow.
    }

    func cameraController(_ controller: IDLiveFaceCaptureIAD.IDCameraControllerBase, didEncounterError error: IDLiveFaceCaptureIAD.IDCameraControllerBase.Error) {
        // Handle and report the error, dismiss the controller
    }

    func cameraControllerUserDidPressResultButton(_ controller: IDLiveFaceCaptureIAD.IDCameraControllerBase) {
        // Called when the user presses the result button manually.
        // Finalize or move to the next step
    }
}

Present the Controller¶

By default, IDCameraController automatically checks and requests permission to use the device’s camera. However, you may want to:

Proactively check camera permissions yourself, to provide context or instructions before showing any system prompts.
Gracefully handle permission denial by guiding the user to enable permissions in Settings.

Example of presenting the camera controller modally:

present(vc, animated: true)

Capture face¶

When face auto-capture triggers (in auto, .auto_and_manual mode) or when the user taps the capture button (in manual mode) the didCaptureImage delegate method is called:

func cameraController(_ controller: IDLiveFaceCaptureIAD.IDCameraControllerBase, didCaptureImage image: IDLiveFaceCaptureIAD.IDImage) {
    // Example flow
    // Dismiss the camera and show captured doc in a preview
    controller.dismiss(animated: true)

    // Display captured image
    capturedPhotoView.imageView.image = image

    // If desired, you can initiate injection-attack detection (IAD) flow.
}

Injection-Attack Detection (IAD)¶

After successfully capturing face, you can create and send an “IAD bundle” to your server for verification. The createIADBundle() method provides the encrypted payload for server-side validation.

let bundle = try controller.createIADBundle()

func cameraController(_ controller: IDLiveFaceCaptureIAD.IDCameraControllerBase, didCaptureImage image: IDLiveFaceCaptureIAD.IDImage) {
    // Example flow:
    // Dismiss the camera
    controller.dismiss(animated: true)

    // Display captured image
    capturedPhotoView.imageView.image = image

    // Process captured image, i.e. trigger injection-attack detection
    do {
        let bundle = try controller.createIADBundle()
        // Send `bundle` to your server’s endpoint
    } catch {
        // Handle bundle creation errors
        print("IAD Bundle creation error:", error)
    }
}

On the server side, you’d validate this bundle (e.g., via a POST request to https://example.com/check_face_liveness). Then parse the results and inform the user if the face is genuine or not.

Dismiss the Controller¶

Depending on how you've presented IDCameraController, you can dismiss it in your delegate callbacks (e.g., didCaptureImage or didEncounterError). If you presented the controller modally, you’d call:

controller.dismiss(animated: true)

For example:

func cameraController(_ controller: IDLiveFaceCaptureIAD.IDCameraControllerBase, didEncounterError error: IDLiveFaceCaptureIAD.IDCameraControllerBase.Error) {
    print("Error: \(error.localizedDescription).")
    controller.dismiss(animated: true)
}

Summary¶

Import the IDLiveFaceCaptureIAD framework.
Set the license key (e.g., in AppDelegate) before using the face detector.
Instantiate IDCameraController with desired options.
Conform to IDCameraControllerDelegate protocol and implement the required methods to handle result, errors, etc.
Present the controller once camera permission is granted.
Capture the face automatically or via user tap.
Generate and send the IAD bundle to your server for injection-attack detection.
Dismiss the controller when you’re done.