Customizing Document Detector

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

Overview

This page is a field-by-field reference for everything integrators can change in Document Detector: copy, capture UI, flow steps, upload behavior, optional proxy, passport filtering, string customizations, and global colors.

---

Customization interface

Assume Certta.shared.configure(configuration:) has already run with a valid mobile token and user ID. Import UIKit and CafSDK (and link DocumentDetector per your distribution).

1. Minimal open — default UI, RG front + back

Uses CerttaDocumentDetectorUIConfiguration() so all UI fields use SDK defaults. Only flow is customized.

import UIKit
import CafSDK

final class DocumentFlowViewController: UIViewController {

    func startDocumentDetector() {
        CerttaDocumentDetector.shared.delegate = self

        let flow: [CafDocumentDetectorStep] = [
            CafDocumentDetectorStep(stepType: .rgFront),
            CafDocumentDetectorStep(stepType: .rgBack)
        ]

        let configuration = CerttaDocumentDetectorConfiguration(
            flow: flow,
            ui: CerttaDocumentDetectorUIConfiguration(),
            enableMultiLanguage: true
        )

        CerttaDocumentDetector.shared.open(from: self, configuration: configuration)
    }
}

extension DocumentFlowViewController: CerttaDocumentDetectorDelegate {
    func didFinish(result: String) {
        // Send `result` to your backend (signed payload).
    }

    func didFinishWith(_ error: CerttaError) {
        // Map `error` / `error.message` to UI (see README).
    }
}

Set Certta.shared.delegate if you need certtaDidCancel() / certtaDidLog.

2. Structured UI — selection, instructions, capture chrome, upload

Build CerttaDocumentDetectorUIConfiguration property by property. This example enables upload, customizes instructions, tightens retries, and adjusts frame colors during capture.

func makeDocumentConfiguration() -> CerttaDocumentDetectorConfiguration {
    var ui = CerttaDocumentDetectorUIConfiguration()

    ui.documentSelectionScreen.title = "Tipo de documento"
    ui.documentSelectionScreen.subtitle = "Escolha o documento que vai fotografar"
    ui.documentSelectionScreen.titlesByDocumentKind = [
        .rg: "RG",
        .cnh: "CNH"
    ]

    ui.instructionsScreen.title = "Como fotografar"
    ui.instructionsScreen.message = "Coloque o documento inteiro dentro da área e evite reflexos."
    ui.instructionsScreen.steps = [
        "Segure o telefone firme",
        "Centralize o documento na moldura"
    ]
    ui.instructionsScreen.primaryButtonTitle = "Continuar"

    ui.captureScreen.documentFrameNeutralColor = .label
    ui.captureScreen.documentFrameValidationFailedColor = .systemRed
    ui.captureScreen.documentFrameValidationPassedColor = .systemGreen
    // ui.captureScreen.fontName = "MyFont-Regular"  // PostScript name, if embedded

    ui.uploadSettings = CafUploadSettings(
        enable: true,
        compress: true,
        fileFormats: [.jpeg, .png],
        maximumFileSize: 5_000_000
    )
    ui.showPreview = true
    ui.showPopup = true
    ui.requestTimeout = 90
    ui.maxRetryAttempts = 4

    let flow = [
        CafDocumentDetectorStep(stepType: .rgFront),
        CafDocumentDetectorStep(stepType: .rgBack)
    ]

    return CerttaDocumentDetectorConfiguration(flow: flow, ui: ui, enableMultiLanguage: true)
}

// Usage:
// CerttaDocumentDetector.shared.open(from: self, configuration: makeDocumentConfiguration())

3. Per-step copy and illustration

Use CafDocumentDetectorStep initializers to override labels, optional UIImage, and messages for a single step.

let flow: [CafDocumentDetectorStep] = [
    CafDocumentDetectorStep(
        stepType: .rgFront,
        customStepLabel: "Frente do RG",
        customIllustration: UIImage(named: "illustration-rg-front"),
        showStepLabel: true,
        customMessage: "Capture a frente nítida, sem cortes.",
        customOkButtonTitle: "OK"
    ),
    CafDocumentDetectorStep(stepType: .rgBack)
]

4. String customizations (CafDDCustomization)

Pass one or more customization structs inside CerttaDocumentDetectorCustomization. They map to native DD custom strings (preview, upload popup, progress lines, failed capture).

