The list of all supported documents and result fields can be found here.

Table of Contents

• Requirements
• Quick Start

• BlinkID Components

• BlinkIDUX Components

• Creating custom UX component
• Localization
• SDK Integration Troubleshooting
• SDK size
• Additional info

Requirements

SDK package contains BlinkID framework, BlinkIDUX package and one or more sample apps that demonstrate their integration. The BlinkID framework can be deployed on iOS 15.0 or later and BlinkIDUX package can be deployed on iOS 16.0 or later. The framework and package support Swift projects.

Both BlinkID and BlinkIDUX are dynamic packages

This project is designed with Swift 6, leveraging the latest concurrency features to ensure efficient, and modern application performance.

BlinkIDUX is built with full support for SwiftUI, enabling seamless integration of declarative user interfaces with modern, responsive design principles.

Requirements

| SDK | Platform | Installation | Minimum Swift Version | Type | | ---------- | -------------- | ----------------------------------------------- | --------------------- | ------- | | BlinkID | iOS 15.0+ | Swift Package Manager | 5.10 / Xcode 15.3 | Dynamic | | BlinkIDUX | iOS 16.0+ | Swift Package Manager | 5.10 / Xcode 15.3 | Dynamic |

Quick Start

In this section, you will initialize the SDK, create a capture session, and submit the images for either server-side or client-side verification, resulting in a fraud verdict and a detailed analysis of the document images.

Getting started with the BlinkID SDK

This Quick Start guide will get you up and performing document scanning as quickly as possible. All steps described in this guide are required for the integration.

This guide closely follows the BlinkID app in the Samples folder of this repository. We highly recommend you try to run the sample app. The sample app should compile and run on your device.

The source code of the sample app can be used as a reference during the integration.

Integration

To integrate the BlinkID SDK into your iOS project, you'll need to:

1. Obtain a valid license key from the Microblink dashboard
2. Add the SDK framework to your project

Swift Package Manager

The Swift Package Manager is a tool for automating the distribution of Swift code and is integrated into the swift compiler.

Once you have your Swift package set up, adding BlinkID and BlinkIDUX as a dependency are as easy as adding it to the dependencies value of your Package.swift or the Package list in Xcode.

##### BlinkID

We provide a URL to the public package repository that you can add in Xcode:

https://github.com/microblink/blinkid-ios

##### BlinkIDUX

dependencies: [
    .package(url: "https://github.com/microblink/blinkid-ios.git", .upToNextMajor(from: "8001.0.0"))
]

Normally you'll want to depend on the BlinkIDUX target:

.product(name: "BlinkIDUX", package: "blinkid-ios")

The package manifest is named BlinkIDUX, but Swift Package Manager identifies a package by its repository name, so the package: argument is "blinkid-ios".

BlinkIDUX has a binary target dependency on BlinkID, so use this package only if you are also using our UX.

You can see dependency in our Package.swift:

.binaryTarget(
    name: "BlinkID",
    path: "Frameworks/BlinkID.xcframework"
)

Manual integration

If you prefer not to use Swift Package Manager, you can integrate BlinkID and BlinkIDUX into your project manually.

##### BlinkID

Download latest release (Download BlinkID.xcframework.zip file or clone this repository).

• Copy BlinkID.xcframework to your project folder.

• In your Xcode project, open the Project navigator. Drag the BlinkID.xcframework file to your project, ideally in the Frameworks group.

• Since BlinkID.xcframework is a dynamic framework, you also need to add it to embedded binaries section in General settings of your target and choose option Embed & Sign.

• Open up Terminal, cd into your top-level project directory, and run the following command "if" your project is not initialized as a git repository:

$ git init

• Add BlinkIDUX as a git submodule by running the following command:

$ git submodule add https://github.com/microblink/blinkid-ios.git

To add a local Swift package as a dependency in Xcode: 1. Go to your Xcode project. 2. Select your project in the Project Navigator. 3. Go to the Package Dependencies tab under your project settings. 4. Click the ”+” button to add a new dependency. 5. In the dialog that appears, select the “Add Local…” option at the bottom left. 6. Navigate to the folder containing your local Swift package and select it.

This will add the local Swift package as a dependency to your Xcode project.

BlinkIDUX has a binary target dependency on BlinkID, so use this package only if you are also using our UX.

AI coding assistants

If you integrate with the help of an AI coding assistant, install the BlinkID skills — packaged instructions that teach the assistant this SDK's API, so it writes integration code against the real types instead of guessing.

Download BlinkID-ux-skill.zip and/or BlinkID-core-skill.zip from the latest release and unzip them into your project:

