API¶

This section covers the native iOS API: how to start the flow, configure the SDK, and implement the available delegates.

Delegate protocols¶

Use these protocols to receive lifecycle callbacks and events:

DocumentCaptureDelegate
- func onDocumentCaptureResults(results: DocumentCaptureResults)
- func onDocumentCaptureStarted()
- func onDocumentCaptureFinished(error: DocumentCaptureError?)
DocumentCaptureEventsDelegate
- func onDocumentCaptureEvent(event: DocumentCaptureEvent)

Starting a flow¶

1) Create a DocumentCaptureConfiguration (build it in code or decode from JSON).

2) Set the events delegate (optional but recommended).

3) Start the SDK with your delegate and configuration.

import UIKit
import VeridasDocumentSDK

final class MyController: UIViewController, DocumentCaptureDelegate, DocumentCaptureEventsDelegate {
    func startDocumentCapture() {
        let config = loadConfigFromJSON("documentCapture", as: DocumentCaptureConfiguration.self)
        DocumentCapture.setEventsDelegate(delegate: self) // DocumentCaptureEventsDelegate
        DocumentCapture.start(delegate: self, configuration: config) // DocumentCaptureDelegate
    }

    // DocumentCaptureDelegate
    func onDocumentCaptureResults(results: DocumentCaptureResults) { print(results) }
    func onDocumentCaptureStarted() { print("SDK started") }
    func onDocumentCaptureFinished(error: DocumentCaptureError?) { print(error as Any) }

    // DocumentCaptureEventsDelegate
    func onDocumentCaptureEvent(event: DocumentCaptureEvent) { print(event) }
}

Example helper for loading JSON configs (shared by all SDKs):

private func loadConfigFromJSON<T: Decodable>(_ name: String, as type: T.Type) -> T {
    guard let url = Bundle.main.url(forResource: name, withExtension: "json") else {
        fatalError("Missing \(name).json in app bundle")
    }
    do {
        let data = try Data(contentsOf: url)
        let decoder = JSONDecoder()
        return try decoder.decode(T.self, from: data)
    } catch {
        fatalError("Failed decoding \(name).json: \(error)")
    }
}

ViewModel example¶

import Foundation
import Combine
import VeridasCommonDefinitions
import VeridasDocumentSDK

final class MainSdkViewModel: ObservableObject {
    func startDocumentCapture() {
        let config = loadConfigFromJSON("documentCapture", as: DocumentCaptureConfiguration.self)
        DocumentCapture.setEventsDelegate(delegate: self)
        DocumentCapture.start(delegate: self, configuration: config)
    }

    private func loadConfigFromJSON<T: Decodable>(_ name: String, as type: T.Type) -> T {
        guard let url = Bundle.main.url(forResource: name, withExtension: "json") else {
            fatalError("Missing \(name).json in app bundle")
        }
        do {
            let data = try Data(contentsOf: url)
            let decoder = JSONDecoder()
            return try decoder.decode(T.self, from: data)
        } catch {
            fatalError("Failed decoding \(name).json: \(error)")
        }
    }
}

extension MainSdkViewModel: DocumentCaptureDelegate, DocumentCaptureEventsDelegate {
    func onDocumentCaptureResults(results: DocumentCaptureResults) { print("onDocumentCaptureResults \(results)") }
    func onDocumentCaptureStarted() { print("onDocumentCaptureStarted") }
    func onDocumentCaptureEvent(event: DocumentCaptureEvent) { print("onDocumentCaptureEvent \(event)") }
    func onDocumentCaptureFinished(error: DocumentCaptureError?) { print("onDocumentCaptureFinished \(String(describing: error))") }
}

Dispatched events¶

The SDK dispatches a set of events to communicate that the corresponding actions have been taken. Each event is sent to onDocumentCaptureEvent(event:), which receives a Codable object:

    public struct DocumentCaptureEvent: Codable, CustomStringConvertible

This object contains 2 main attributes, type with the event identifier and detail with all the information related to the event.

Event Name	Event Detail	Event Trigger
`VD_instructions`	`"sdkName": "VD-DOCUMENT", "type": "info", "flowType": "document"`	When initial instructions are displayed.
`VD_mounted`	`"sdkName": "VD-DOCUMENT", "type": "info", "flowType": "document"`	When the SDK is mounted.
`VD_unmounted`	`"sdkName": "VD-DOCUMENT", "type": "info", "flowType": "document"`	When the SDK is unmounted.
`VD_loaded`	`"sdkName": "VD-DOCUMENT", "type": "info", "flowType": "document"`	When the SDK is fully loaded.
`VD_cameraPermissionsGranted`	`"sdkName": "VD-DOCUMENT", "type": "info", "flowType": "document"`	When the user grants camera permissions.
`VD_cameraStarted`	`"sdkName": "VD-DOCUMENT", "type": "info", "flowType": "document"`	When the camera starts successfully.
`VD_cameraVideoPlayStarted`	`"sdkName": "VD-DOCUMENT", "type": "info", "flowType": "document"`	When the camera video playback begins.
`VD_cameraFailureDefaultError`	`"sdkName": "VD-DOCUMENT", "type": "error", "flowType": "document"`	When camera can't be initialised for any reason.
`VD_cameraFailurePermissionError`	`"sdkName": "VD-DOCUMENT", "type": "error", "flowType": "document"`	When camera permissions are denied.
`VD_successTickFinish`	`"sdkName": "VD-DOCUMENT", "type": "info", "flowType": "document"`	When the success tick animation finishes.
`VD_reviewImage`	`"sdkName": "VD-DOCUMENT", "type": "info", "flowType": "document", "stage": "OBVERSE_REVIEW"`	When the review screen is shown.
`VD_continueClicked`	`"sdkName": "VD-DOCUMENT", "type": "info", "flowType": "document"`	When the continue button is clicked in review.
`VD_capture`	`"sdkName": "VD-DOCUMENT", "type": "info", "flowType": "document", "size": {"height: 1920, "width": 1440"}, "stage": "obverseDetection"`	When the front or back side of the document is captured.
`VD_processFinished`	`"sdkName": "VD-DOCUMENT", "type": "info", "flowType": "document"`	When the process ends, either by completion or timeout.
`VD_closeClicked`	`"sdkName": "VD-DOCUMENT", "type": "info", "flowType": "document"`	When the close button is clicked and user exits from confirmation modal.
`VD_repeatClicked`	`"sdkName": "VD-DOCUMENT", "type": "info", "flowType": "document"`	When the repeat button is clicked in the review screen.
`VD_detectionTimeout`	`"sdkName": "VD-DOCUMENT", "type": "info", "flowType": "document"`	When the process times out.
`VD_restartClicked`	`"sdkName": "VD-DOCUMENT", "type": "info", "flowType": "document"`	When the restart button is clicked after feedback.
`VD_restartProcess`	`"sdkName": "VD-DOCUMENT", "type": "info", "flowType": "document"`	When the process needs to be restarted due to an error.
`VD_manualCaptureButton`	`"sdkName": "VD-DOCUMENT", "type": "info", "flowType": "document"`	When the user captures the document manually.
`VD_loseFocus`	`"sdkName": "VD-DOCUMENT", "type": "info", "flowType": "document"`	When the user has lost the focus on the browser tab.