var ui = CerttaDocumentDetectorUIConfiguration()

let previewStrings = CafPreviewCustomization(
    title: "Conferir foto",
    message: "O texto está legível?",
    okButton: "Usar esta foto",
    tryAgainButton: "Tirar de novo"
)

let uploadProgress = CafUploadMessagesCustomization(
    sending: "Enviando…",
    verifyingIntegrity: "Verificando…",
    processingData: "Processando…",
    almostDone: "Quase lá…",
    timeBetweenMessages: 1.2
)

let failed = CafFailedPhotoCustomization(
    title: "Foto rejeitada",
    description: "Tente novamente com melhor iluminação.",
    continueButton: "Continuar"
)

ui.customization = CerttaDocumentDetectorCustomization(
    ddCustomizations: [previewStrings, uploadProgress, failed]
)

let configuration = CerttaDocumentDetectorConfiguration(
    flow: [
        CafDocumentDetectorStep(stepType: .cnhFront),
        CafDocumentDetectorStep(stepType: .cnhBack)
    ],
    ui: ui
)

5. Legacy initializer — CafDocumentDetectorLayout + CafInstructionsConfiguration

When you prefer not to use CerttaDocumentDetectorUIConfiguration, assemble layout, instructionsConfig, and uploadSettings yourself.

var layout = CafDocumentDetectorLayout()
layout.setCloseButton(image: UIImage(systemName: "xmark.circle.fill"))
layout.setFeedbackColors(
    CafDocumentFeedbackColors(
        defaultColor: .white,
        errorColor: .systemRed,
        successColor: .systemGreen
    )
)

var instructions = CafInstructionsConfiguration(
    enabled: true,
    captureTitle: "Captura",
    captureDescriptionText: "Alinhe o documento.",
    captureSteps: ["Passo 1", "Passo 2"],
    captureButtonTitle: "Capturar"
)

let configuration = CerttaDocumentDetectorConfiguration(
    flow: [
        CafDocumentDetectorStep(stepType: .passport)
    ],
    layout: layout,
    uploadSettings: CafUploadSettings(enable: true),
    instructionsConfig: instructions,
    requestTimeout: 60,
    showPreCapturePopup: true,
    showPreview: true,
    ddCustomizations: [],
    enableMultiLanguage: true,
    selectDocumentConfig: nil,
    maxRetryAttempts: 3
)

6. Bridge from full CafDocumentDetectorConfig

If you already build CafDocumentDetectorConfig (demo, JSON, or legacy builder), wrap it with init(from:). Fields not stored on CerttaDocumentDetectorConfiguration still receive hub defaults at runtime — see Hub mapping.

let full = CafDocumentDetectorConfig(
    flow: [
        CafDocumentDetectorStep(stepType: .rgFront),
        CafDocumentDetectorStep(stepType: .rgBack)
    ],
    proxySettings: CafProxySettings(hostname: "proxy.example.com", port: 443),
    allowedPassportCountryList: [.bra, .usa]
)

let configuration = CerttaDocumentDetectorConfiguration(from: full)
CerttaDocumentDetector.shared.open(from: self, configuration: configuration)

Note: Proxy and passport list on full are not forwarded through the Certta hub’s internal mapping the same way as CafSDKProvider + CafDocumentDetectorConfig — for guaranteed proxy / allowlist behavior, use CafSDKProvider.Builder with a full CafDocumentDetectorConfig (see below).

7. Full control — CafSDKProvider.Builder + proxy / passport / delays

Use this path when you must set proxy, getUrlExpireTime, currentStepDoneDelay, allowedPassportCountryList, or manual capture fields exactly. Pseudocode:

var config = CafDocumentDetectorConfig(
    flow: [CafDocumentDetectorStep(stepType: .passport)],
    proxySettings: CafProxySettings(hostname: "10.0.0.1", port: 8080),
    getUrlExpireTime: "3600",
    currentStepDoneDelay: 0.5,
    allowedPassportCountryList: [.bra],
    maxRetryAttempts: 5
)