mkdir -p .claude/skills
unzip BlinkID-ux-skill.zip   -d .claude/skills   # scanning screen, custom UX, theming
unzip BlinkID-core-skill.zip -d .claude/skills   # headless / Direct API, results, resources

Install the UX skill if you use BlinkIDUX, the Core skill if you process images without our camera UI, or both. The skills are versioned with the SDK — re-download them when you upgrade.

Initiating the document scanning process

In files in which you want to use the functionality of the SDK place the import directive.

import BlinkID

1. Initialize the SDK with your license key:

let settings = BlinkIDSdkSettings(
    licenseKey: "your-license-key",
    resourcesConfiguration: ResourcesConfig(download: true)
)
let sdk = try await BlinkIDSdk.createBlinkIDSdk(withSettings: settings)

Migration note: the standalone downloadResources initializer argument has been replaced by a grouped resourcesConfiguration: ResourcesConfig. See SDK Settings for the full mapping.

1. Create a capture session:

let session = await sdk.createScanningSession()

1. Process images and handle results:

let scanResult = await session.process(inputImage: capturedImage)
if scanResult.processResult?.inputImageAnalysisResult.processingStatus == .success { 
    let finalResult = await session.getResult()
}

Initiating BlinkID UX

In files in which you want to use the functionality of the SDK place the import directive.

import BlinkIDUX

1. Initialize the BlinkIDAnalyzer:

• Begin by creating an instance of the BlinkIDAnalyzer after initializing the capture session:

let analyzer = await BlinkIDAnalyzer(sdk: sdk)

1. Display the BlinkIDUXView in SwiftUI:

• Add the BlinkIDUXView to your SwiftUI view hierarchy using the BlinkIDAnalyzer:

struct ContentView: View {
    var body: some View {
        BlinkIDUXView(analyzer: analyzer) { scanningResultState in }
    }
}

1. Access results:

BlinkIDUXView(analyzer: analyzer) { scanningResultState in
    if let scanningResult = scanningResultState.scanningResult {
        // do sth with result
    } else {
        // or here if there's no result
    }
}

1. You can also pass ScanningUXSettings as a view modifier:

BlinkIDUXView(analyzer: analyzer) { scanningResultState in
}
.uxSettings(uxSettings)

1. Observe per-frame processing with the onFrameProcessResult view modifier:

• This modifier delivers a FrameProcessResultHandle on every processed camera frame (and once when the hard step timeout fires). Use resultCompleteness to inspect how much data has been extracted so far and decide whether to advance the scanning session to the next step:

BlinkIDUXView(analyzer: analyzer) { scanningResultState in
}
.onFrameProcessResult { handle in
    guard let completeness = handle.processResult?.resultCompleteness else { return }
    // inspect completeness and decide whether to advance to the next step
}

Important: Do not use BlinkIDScanningResult for this decision. ResultCompleteness is lightweight, always available per frame, and describes extraction status and presence requirements without constructing a full result.

Warning: This handle is delivered on the frame processing context, not on the main thread. Dispatch any UI work to DispatchQueue.main or @MainActor as needed.

Initiating BlinkID

BlinkID is a powerful document scanning solution designed to enhance the security and accuracy of document scanning processes.

BlinkID Components

BlinkIDSdk

The BlinkIDSdk class serves as the main entry point for document scanning functionality. It manages SDK initialization, resource downloading, and session creation.

let settings = BlinkIDSdkSettings(
    licenseKey: "your-license-key",
    resourcesConfiguration: ResourcesConfig(download: true)
)
do {
    let sdk = try await BlinkIDSdk.createBlinkIDSdk(withSettings: settings)
    let session = await sdk.createScanningSession()
    // Use the session for document scanning
} catch {
    // Handle initialization errors
}

BlinkIDSession

BlinkIDSession is a Swift class that manages document scanning operations, providing a robust interface for capturing, processing, and validating documents through image analysis and scanning.

The BlinkIDSession class serves as the primary controller for document scanning workflows, handling various aspects such as:

• Image processing and analysis
• Session lifecycle management
• Result generation and processing

Initialization

let sdk = try await BlinkIDSdk.createBlinkIDSdk(withSettings: settings)
let BlinkIDSession = await sdk.createScanningSession()

Creates a new capture session with specified settings and resource path configurations.

Key Features

##### Cancel Processing

public func cancelActiveProcessing()

Immediately terminates any ongoing processing operations. This method can be called from any context and is useful for handling user cancellations or session aborts.

##### Image Processing

@ProcessingActor
public func process(inputImage: InputImage) -> FrameProcessResult

Processes an input image and provides detailed analysis results. This method:

• Analyzes the provided image according to session settings
• Returns a FrameProcessResult containing analysis results and completion status
• Must be executed within the ProcessingActor context

