Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Document Detector

Install and configure Document Detector for iOS with Certta and CafSDK. Learn requirements, session setup, document capture flow, UI configuration, delegates, theming, and support.

This guide covers version 7.0.0 and above. For versions below 7.0.0, please see the legacy documentation.

Overview

Document Detector for iOS guides the user through capture and validation of identity documents (RG, CNH, passport, etc.). With Certta, you run it on the same session as Face Liveness and Smart Capture: configure credentials once, then open the native flow with CerttaDocumentDetector.

This guide covers prerequisites, Certta session requirements, CerttaDocumentDetectorConfiguration (including CerttaDocumentDetectorUIConfiguration), open / loadSession, results on CerttaDocumentDetectorDelegate, cancel and logs on CerttaDelegate, and theming.

Installation GuideCustomizing Document Detector

Mapping events and results

CerttaDocumentDetectorDelegate is intentionally small: success and blocking errors only.

Callback
Purpose

didFinish(result:)

Successful end of the flow. result is the signed payload / JWT string from CAF (treat as sensitive).

didFinishWith(_ error: CerttaError)

Session invalid, camera/network/security/initialization issues, and unified pipeline processing failures (see below).

Ensure the JWT response is evaluated on the backend. This process must include validating the token's signature and verifying the isAlive and isMatch fields. Do not perform these validations on the client side.

What moved to CerttaDelegate

  • User cancel → certtaDidCancel() on Certta.shared.delegate (not on CerttaDocumentDetectorDelegate).

  • Pipeline logs (levels/messages) → certtaDidLog(level:message:) on CerttaDelegate.

  • .loading / .loaded from the unified pipeline are not forwarded to CerttaDocumentDetectorDelegate (use loadSession for warm-up only).

Processing failures (CafUnifiedEvent.failure)

  • There is no separate didFail(_: CerttaDocumentDetectorFailure) on CerttaDocumentDetectorDelegate.

  • Failures are logged by the SDK and surfaced to didFinishWith as CerttaError.unknownError(String), where the string includes result/cause context when available.

Migration from older samples

  • Replace didFinish(signedResponse:) with didFinish(result:) (same string semantics).

  • Implement CerttaDelegate if you previously handled cancel or logs on the Document Detector delegate.

Prerequisites

  1. CAF SDK installed — installation guide (Swift Package Manager or CocoaPods).

  2. DocumentDetector linked with CafSDK, per your distribution (SPM / CocoaPods / XCFramework).

  3. Info.plist — camera usage (required):

  1. Photo library — add NSPhotoLibraryUsageDescription only if your product lets users pick images from the library.

  2. Active Certta session — call Certta.shared.configure(configuration:) so mobile token and user ID are non-empty before open. Missing session or credentials surface CerttaError (typically initializationError) via didFinishWith.

Start Document Detector

Use CerttaDocumentDetector.shared. Set delegate, or conform the presenting UIViewController to CerttaDocumentDetectorDelegate — resolution order: delegate ?? (presenter as? CerttaDocumentDetectorDelegate).

Minimal configuration (legacy-style initializer)

Only flow is required for a real session. Other parameters use defaults on init(flow:layout:uploadSettings:instructionsConfig:requestTimeout:showPreCapturePopup:showPreview:ddCustomizations:enableMultiLanguage:selectDocumentConfig:maxRetryAttempts:).

Avoid shipping CerttaDocumentDetectorConfiguration(flow: []) with an empty flow.

Recommended: CerttaDocumentDetectorUIConfiguration

Use CerttaDocumentDetectorConfiguration.init(flow:ui:enableMultiLanguage:). flow stays on CerttaDocumentDetectorConfiguration. Copy, capture styling (captureScreen), upload, timeouts, preview, popup, retries, and [CafDDCustomization] live on CerttaDocumentDetectorUIConfiguration, aligned with Android’s DocumentDetectorUiConfiguration. Internally these map to CafDocumentDetectorLayout, capture-related CafInstructionsConfiguration, and CafSelectDocumentConfig.

  • ui: CerttaDocumentDetectorUIConfiguration() — SDK defaults for all UI fields.

  • layoutResourceName — optional; reserved for future native layout hooks, unused by the default UI (similar intent to Android layoutId).

The legacy initializer init(flow:layout:uploadSettings:instructionsConfig:…) remains available if you assemble CafDocumentDetectorLayout, CafInstructionsConfiguration, and CafSelectDocumentConfig yourself.

You can also bridge an existing UI bundle with CerttaDocumentDetectorUIConfiguration.init(layout:instructions:documentTypeSelection:).

loadSession

Call CerttaDocumentDetector.shared.loadSession(from:configuration:) before open with the same CerttaDocumentDetectorConfiguration to warm caches and resources. .loading / .loaded are not delivered to CerttaDocumentDetectorDelegate.