let provider = CafSDKProvider.Builder(
    self,
    mobileToken: token,
    personId: userId,
    environment: .prod,
    configuration: CafSDKConfiguration(
        presentationOrder: [.documentDetector],
        colorConfig: nil,
        waitForAllServices: true,
        enableTransitionScreens: true
    ).setDocumentDetectorConfig(config)
) { event in
    // Handle CafUnifiedEvent (success, failure, error, log, etc.)
}.build()

provider.start()

Exact CafSDKConfiguration and callback handling depend on your app; see configuration reference and product samples.

8. Bridge legacy CafDocumentDetectorLayout + CafInstructionsConfiguration into CerttaDocumentDetectorUIConfiguration

If you already have CafDocumentDetectorLayout and CafInstructionsConfiguration (or CafSelectDocumentConfig) from an older integration, use:

let ui = CerttaDocumentDetectorUIConfiguration(
    layout: existingLayout,
    instructions: existingInstructions,
    documentTypeSelection: existingSelectConfig // or nil
)

let configuration = CerttaDocumentDetectorConfiguration(
    flow: [CafDocumentDetectorStep(stepType: .rgFront)],
    ui: ui
)

Defaults for uploadSettings, showPreview, etc., are set inside that bridge initializer — adjust fields on ui after construction if needed.

9. Session colors before opening DD

// After Certta.shared.configure(...)
Certta.shared.setColorConfiguration(
    CafColorConfiguration(
        primaryColor: "#34D690",
        secondaryColor: "#012D1F",
        contentColor: "#323232",
        backgroundColor: "#FFFFFF",
        mediumColor: "#D1D1D1",
        dialogBackgroundColor: "#FFFFFF",
        dialogBorderColor: "#E5E5E7"
    )
)

Use UITraitCollection (or your theme layer) to build different CafColorConfiguration values for light vs dark if needed.

10. Optional: warm-up with loadSession

let configuration = CerttaDocumentDetectorConfiguration(
    flow: [CafDocumentDetectorStep(stepType: .rgFront)],
    ui: CerttaDocumentDetectorUIConfiguration()
)

CerttaDocumentDetector.shared.loadSession(from: self, configuration: configuration)
// … later, same configuration:
CerttaDocumentDetector.shared.open(from: self, configuration: configuration)

---

CerttaDocumentDetectorUIConfiguration

Root type for structured UI. Defaults below match the Swift initializer in CafSDK.

Property	Type	What it does	Default (typical)
documentSelectionScreen	CafDocumentDetectorDocumentSelectionScreen	Titles/subtitles for the document type picker; per-kind labels. If all empty, selection config may be omitted internally.	See nested section
layoutResourceName	String?	Reserved for future native layout hooks; not used by default UI.	nil
instructionsScreen	CafDocumentDetectorInstructionsScreen	Pre-capture instructions (title, message, steps, button, header image). Maps to capture fields of CafInstructionsConfiguration.	See nested section
captureScreen	CafDocumentDetectorCaptureScreen	During capture: close button, frame colors (neutral / error / success), font name. Maps to CafDocumentDetectorLayout.	See nested section
uploadSettings	CafUploadSettings	Whether uploads run, compression, formats, max size.	enable: false (Certta UI default; aligns with Android)
showPreview	Bool	Show post-capture preview before continuing.	true
requestTimeout	Int	Request timeout in seconds (HTTP).	60
showPopup	Bool	Show pre-capture popup (instruction gate).	true
maxRetryAttempts	Int	Max retries when capture/validation fails.	2
customization	CerttaDocumentDetectorCustomization	Wrapper for [CafDDCustomization] (upload popup copy, preview strings, upload progress messages, failed photo).	Empty customizations

CafDocumentDetectorDocumentSelectionScreen

Property	Type	What it does
title	String?	Main title of the document-type screen.
subtitle	String?	Subtitle / description under the title.
titlesByDocumentKind	[CafDocumentTypeKey: String]?	Override label per logical document group (e.g. .rg, .cnh).
descriptionsByDocumentKind	[CafDocumentTypeKey: String]?	Override secondary text per group.

CafDocumentTypeKey: rg, rgDigital (rg_digital), cnh, cnhDigital (cnh_digital), crlv, rne, ctps, passport, any.

CafDocumentDetectorInstructionsScreen