@ProcessingActor
public func getResult() -> BlinkIDScanningResult

Retrieves the final results of the capture session, including:

• All captured images
• Session metadata
• Must be called within the ProcessingActor context

Usage Example

/// Processes a camera frame for document analysis.
/// - Parameter image: The camera frame to analyze
public func analyze(image: CameraFrame) async {
    guard !paused else { return }
    let inputImage = InputImage(cameraFrame: image)
    
    let result = await BlinkIDSession.process(inputImage: inputImage)
if result.processResult?.inputImageAnalysisResult.processingStatus == .success {
        Task { @ProcessingActor in
            let sessionResult = session.getResult()
            // Finish scanning
        }
    }
}

Please refer to our BlinkIDAnalyzer in the BlinkIDUX module for implementation details and guidance on its usage.

Integration Considerations

1. Actor Isolation: Many methods must be called within the ProcessingActor context to ensure thread safety
2. Session Management: Each session maintains its own unique identifier and state
3. Resource Management: Proper initialization with valid resource paths is crucial for operation
4. Cancellation Support: Operations can be cancelled at any time using cancelActiveProcessing()

• Ensure proper error handling for processing operations
• Consider implementing timeout mechanisms for long-running operations
• Maintain proper lifecycle management of the session
• Handle results appropriately according to your application's needs

FrameProcessResult

• processResult: ProcessResult? - The result of the frame processing, or nil if processing did not produce one.
• sessionError: SessionError? - The error that occurred during processing, if any.

ScanningSettings

ScanningSettings is the central configuration for how a document is scanned. It groups together the individual extraction modules — document capture, MRZ, barcode, and VIZ — along with the data-matching tolerance. It's passed to BlinkIDSessionSettings, which in turn configures a scanning session.

Each module is optional. A nil module means that module is disabled; a non-nil module means it runs with the supplied settings. By default every module is enabled with its standard settings.

| Property | Type | Default | Description | |----------|------|---------|-------------| | documentCaptureModule | DocumentCaptureModuleSettings? | .init() | Document detection, image extraction, and image-quality validation | | mrzModule | MrzModuleSettings? | .init() | Machine Readable Zone detection and parsing | | barcodeModule | BarcodeModuleSettings? | .init() | 1D/2D barcode detection and data extraction | | vizModule | VizModuleSettings? | .init() | Visual Inspection Zone field extraction | | maxAllowedMismatchesPerField | Int | 0 | Max characters per field that may differ during data matching across sides |

let settings = ScanningSettings(
    documentCaptureModule: DocumentCaptureModuleSettings(),
    mrzModule: MrzModuleSettings(),
    barcodeModule: BarcodeModuleSettings(),
    vizModule: VizModuleSettings(),
    maxAllowedMismatchesPerField: 0
)

To disable a module entirely, pass nil:

// Capture-only configuration with no barcode scanning
let settings = ScanningSettings(barcodeModule: nil)

DocumentCaptureModuleSettings

Responsible for the initial document detection, image extraction (face, document, signature), and image-quality validation (blur, glare, lighting, tilt, hand occlusion).

| Property | Type | Default | Description | |----------|------|---------|-------------| | cropType | InputImageCropType | .notCropped | How the input image is treated for document localization and perspective correction. .cropped and .unknown apply to Photo source only (validation error if used with Video). See InputImageCropType. | | unsupportedDocumentsAllowed | Bool | false | Allow processing of documents classified as OTHER. | | secondSideWithNoExtractableDataSkipped | Bool | true | Stop after the front side when the back has no extractable data. If false, the back is still captured. | | passportDataPageScanOnly | Bool | true | Scan only the passport data page (the one with the MRZ). If false, a second page may be required for some passports. | | faceImageExtractionEnabled | Bool | false | Extract the document's face image when present. | | faceImagePresenceMandatory | Bool | false | Require a face image. In Automatic mode the side with the face must be scanned first. | | inputImageReturnEnabled | Bool | false | Return the input images in the result. Significantly increases memory use. | | documentImageReturnEnabled | Bool | false | Return the cropped document image in the result. | | inputImageMargin | Float? | 0.02 | Minimum margin (0.0–1.0) between the image edge and the document. Video source only; ignored when cropType == .cropped. | | dotsPerInch | DPI | 250 | DPI for cropped document, face, and signature images. Allowed range 100–400. | | extensionFactor | Float | 0.0 | Extension factor (0.0–1.0) for the cropped document image. Document images only. | | blurSensitivityLevel | SensitivityLevel | .mid | Sensitivity of blur detection. | | imageWithBlurRejected | Bool? | true | Reject blurry images (sets ProcessingStatus to imagePreprocessingFailed). If false, blur is reported but processed. | | glareSensitivityLevel | SensitivityLevel | .mid | Sensitivity of glare detection. | | imageWithGlareRejected | Bool? | true | Reject images with glare. If false, glare is reported but processed. | | tiltSensitivityLevel | SensitivityLevel | .mid | Sensitivity of allowed document tilt. | | imageWithPoorLightingRejected | Bool | true | Reject images that are tooBright or tooDark. | | imageWithHandOcclusionRejected | Bool? | true | Reject images occluded by a hand. Applies only when cropType != .cropped. | | inputImageSelectionStrategy | InputImageSelectionStrategy | .balanced | Strategy for selecting the best image from a pool of stable frames. Video source only. See InputImageSelectionStrategy. |

