Implementation Guide¶

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

Import¶

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

import IDLiveDocCaptureIAD

Set the License Key¶

Before using IDLiveDocCaptureIAD for document 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 IDLiveDocCaptureIAD

do {
    try License.setLicense("YOUR_LICENSE_KEY", licenseType: .documentDetector)
} catch {
    // Handle error (e.g., show an alert or disable document 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 a Bounding Box¶

If you want to enable document detection with a visual bounding box, pass a bounding box to the instantiation method as shown below:

let imageBoundingBox = DocumentDetector.standartIDCardBoundingBox()
let vc = IDCameraController.instantiate(imageBoundingBox: imageBoundingBox)

Note: DocumentDetector provides several preset bounding boxes tailored for different document formats. Setting DocumentDetector to an empty frame (CGRect.zero or CGRect.null) disables it.

Custom Configuration Options¶

For more advanced scenarios, you can pass custom options during instantiation. The following example demonstrates how to configure the capture controller with additional parameters such as attack detection, a bounding box, and camera position. It also sets extra options like allowing preview before sending.

let vc = IDCameraController.instantiate(
    attackDetection: .injection,
    imageBoundingBox: DocumentDetector.standartIDCardBoundingBox(), cameraPosition: .back
)

vc.allowToPreviewBeforeSending = true

Implement Delegate Methods¶

To use IDCameraController effectively, you must conform to the IDCameraControllerDelegate. This allows your app to respond to various events during document capture, including updates to detection progress, errors, and camera view state changes. Make sure your class adopts the IDCameraControllerDelegate protocol and implements the required methods:

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

func cameraController(_ controller: IDLiveDocCaptureIAD.IDCameraController, didCaptureImage image: UIImage) {
// Called when a document image is captured (automatically or manually).
// Example: Dismiss the camera, display the captured image in a preview, process and verify captured image.
}

func cameraController(_ controller: IDLiveDocCaptureIAD.IDCameraController, didUpdateDetectionResult result: IDLiveDocCaptureIAD.DocumentDetectionResult, image: UIImage) {
    // Called whenever a detection result is updated.
    // You might use this to provide user feedback, e.g.:
    // "Position the document in the frame." or "Move closer to the document."
}

func cameraController(_ controller: IDLiveDocCaptureIAD.IDCameraController, didEncounterError error: any Error) {
    // Handle any runtime errors.
    // Common practice: Log the error and dismiss the controller if it can’t continue.
}


func cameraController(_ controller: IDLiveDocCaptureIAD.IDCameraController, didUpdateLiveImage image: UIImage) {
    // Called whenever the live image has been updated.
    // Accessible it for processing.
}

//The view mode has been updated. React in UI if needed.
func cameraController(_ controller: IDLiveDocCaptureIAD.IDCameraController, didUpdateViewMode viewMode: IDLiveDocCaptureIAD.ViewMode) {
    // Called when the camera view mode change
    // Update UI elements or instructions for the user here.
}

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 the Document¶

When document 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: IDCameraController, didCaptureImage image: UIImage) {
    // 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 the document, 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: IDCameraController, didCaptureImage image: UIImage) {
    // 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_doc_liveness). Then parse the results and inform the user if the document 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: IDCameraController, didEncounterError error: any Error) {
    print("Error: \(error.localizedDescription).")
    controller.dismiss(animated: true)
}

Document Detection Results¶

During capturing, the library may provide detection updates via didUpdateDetectionResult. The DocumentDetectionResult contains QualityWarning enum typically includes states like:

notFound – Document is not detected in the image.
outsideOfImageMask – Document is out of mask bounds
sizeLowerThan10Percent – Document size (area) is lower than 10% of the frame size.
bordersOutsideOfFrame – Document border(s) are outside the frame.
multipleDocumentsInFrame – More than one document are present in the frame.
tooCloseToBorder – Document is too close to the frame border.

Note: These warnings can help you guide users in real time. For example, if notFound is reported, you can display a label instructing the user to align the document within the frame.

Summary¶

Import the IDLiveDocCaptureIAD framework.
Set the license key (e.g., in AppDelegate) before using the document detector.
Instantiate IDCameraController with desired options (bounding box, capture mode, etc.).
Conform to IDCameraControllerDelegate protocol and implement the required methods to handle live detection updates, errors, etc.
Present the controller once camera permission is granted.
Capture the document 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.