References

This page contains references for possible error codes, object structure, etc. In addition to this reference, the SDK has DocC support so you can inspect the objects using tools like Quick Help directly in Xcode.

Document scanner configuration parameters

This section describes the options within DocumentScannerConfig for customizing the document scanning experience.

• autoCaptureToggleConfig: Controls auto-capture UI.
  • .show: Always show auto-capture toggle.
  • .hide: Hide auto-capture toggle.
  • .showDelayed(durationMs: Int): Show toggle after a delay (milliseconds).
  • Has no effect when mrzRequired is true — the toggle is then never shown.
• documentSide: Which side to scan.
  • .front
  • .back
• documentType: Type of document.
  • .unknown
  • .passport
• mrzRequired: Whether auto-capture waits for a complete machine readable zone (MRZ) read. Defaults to false.
  • When true, auto-capture is withheld until the MRZ yields all three of documentNumber, dateOfBirth, and expiryDate — the fields needed to derive a Basic Access Control (BAC) key for NFC chip reads. There is no timeout.
  • When true, a complete MRZ read is enough: auto-capture completes even if image quality checks (blur, glare, resolution) fail. The captured image’s quality flags (isGood, isSharp, isGlareFree, isAdequateResolution) still report the engine’s verdicts, so they may be false on a successful capture. Until the MRZ is read, image quality feedback still guides the user.
  • When true, the auto-capture toggle is never shown and autoCaptureToggleConfig is ignored (including an invalid delay), so the user cannot switch to manual capture. Every capture is an auto-capture that passed the MRZ gate. A user whose document’s MRZ can’t be read leaves the scan with the back button.
  • When false, manual capture (the shutter button) is available as configured by autoCaptureToggleConfig. It does not read the MRZ, so its mrz is always nil.
  • When false (the default), auto-capture is never held back for the MRZ. An MRZ read is still attempted on every auto-capture, so its mrz may be fully populated, partially populated, or nil.

The on-capture feedback is set separately, after initialization, using the configureShutter mutating method (so the config must be declared as var). See the Customization page for a full description of each effect.

• configureShutter(screenFlash:hapticFeedback:sound:): Feedback played when a capture completes.
  • screenFlash: Brief black flash mimicking a camera shutter. Defaults to true.
  • hapticFeedback: Haptic feedback on capture. Defaults to false.
  • sound: Camera shutter sound on capture. Defaults to false.

Example:

import Document

let config = DocumentScannerConfig(
    autoCaptureToggleConfig: .showDelayed(durationMs: 10_000),
    documentSide: .front,
    documentType: .passport
)

Result

This section describes the structure of the results returned by the document scanner SDK, including an example of how to handle the results.

DocumentScannerResult contains:

• result: DocumentProcessingState.Result
  • .success(Success)
    • image: DocumentImage
      • image: Data (PNG)
      • width, height, rotation
      • isGood, isSharp, isGlareFree, isAdequateResolution
    • method: .manualCapture or .smartCapture
    • mrz: MRZData? — the machine readable zone data read during capture, or nil when no MRZ was read.
      • documentNumber, dateOfBirth, expiryDate: String?, in raw MRZ yyMMdd format where present.
  • .failure(Failure)
    • message: Error message
    • component: .smartCapture, .camera, .other
    • cause: Optional error
• metadata: DocumentProcessingMetadata (optional)
  • blurryFrameCount, glareFrameCount, lowResFrameCount, documentBoundaryFrameCount, processedFrameCount
  • captureDuration, lastFrameProcessingDuration
  • hasDisabledAutoCapture

Example result handling:

if let result = sdk.documentScannerResult {
    switch result.result {
    case .success(let success):
        // Access success.image and success.method
        if let mrz = success.mrz,
           let documentNumber = mrz.documentNumber,
           let dateOfBirth = mrz.dateOfBirth,
           let expiryDate = mrz.expiryDate {
            // OzoneNFCDocumentKey expects raw MRZ yyMMdd dates and a
            // `passportNumber` field — Success.mrz already gives both in that
            // shape, just under different property names (documentNumber).
            let documentKey = OzoneNFCDocumentKey(
                passportNumber: documentNumber,
                dateOfBirth: dateOfBirth,
                expiryDate: expiryDate
            )
            // Pass documentKey to OzoneNFCReader / OzoneNFCViewController —
            // see the OzoneNFC component's Quick Setup for the scanning call.
        }
    case .failure(let failure):
        // Access failure.message and failure.component
    }
    if let metadata = result.metadata {
        // Access frame counts and durations
    }
}