Bool? fields use nil to defer to SDK behavior, distinct from an explicit true/false.

MrzModuleSettings

Handles detection and parsing of the Machine Readable Zone found on passports, visas, and identity cards.

| Property | Type | Default | Description | |----------|------|---------|-------------| | presenceMandatory | Bool | false | Require an MRZ regardless of document rules. In Single mode it must be on the scanned side; in Automatic mode on one of the scanned sides. |

If a timeout advances the flow and an MRZ was detected but not extractable, the presence requirement is treated as fulfilled — MRZ extraction won't block completion on the next side.

BarcodeModuleSettings

Manages detection and data extraction from 1D and 2D barcode formats (PDF417, QR, and various retail codes). Can run standalone or alongside document capture.

| Property | Type | Default | Description | |----------|------|---------|-------------| | presenceMandatory | Bool | false | Require a barcode. Single mode: on the scanned side. Automatic mode: on one of the scanned sides. | | barcodeImageReturnEnabled | Bool | false | Return the barcode image. DPI and extension factor do not affect it. | | pdf417ScanningEnabled | Bool | true | Enable PDF417 scanning. | | qrScanningEnabled | Bool | true | Enable QR scanning. | | upceScanningEnabled | Bool | false | Enable UPC-E. Only if document capture is disabled. | | upcaScanningEnabled | Bool | false | Enable UPC-A. Only if document capture is disabled. | | code128ScanningEnabled | Bool | false | Enable Code-128. Only if document capture is disabled. | | code39ScanningEnabled | Bool | false | Enable Code-39. Only if document capture is disabled. | | ean8ScanningEnabled | Bool | false | Enable EAN-8. Only if document capture is disabled. | | ean13ScanningEnabled | Bool | false | Enable EAN-13. Only if document capture is disabled. | | itfScanningEnabled | Bool | false | Enable ITF. Only if document capture is disabled. | | dataMatrixScanningEnabled | Bool | false | Enable DataMatrix. Only if document capture is disabled. | | aztecScanningEnabled | Bool | false | Enable Aztec. Only if document capture is disabled. |

Important: The analyzer model flags a barcode as "present" when it detects either a PDF417 or a QR code, without distinguishing between them at that stage. If pdf417ScanningEnabled is on but qrScanningEnabled is off (or vice versa), the analyzer can trigger on the other type and hang. Keep pdf417ScanningEnabled and qrScanningEnabled enabled together.

VizModuleSettings

Extracts data from the document's visual fields. Supports character validation, signature image extraction, and aggregation across multiple video frames.

| Property | Type | Default | Description | |----------|------|---------|-------------| | presenceMandatory | Bool | false | Require VIZ. Single mode scans the front of supported documents only. Automatic mode is unaffected (front then back). | | signatureImageExtractionEnabled | Bool | false | Extract the signature image where supported by document rules. | | characterValidationEnabled | Bool | true | Allow only results with expected characters per field. An invalid character yields ProcessingStatus.invalidCharactersFound. Improves accuracy. | | resultAggregationEnabled | Bool? | true | Aggregate data across frames. Disabling yields higher-quality images but slower scanning. Video source only; ignored for Photo. |

If a front-side VIZ isn't fully extracted before a timeout advances the flow, extraction continues on the back side when present.

Supporting types

InputImageCropType

Controls how DocumentCaptureModuleSettings.cropType treats the input image with respect to document localization and perspective correction.

• notCropped — default. The image is treated as raw and runs through the full detection and perspective-correction pipeline. Applicable to both Photo and Video sources.
• unknown — the image may be cropped, but there's no guarantee. The SDK first attempts to treat it as cropped and, if extraction fails, falls back to the normal detect-and-crop pipeline. Photo source only.
• cropped — the image is already cropped and perspective-corrected. Photo source only.

Using unknown or cropped with a Video input source causes a validation error.

InputImageSelectionStrategy