CerttaDocumentDetectorConfiguration parameters

Initializer
When

init(flow:ui:enableMultiLanguage:)

Recommended — structured CerttaDocumentDetectorUIConfiguration.

init(flow:layout:uploadSettings:instructionsConfig:…)

Raw Caf* types without the unified UI struct.

init(from: CafDocumentDetectorConfig)

You already have a full CafDocumentDetectorConfig (e.g. migration).

On the UI path, timeouts, upload, preview, popup, retries, and customizations come from CerttaDocumentDetectorUIConfiguration. On the legacy path, override per-field defaults on the long init.

Field
Notes

flow

[CafDocumentDetectorStep] — required for a real session.

layout

Legacy only. UI path: built from captureScreen → CafDocumentDetectorLayout.

uploadSettings

Legacy defaults vs UI path (CerttaDocumentDetectorUIConfiguration.uploadSettings, default upload disabled / Android-aligned).

instructionsConfig

Legacy. UI path: from instructionsScreen.

requestTimeout

Legacy: TimeInterval. UI path: Int seconds on CerttaDocumentDetectorUIConfiguration, default 60.

showPreCapturePopup / showPopup

UI path: showPopup, default true.

showPreview

UI path default true (Android-aligned); legacy default false on the long init.

ddCustomizations

UI path: customization.ddCustomizations.

enableMultiLanguage

Default true; can be set on init(flow:ui:enableMultiLanguage:).

selectDocumentConfig

UI path: derived from documentSelectionScreen when titles/subtitles/custom maps are set.

maxRetryAttempts

UI path: CerttaDocumentDetectorUIConfiguration.maxRetryAttempts, default 2.

Hub mapping and fixed defaults

init(from:) and the UI/legacy inits still map to CafDocumentDetectorConfig with fixed values for fields the Certta type does not expose:

Field
Hub behavior

proxySettings

nil (not set via Certta)

getUrlExpireTime

nil

currentStepDoneDelay

1 (seconds)

allowedPassportCountryList

nil

manualCaptureEnabled / manualCaptureTime

true / 0 in the internal mapping

For full control (proxy, expiry string, step delay, passport list, manual capture tuning), use CafSDKProvider.Builder with CafDocumentDetectorConfig — see the configuration reference.

Supported Documents

Document
Description

RG_FRONT

Front side of the RG document, where the photo is located.

RG_BACK

Back side of the RG document.

RG_FULL

Open RG document, displaying both the front and back sides together.

CNH_FRONT

Front side of the CNH document, where the photo is located.

CNH_BACK

Back side of the CNH document.

CNH_FULL

Open CNH document, displaying both the front and back sides together.

CRLV

CRLV document.

RNE_FRONT

Front side of the RNE or RNM document.

RNE_BACK

Back side of the RNE or RNM document.

PASSPORT

Passport document, displaying the photo and personal data.

CTPS_FRONT

Front side of the CTPS document, where the photo is located.

CTPS_BACK

Back side of the CTPS document.

ANY

Allows submission of any type of document, including all those listed above or any other unclassified document.

Understanding Document Detector Events & Results

Events and results

CerttaDocumentDetectorDelegate

CerttaError exposes message and conforms to LocalizedError (errorDescription).

  • didFinish(result:) — Do not log the full token in production.

  • didFinishWith — Invalid session, permissions, network, security, initialization, and processing failures (as unknownError).

CerttaDelegate (cancel & logs)

Set Certta.shared.delegate when you need cancel or log lines. Protocol methods have default empty implementations.

Permissions and UX

  • Request camera early when possible; otherwise expect permissionError via didFinishWith.

  • Use clear copy on instructionsScreen / selection so users know how to align the document.

  • On cancel, handle certtaDidCancel() with predictable navigation (back or retry).

Colors and theming

Pass CafColorConfiguration when you call Certta.shared.configure(configuration:), or update the active session with Certta.shared.setColorConfiguration(_:) (no-op if there is no session — call configure first). Document Detector consumes the same global palette as other Certta modules.

For light vs dark palettes, resolve hex strings from UITraitCollection.current.userInterfaceStyle (or your app theme) before building CafColorConfiguration.

Example (single dark-friendly palette using default SDK greens — adjust for your app):

Legacy CafSDKProvider

If you do not use the Certta hub for Document Detector, integrate with CafSDKProvider.Builder and a full CafDocumentDetectorConfig for proxy, URL expiry, delays, passport list, and manual capture — see configuration reference.

Release notes

See Changelog / GitHub Releases for versions, breaking changes, and minimum Xcode / iOS.

Support

Use your CAF / Certta support channel, FAQ, and repository for issues and updates.

Last updated