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:

SelfieCaptureDelegate
- func onSelfieCaptureResults(results: SelfieCaptureResults)
- func onSelfieCaptureStarted()
- func onChallengeTokenRequired()
- func onSelfieCaptureFinished(error: SelfieCaptureError?)
SelfieCaptureEventsDelegate
- func onSelfieCaptureEvent(event: SelfieCaptureEvent)

Starting a flow¶

1) Create a SelfieCaptureConfiguration (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 VeridasSelfieSDK

final class MyController: UIViewController, SelfieCaptureDelegate, SelfieCaptureEventsDelegate {
    func startSelfieCapture() {
        let config = loadConfigFromJSON("selfieCapture", as: SelfieCaptureConfiguration.self)
        SelfieCapture.setEventsDelegate(delegate: self) // SelfieCaptureEventsDelegate
        SelfieCapture.start(delegate: self, configuration: config) // SelfieCaptureDelegate
    }

    // SelfieCaptureDelegate
    func onSelfieCaptureResults(results: SelfieCaptureResults) { print(results) }
    func onSelfieCaptureStarted() { print("SDK started") }
    func onChallengeTokenRequired() { print("Challenge token required") }
    func onSelfieCaptureFinished(error: SelfieCaptureError?) { print(error as Any) }

    // SelfieCaptureEventsDelegate
    func onSelfieCaptureEvent(event: SelfieCaptureEvent) { 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 VeridasSelfieSDK

final class MainSdkViewModel: ObservableObject {
    func startSelfieCapture() {
        let config = loadConfigFromJSON("selfieCapture", as: SelfieCaptureConfiguration.self)
        SelfieCapture.setEventsDelegate(delegate: self)
        SelfieCapture.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: SelfieCaptureDelegate, SelfieCaptureEventsDelegate {
    func onSelfieCaptureResults(results: SelfieCaptureResults) { print("onSelfieCaptureResults \(results)") }
    func onSelfieCaptureStarted() { print("onSelfieCaptureStarted") }
    func onChallengeTokenRequired() { print("onChallengeTokenRequired") }
    func onSelfieCaptureEvent(event: SelfieCaptureEvent) { print("onSelfieCaptureEvent \(event)") }
    func onSelfieCaptureFinished(error: SelfieCaptureError?) { print("onSelfieCaptureFinished \(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 onSelfieCaptureEvent(event:), which receives a Codable object:

    public struct SelfieCaptureEvent: 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-SELFIE", "type": "info", "flowType": "selfie"`	When initial instructions are displayed.
`VD_mounted`	`"sdkName": "VD-SELFIE", "type": "info", "flowType": "selfie"`	When the SDK is mounted.
`VD_unmounted`	`"sdkName": "VD-SELFIE", "type": "info", "flowType": "selfie"`	When the SDK is unmounted.
`VD_loaded`	`"sdkName": "VD-SELFIE", "type": "info", "flowType": "selfie"`	When the SDK is fully loaded.
`VD_flowStarted`	`"sdkName": "VD-SELFIE", "type": "info", "flowType": "selfie"`	When the capture flow starts.
`VD_faceNotCentered`	`"sdkName": "VD-SELFIE", "type": "info", "flowType": "selfie"`	When the face is detected as not centered.
`VD_cameraPermissionsGranted`	`"sdkName": "VD-SELFIE", "type": "info", "flowType": "selfie"`	When the user grants camera permissions.
`VD_cameraStarted`	`"sdkName": "VD-SELFIE", "type": "info", "flowType": "selfie"`	When the camera starts successfully.
`VD_cameraVideoPlayStarted`	`"sdkName": "VD-SELFIE", "type": "info", "flowType": "selfie"`	When the camera video playback begins.
`VD_cameraRecorderSetup`	`"sdkName": "VD-SELFIE", "type": "info", "flowType": "selfie","width": 960, "height": 1280"`	When the camera recording is configured.
`VD_headOkMovement`	`"sdkName": "VD-SELFIE", "type": "info", "flowType": "head", "movementRequested": "top", "challengeNumber": 1`	When a correct head movement is made.
`VD_headWrongMovementError`	`"sdkName": "VD-SELFIE", "type": "error", "flowType": "selfie"`	When an incorrect head movement is detected.
`VD_headMovementTimeoutError`	`"sdkName": "VD-SELFIE", "type": "error", "flowType": "selfie"`	When a head movement has not been detected.
`VD_cameraRecorderStop`	`"sdkName": "VD-SELFIE", "type": "info", "flowType": "selfie"`	When the camera recording is stopped.
`VD_successTickFinish`	`"sdkName": "VD-SELFIE", "type": "info", "flowType": "selfie"`	When the success tick animation finishes.
`VD_capture`	`"sdkName": "VD-SELFIE", "type": "info", "flowType": "selfie","size": {"height: 1920, "width": 1440"}, "stage": "faceDetection"`	When the final capture completes after success tick.
`VD_capturedSelfie`	`"sdkName": "VD-SELFIE", "type": "info", "flowType": "selfie"`	When the initial selfie is captured before head movements.
`VD_capturedHead`	`"sdkName": "VD-SELFIE", "type": "info", "flowType": "selfie"`	When the head movement process is completed.
`VD_processFinished`	`"sdkName": "VD-SELFIE", "type": "info", "flowType": "selfie"`	When the whole process is finished, either successfully or with an error.
`VD_cameraFailureDefaultError`	`"sdkName": "VD-SELFIE", "type": "error", "flowType": "selfie"`	When camera can't be initialised for any reason.
`VD_cameraFailurePermissionError`	`"sdkName": "VD-SELFIE", "type": "error", "flowType": "selfie"`	When camera permissions are denied.
`VD_detectionTimeout`	`"sdkName": "VD-SELFIE", "type": "info", "flowType": "selfie"`	When the flow ends due to timeout.
`VD_repeatClicked`	`"sdkName": "VD-SELFIE", "type": "info", "flowType": "selfie"`	When the repeat button is clicked in the review screen.
`VD_closeClicked`	`"sdkName": "VD-SELFIE", "type": "info", "flowType": "selfie"`	When the close button is clicked and user exits from confirmation modal.
`VD_restartClicked`	`"sdkName": "VD-SELFIE", "type": "info", "flowType": "selfie"`	When the restart button is clicked after feedback screen.
`VD_restartProcess`	`"sdkName": "VD-SELFIE", "type": "info", "flowType": "selfie"`	When the process needs to be restarted due to an error.
`VD_restartFromModal`	`"sdkName": "VD-SELFIE", "type": "info", "flowType": "selfie"`	When the process needs to be restarted after help or error modal.
`VD_challengeUpdated`	`"sdkName": "VD-SELFIE", "type": "info", "flowType": "selfie"`	When the challenge token is updated after an error.
`VD_cameraRecorderSetupError`	`"sdkName": "VD-SELFIE", "type": "error", "flowType": "selfie"`	When the camera recorder setup fails.
`VD_continueClicked`	`"sdkName": "VD-SELFIE", "type": "info", "flowType": "selfie"`	When the continue button is clicked in review.
`VD_reviewImage`	`"sdkName": "VD-SELFIE", "type": "info", "flowType": "selfie"`	When the review screen is shown.
`VD_loseFocus`	`"sdkName": "VD-SELFIE", "type": "info", "flowType": "selfie"`	When the user has lost the focus on the browser tab.