Controls how DocumentCaptureModuleSettings.inputImageSelectionStrategy picks the best frame from a pool of stable input images. A larger pool improves the chance of a high-quality capture but can add a slight delay. Video source only.

• singleImage — selects the first acceptable stable image.
• optimizeForSpeed — faster, but may pick a lower-quality image (smaller pool considered).
• balanced — default. Trade-off between speed and quality.
• optimizeForQuality — slower; considers a larger pool to select a higher-quality image.

SensitivityLevel

Configures detection sensitivity for blur, glare, and tilt.

• off — detection disabled
• low — less sensitive
• mid — balanced (default for quality checks)
• high — most sensitive

DPI

A type alias for UInt16, used by dotsPerInch.

Putting it together

ScanningSettings is supplied via BlinkIDSessionSettings, which is what a scanning session actually consumes:

let sessionSettings = BlinkIDSessionSettings(
    inputImageSource: .video,
    scanningMode: .automatic,
    scanningSettings: ScanningSettings(
        documentCaptureModule: DocumentCaptureModuleSettings(
            faceImageExtractionEnabled: true,
            documentImageReturnEnabled: true
        ),
        mrzModule: MrzModuleSettings(presenceMandatory: true),
        barcodeModule: BarcodeModuleSettings(),
        vizModule: VizModuleSettings()
    ),
    stepTimeoutDuration: 60.0,
    inactivityTimeoutDuration: 10.0
)

Redaction

Redaction lets you anonymize sensitive data from a scanned document before the result is finalized. You can apply redaction uniformly, or vary it per document by implementing a RedactionSettingsResolver.

RedactionSettings

Describes what gets redacted from a scanned document.

| Property | Type | Default | Description | |----------|------|---------|-------------| | mode | RedactionMode | .fullResult | The mode of redaction applied to the document. | | fields | [FieldType] | — | The specific fields to redact. | | documentNumberRedactionSettings | DocumentNumberRedactionSettings? | nil | Partial redaction of the document number. See DocumentNumberRedactionSettings. | | redactMrz | Bool | false | If true, the entire MRZ result is redacted. | | redactBarcode | Bool | false | If true, the entire barcode result is redacted. |

let redaction = RedactionSettings(
    mode: .fullResult,
    fields: [.additionalAddressInformation, .additionalPersonalIdNumber],
    documentNumberRedactionSettings: DocumentNumberRedactionSettings(
        prefixDigitsVisible: 0,
        suffixDigitsVisible: 4
    ),
    redactMrz: true,
    redactBarcode: false
)

##### getDefaultRedactionSettings(for:)

Returns the SDK's built-in default RedactionSettings for a given document class, or nil if none apply. Use it as a starting point when you want to tweak — rather than fully replace — the defaults for a document class.

static func getDefaultRedactionSettings(for classInfo: DocumentClassInfo) -> RedactionSettings?

DocumentNumberRedactionSettings

Controls partial redaction of the document number, keeping a chosen number of digits visible at each end.

| Property | Type | Default | Description | |----------|------|---------|-------------| | prefixDigitsVisible | UInt8 | 0 | How many digits at the start of the document number remain visible after redaction. | | suffixDigitsVisible | UInt8 | 0 | How many digits at the end of the document number remain visible after redaction. |

// Keep the last 4 digits visible, redact the rest
let docNumber = DocumentNumberRedactionSettings(prefixDigitsVisible: 0, suffixDigitsVisible: 4)

RedactionSettingsResolver

A Sendable protocol for supplying per-document redaction behavior. The SDK invokes the resolver immediately before the scanning result is finalized, passing the detected DocumentClassInfo. Return custom RedactionSettings, or nil to fall back to the SDK's defaults for that document class.

public protocol RedactionSettingsResolver: Sendable {
    func resolveRedactionSettings(classInfo: DocumentClassInfo) -> RedactionSettings?
}

A common pattern is to start from the SDK defaults and adjust only specific fields:

struct MyResolver: RedactionSettingsResolver {
    func resolveRedactionSettings(classInfo: DocumentClassInfo) -> RedactionSettings? {
        switch (classInfo.documentType, classInfo.country) {
        case (.alienId, .malaysia):
            var defaults = RedactionSettings.getDefaultRedactionSettings(for: classInfo)
            defaults?.fields = [.additionalAddressInformation, .additionalPersonalIdNumber]
            return defaults
        default:
            return nil // use SDK defaults
        }
    }
}

Note: Returning nil applies the SDK defaults automatically — you only need getDefaultRedactionSettings(for:) when you want to modify the defaults, not accept them as-is. Because the resolver may be invoked from any actor or task context in the scanning pipeline, conforming types must be Sendable.

RedactionMode, FieldType, AlphabetType, and DocumentClassInfo are defined elsewhere in the SDK; refer to the API reference for their full set of cases.