Property	Type	What it does	Default
enabled	Bool	Turn the instructions step on or off.	true
title	String?	Headline for the instructions view.	nil
message	String?	Body text (e.g. how to scan).	nil
steps	[String]?	Bullet / step lines.	nil
primaryButtonTitle	String?	Primary CTA (e.g. “Continue”).	nil
headerImage	UIImage?	Optional image above the text.	nil

CafDocumentDetectorCaptureScreen

Controls live capture chrome (overlay, close control, frame colors, typography).

Property	Type	What it does	Default
closeButtonImage	UIImage?	Custom close icon.	nil
closeButtonSize	CGFloat?	Tap target / icon size.	nil
closeButtonTintColor	UIColor?	Tint for the close control.	nil
closeButtonContentMode	UIView.ContentMode?	How the image scales.	nil
documentFrameNeutralColor	UIColor	Frame color before validation feedback.	.black
documentFrameValidationFailedColor	UIColor	Frame when validation fails.	#E21B45
documentFrameValidationPassedColor	UIColor	Frame when validation passes.	#0BAA43
fontName	String?	Custom font postscript name for DD copy where applied.	nil

CerttaDocumentDetectorCustomization

Property	Type	What it does
ddCustomizations	[CafDDCustomization]	Array of CafDDUploadCustomization, CafPreviewCustomization, CafUploadMessagesCustomization, CafFailedPhotoCustomization (see DD customizations).

---

CerttaDocumentDetectorConfiguration (parameters)

Used with CerttaDocumentDetector.shared.open(from:configuration:).

Recommended: init(flow:ui:enableMultiLanguage:)

Input	Role
flow	[CafDocumentDetectorStep] — required for a real session (order of captures).
ui	CerttaDocumentDetectorUIConfiguration — all UI described above.
enableMultiLanguage	Propagates to runtime (enableMultiLanguage). Default true.

Legacy: init(flow:layout:uploadSettings:instructionsConfig:requestTimeout:showPreCapturePopup:showPreview:ddCustomizations:enableMultiLanguage:selectDocumentConfig:maxRetryAttempts:)

Parameter	Default	What it does
flow	[]	Capture steps.
layout	CafDocumentDetectorLayout()	See Layout.
uploadSettings	CafUploadSettings(enable: true)	See Upload.
instructionsConfig	CafInstructionsConfiguration()	See Instructions.
requestTimeout	60	Seconds (TimeInterval).
showPreCapturePopup	true	Same role as UI showPopup.
showPreview	false	Post-capture preview (UI path default is often true via CerttaDocumentDetectorUIConfiguration).
ddCustomizations	[]	See DD customizations.
enableMultiLanguage	true	Multi-language bundles / behavior.
selectDocumentConfig	nil	Document picker copy; see Selection.
maxRetryAttempts	2	Retry limit.

init(from: CafDocumentDetectorConfig)

Copies all overlapping fields from a full CafDocumentDetectorConfig. The Certta hub still applies fixed values for fields not on CerttaDocumentDetectorConfiguration when building the runtime config (see README — Hub mapping).

---

CafDocumentDetectorConfig (full model)

Use with CafSDKProvider.Builder when you need every lever. Property list (defaults from CafSDK):

Property	Type	What it does
flow	[CafDocumentDetectorStep]	Ordered steps.
layout	CafDocumentDetectorLayout	Capture UI layout + feedback colors + font.
uploadSettings	CafUploadSettings	Upload pipeline.
instructionsConfig	CafInstructionsConfiguration	Instruction & upload instruction content.
manualCaptureEnabled	Bool?	Allow manual capture path when supported.
manualCaptureTime	TimeInterval	Timing for manual capture.
requestTimeout	TimeInterval	Network timeout (seconds).
showPopup	Bool	Pre-capture instruction popup.
proxySettings	CafProxySettings?	Optional reverse proxy for API traffic.
previewShow	Bool	Post-capture preview screen.
ddCustomizations	[CafDDCustomization]	String / screen customizations.
getUrlExpireTime	String?	Custom image URL expiry handling where applicable.
enableMultiLanguage	Bool	Multi-language.
currentStepDoneDelay	TimeInterval	Delay between steps (seconds).
allowedPassportCountryList	[CafCountryCode]?	Restrict passport issuers (ISO-style codes). nil = no extra filter.
selectDocumentConfig	CafSelectDocumentConfig?	Document selection UI strings.
sdkType	CafSdkPlatform	Platform tag (e.g. .nativeIos).
maxRetryAttempts	Int	Max retries per step.