ProcessResult

• inputImageAnalysisResult: InputImageAnalysisResult - Detailed analysis of the processed frame (detection, quality, document classification).
• resultCompleteness: ResultCompleteness - Describes how much of the document's data has been extracted so far.

Key Features

##### InputImageAnalysisResult Contains detailed analysis results for a single frame in the verification process, including processing status, document detection and classification, image quality checks (blur, glare, lighting, moiré, hand occlusion), and the lists of missing, extracted, invalid, and extra fields.

Notable fields include:

• processingStatus: ProcessingStatus - Overall processing status for the frame
• documentDetectionStatus: DetectionStatus - The status of document detection
• documentLocation: Quadrilateral? - The location of the detected document within the image, or nil if not available
• documentOrientation: DocumentOrientation - The orientation of the detected document
• documentRotation: DocumentRotation - The rotation of the detected document
• documentClassInfo: DocumentClassInfo - Information about the document class (country, region, type)

• failed: Detection has failed
• success: Document has been detected
• cameraTooFar: Document has been detected but the camera is too far from the document
• cameraTooClose: Document has been detected but the camera is too close to the document
• cameraAngleTooSteep: Document has been detected but the camera's angle is too steep
• documentTooCloseToCameraEdge: Document has been detected but the document is too close to the camera edge
• documentPartiallyVisible: Only part of the document is visible

• scanningSideInProgress: A document side is currently being scanned
• scanningBarcodeInProgress: The barcode is currently being scanned
• sideScanned: A document side has been scanned
• documentScanned: The entire document has been scanned
• cancelled: Scanning was cancelled

• viz: [VizCompleteness?]? - Completeness of VIZ extraction for one or more VIZ models
• mrz: MrzCompleteness? - Completeness of MRZ extraction
• barcode: BarcodeCompleteness? - Completeness of barcode extraction
• faceImage: ImageCompleteness? - Completeness of face image extraction
• signatureImage: ImageCompleteness? - Completeness of signature image extraction
• barcodeImage: ImageCompleteness? - Completeness of barcode image extraction
• documentImages: [ImageCompleteness]? - Completeness of document image extraction (one or more pages/sides)

Represents a 2D point in the coordinate system.

• x: Int32 - X-coordinate
• y: Int32 - Y-coordinate

Represents a four-sided polygon defined by its corner points.

• upperLeft: Point
• upperRight: Point
• lowerRight: Point
• lowerLeft: Point

Usage Example

if result.processResult?.inputImageAnalysisResult.processingStatus == .success {
    Task { @ProcessingActor in
        let sessionResult = session.getResult()
        // Finish scanning
    }
}

Integration Considerations

1. Error Handling

1. Quality Control

1. Progress Tracking

All types conform to the Sendable protocol, ensuring thread-safe operations in concurrent environments.

##### Best practices

1. Always check session.getScanningStatus() == .documentScanned before concluding the scanning process
2. Implement proper error handling for all possible DetectionStatus cases
3. Monitor quality indicators (blur, glare, moire) for optimal capture conditions
4. Implement appropriate user feedback based on processingStatus and documentDetectionStatus

InputImage

InputImage is a Swift class that wraps either a UIImage or camera frame for processing in the document scanning system.

Initialization

// Create from UIImage
public init(uiImage: UIImage, regionOfInterest: RegionOfInterest = RegionOfInterest())
// Create from camera frame
public init(cameraFrame: CameraFrame)

Key Features

##### RegionOfInterest

A structure that defines the area of interest within an image for processing.

• x: Float - X-coordinate (normalized between 0 and 1)
• y: Float - Y-coordinate (normalized between 0 and 1)
• width: Float - Width (normalized between 0 and 1)
• height: Float - Height (normalized between 0 and 1)

An enumeration representing the device orientation during frame capture.

• portrait: Device in normal upright position
• portraitUpsideDown: Device held upside down
• landscapeRight: Device rotated 90 degrees clockwise
• landscapeLeft: Device rotated 90 degrees counterclockwise

A structure representing a complete camera frame with its metadata.

• buffer: CMSampleBuffer - Raw camera buffer containing image data
• roi: RegionOfInterest - Region of interest within the frame
• orientation: CameraFrameVideoOrientation - Camera orientation
• width: Int - Frame width in pixels (computed property)
• height: Int - Frame height in pixels (computed property)

public init(
    buffer: CMSampleBuffer, 
    roi: RegionOfInterest = RegionOfInterest(), 
    orientation: CameraFrameVideoOrientation = .portrait
)