---

CafDocumentDetectorStep & CafDocumentStepType

Each step is one capture target, optionally overridden for labels and assets.

CafDocumentStepType

Case	Meaning
rgFront / rgBack / rgFull	Brazilian ID (RG) variants.
cnhFront / cnhBack / cnhFull	CNH variants.
crlv	CRLV.
rneFront / rneBack	RNE.
ctpsFront / ctpsBack	CTPS.
passport	Passport.
any	Generic / flexible capture.

CafDocumentDetectorStep fields

Property	Type	What it does
stepType	CafDocumentStepType	Which document surface to capture.
customStepLabel	String?	Override step title in UI.
customIllustration	UIImage?	Custom illustration for this step.
showStepLabel	Bool	Show or hide the step label. Default true.
customMessage	String?	Step-specific instruction message.
customOkButtonTitle	String?	Primary button title for this step.

---

CafDocumentDetectorLayout & feedback colors

CafDocumentDetectorLayout

Property / API	What it does
closeButtonImage, closeButtonSize, closeButtonColor, closeButtonContentMode	Close control; use setCloseButton(size:color:image:contentMode:) to set in one call.
feedbackColors	CafDocumentFeedbackColors — frame line colors; setFeedbackColors(_:).
font	PostScript font name for applicable DD text. setFont(name:).

CafDocumentFeedbackColors

Property	Default	What it does
defaultColor	.black	Neutral frame.
errorColor	#E21B45	Validation failed.
successColor	#0BAA43	Validation passed.

---

CafInstructionsConfiguration

Split into capture and upload instruction content (Document Detector primarily uses capture fields).

Property	Used for DD (capture path)
enabled	Master switch for instructions.
captureTitle, captureDescriptionText, captureSteps, captureButtonTitle, captureHeaderImage	Pre-capture instruction screen.
uploadTitle, uploadDescriptionText, uploadSteps, uploadButtonTitle, uploadHeaderImage	Upload-phase instructions (if your flow shows them).

---

CafSelectDocumentConfig & CafDocumentTypeKey

Property	What it does
screenTitle	Title of document selection.
description	Subtitle / help text.
customTitles	Map CafDocumentTypeKey → String for per-type titles.
customDescriptions	Map CafDocumentTypeKey → String for per-type descriptions.

---

CafUploadSettings & CafFileFormatWrapper

CafUploadSettings

Property	Default	What it does
enable	true (in CafDocumentDetectorConfig init)	Turn upload on/off. Certta UI default is often false via CerttaDocumentDetectorUIConfiguration.
compress	true	Compress before upload.
fileFormats	PNG, JPEG, HEIF, PDF, HEIC	Allowed CafFileFormatWrapper values.
maximumFileSize	10_000_000	Max size in bytes.

CafFileFormatWrapper

png, jpeg, pdf, heif, heic — maps to UTI strings internally.

---

CafProxySettings

Property	What it does
hostname, port	Proxy endpoint (required in init(hostname:port:)).
user, password	Optional auth via setAuthentication(user:password:).

---

CafDDCustomization types

All conform to CafDDCustomization. Pass them inside CerttaDocumentDetectorCustomization.ddCustomizations or CafDocumentDetectorConfig.ddCustomizations. They are applied to the native DocumentDetector builder (setCustomStrings).

CafDDUploadCustomization

Popup around upload confirmation: image, message, uploadButton, cancelButton.

CafPreviewCustomization

Preview screen after capture: title, message, okButton, tryAgainButton.

CafUploadMessagesCustomization

Progress strings during upload: sending, verifyingIntegrity, processingData, almostDone, timeBetweenMessages.

CafFailedPhotoCustomization

Bad capture sheet: title, description, continueButton.

---

Passport allowlist (CafCountryCode)

allowedPassportCountryList: array of CafCountryCode (string-backed ISO-style codes, e.g. bra, usa). Limits which passport issuers are accepted when that validation applies. nil means no list-based restriction.

The enum is large; see CafCountryCode.swift in CafSDK for the full list.

---

Global colors

Document Detector respects CafColorConfiguration supplied via Certta (configure / setColorConfiguration) for shared CAF UI. See Colors and theming.

---