func processCameraOutput(_ sampleBuffer: CMSampleBuffer) {
    let frame = CameraFrame(
        buffer: sampleBuffer,
        roi: RegionOfInterest(x: 0, y: 0, width: 1.0, height: 1.0),
        orientation: .portrait
    )
let inputImage = InputImage(cameraFrame: frame)
}

Usage Example

// Creating from UIImage
let inputImage1 = InputImage(
    uiImage: documentImage,
    regionOfInterest: RegionOfInterest(x: 0, y: 0, width: 1.0, height: 1.0)
)
// Creating from camera frame
let inputImage2 = InputImage(cameraFrame: cameraFrame)

Integration Considerations

1. Image Source Handling

1. Region of Interest

1. Performance Optimization

• InputImage and related types conform to the Sendable protocol
• CameraFrame is marked as @unchecked Sendable due to buffer handling
• Care should be taken when sharing frames across threads

1. Memory Management

1. Error Handling

1. Performance

SDK Settings

BlinkIDSdkSettings is the top-level configuration passed to BlinkIDSdk.createBlinkIDSdk(withSettings:). It conforms to two protocols:

• SdkSettings — licensing plus base resource configuration (resourcesConfiguration).
• OtaSdkSettings — over-the-air resource configuration (otaResourcesConfiguration).

let settings = BlinkIDSdkSettings(
    licenseKey: "your-license-key",
    licensee: nil,
    helloLogEnabled: false,
    resourcesConfiguration: ResourcesConfig(),
    otaResourcesConfiguration: OTAResourcesConfig(),
    microblinkProxyURL: nil
)

Migration from earlier versions: resource options used to be set as flat arguments directly on BlinkIDSdkSettings. They now live inside ResourcesConfig:

> | Old (flat argument) | New (ResourcesConfig) |

|---------------------|-------------------------|

| downloadResources | resourcesConfiguration.download |

| resourceLocalFolder | resourcesConfiguration.localFolder |

| bundleURL | resourcesConfiguration.bundleUrl |

>

> // Before

> Over-the-air resources are new in this release; see OTA resources.

Resource Management

The SDK supports both downloaded and bundled resources:

• Automatic resource downloading and caching
• Bundle-based resource loading
• Resource validation and verification
• Over-the-air (OTA) resource updates

Configuring resources

Resource behavior is configured through two objects on BlinkIDSdkSettings:

• resourcesConfiguration — a ResourcesConfig for the base machine-learning resources.
• otaResourcesConfiguration — an OTAResourcesConfig for over-the-air resource updates.

| Property | Type | Default | Description | |----------|------|---------|-------------| | download | Bool | true | Whether resources required for on-device image processing are downloaded and cached on first initialization. If false, you must package the required resources in your app's assets. | | serviceUrl | String | https://models.cdn.microblink.com/resources | Host URL for downloaded resources. | | localFolder | String | MLModels | Name of the subfolder within your app's cache folder where resources are cached. | | requestTimeout | RequestTimeout | .default | Timeout settings for resource downloads. | | bundleUrl | URL? | nil | When downloading is disabled, the bundle where the resources reside. |

let resources = ResourcesConfig(
    download: true,
    serviceUrl: "https://models.cdn.microblink.com/resources",
    localFolder: "MLModels"
)

Downloading models

The SDK supports downloading machine learning models from our CDN. Models are automatically retrieved from https://models.cdn.microblink.com/resources when enabled.

To enable model downloads, set download to true in your ResourcesConfig:

let settings = BlinkIDSdkSettings(
    licenseKey: yourLicenseKey,
    resourcesConfiguration: ResourcesConfig(download: true) // Enable model downloads
)

By default, downloaded models are stored in the MLModels folder. You can specify a custom storage location using the localFolder property of ResourcesConfig:

let settings = BlinkIDSdkSettings(
    licenseKey: yourLicenseKey,
    resourcesConfiguration: ResourcesConfig(
        download: true,
        localFolder: "MyModels"
    )
)

Model downloads occur during SDK initialization in the createBlinkIDSdk method:

do {
    let instance = try await BlinkIDSdk.createBlinkIDSdk(withSettings: settings)
} catch let error as ResourceDownloaderError {
    // Handle specific download errors
    if case .noInternetConnection = error {
        // Handle no internet connection
    }
    // Handle other download errors as needed
}

The operation may throw a ResourceDownloaderError with the following possible cases:

| Error Case | Description | |------------|-------------| | invalidURL(String) | The provided URL for model download is invalid | | downloadFailed(Int) | Download failed with specific HTTP status code | | fileNotFound(URL) | Resource file not found at specified location | | hashMismatch(String) | File hash verification failed | | fileAccessError(Error) | Error accessing file system | | cacheDirNotFound | Cache directory not found | | fileCreationError(Error) | Error creating file | | noInternetConnection | No internet connection available | | invalidResponse | Invalid or unexpected server response | | resourceUnavailable | Requested resource is not available |

The SDK provides built-in components for handling network connectivity states. NetworkMonitor is ready-to-use network connectivity monitor that uses NWPathMonitor:

@MainActor
public class NetworkMonitor: ObservableObject {
    @Published public var isConnected = true
    public var isOffline: Bool { !isConnected }
    
    public init() {
        setupMonitor()
    }
}

NoInternetView is a pre-built SwiftUI view for handling offline states:

public struct NoInternetView: View {
    public init(retryAction: @escaping () -> Void)
}

Bundling models

To use bundled models with our SDK, ensure the required model files are included in your app package and set the download property of ResourcesConfig to false. Specify the location of the bundled models using the bundleUrl property of ResourcesConfig. If you are using the main bundle, you can retrieve its URL as follows:

let bundle = Bundle.main.bundleURL
let settings = BlinkIDSdkSettings(
    licenseKey: yourLicenseKey,
    resourcesConfiguration: ResourcesConfig(
        download: false,
        bundleUrl: bundle
    )
)

Over-the-Air (OTA) resources

In addition to the base resources, the SDK can keep its machine-learning resources up to date over the air (OTA). OTA resources are managed separately from the base resources: they are downloaded from a dedicated host and cached in their own folder, and their update behavior is controlled independently through OTAResourcesConfig on BlinkIDSdkSettings.otaResourcesConfiguration.

OTA is enabled by default — the default OTAResourcesConfig checks for updates on initialization and falls back gracefully if an update can't be downloaded.

OTAResourcesConfig

| Property | Type | Default | Description | |----------|------|---------|-------------| | checkForUpdates | Bool | true | When true, the SDK checks for and downloads updated OTA resources on init. When false, cached resources are reused as-is with no update check — except on first run, when resources are missing locally and are downloaded regardless. | | strict | Bool | false | Controls how a failed OTA download is handled during init. When true, initialization throws if the OTA update fails to download. When false, initialization continues silently and falls back to the currently bundled/cached version. | | serviceUrl | String | https://blinkid-ota.microblink.com | Host URL for OTA resources. | | localFolder | String | OTAMLModels | Name of the subfolder within your app's cache folder where OTA resources are cached. | | requestTimeout | RequestTimeout | .default | Timeout settings for resource downloads. | | bundleUrl | URL? | nil | When downloading is disabled, the bundle where the OTA resources reside. |

Default configuration (equivalent to passing no otaResourcesConfiguration):

let settings = BlinkIDSdkSettings(
    licenseKey: yourLicenseKey,
    otaResourcesConfiguration: OTAResourcesConfig() // checkForUpdates: true, strict: false
)

Fail hard if an OTA update can't be fetched, instead of silently falling back:

let settings = BlinkIDSdkSettings(
    licenseKey: yourLicenseKey,
    otaResourcesConfiguration: OTAResourcesConfig(
        checkForUpdates: true,
        strict: true
    )
)

Reuse cached OTA resources without checking for updates (after first run):

let settings = BlinkIDSdkSettings(
    licenseKey: yourLicenseKey,
    otaResourcesConfiguration: OTAResourcesConfig(checkForUpdates: false)
)

Notes

- First-run downloads are unavoidable. checkForUpdates: false only suppresses update checks; if OTA resources are missing locally they are still downloaded on first run.

- strict: true changes initialization into a throwing failure path. Make sure your createBlinkIDSdk error handling accounts for a failed OTA download when you enable it.

- Base and OTA resources use different hosts and cache folders. Base resources default to https://models.cdn.microblink.com/resources in MLModels; OTA resources default to https://blinkid-ota.microblink.com in OTAMLModels. Keep them separate to avoid collisions.

Clearing cached resources

The SDK provides two ways to remove cached resources from the device — for example on logout, on "delete my data" flows, when freeing storage, or to force a fresh download on the next initialization. Both clear the base and OTA caches and reset the SDK's internal OTA-managed state, and both silently ignore deletion errors so cleanup is never interrupted.

deleteCachedResources(resourcesLocalFolder:otaResourcesLocalFolder:)

A static utility that deletes the cached resource folders. It does not require a running SDK instance and does not terminate the SDK — it only removes files.

// Using the default folder names (MLModels + OTAMLModels)
BlinkIDSdk.deleteCachedResources()
// If you configured custom localFolder names, pass the same names here
BlinkIDSdk.deleteCachedResources(
    resourcesLocalFolder: "MyModels",
    otaResourcesLocalFolder: "MyOTAModels"
)

Because this method locates folders b

... (README truncated for length)