🆕Começando com o SDK

Conheça o CafSDK

Essa documentação técnica aborda a implementação do CafSDK para iOS, com detalhes sobre a configuração, inicialização, execução dos fluxos de captura e personalizações avançadas.

Atualmente, o CafSDK integra 2 módulos principais: Face Liveness (FL) e Document Detector (DD), executados de forma sequencial com uma interface de configuração unificada.

O que é Face Liveness

É o módulo que valida a autenticidade de um rosto capturado por aplicativo de foto, garantindo que a imagem corresponda à uma pessoa real.

Características técnicas:

• Configuração de URLs para autenticação (authBaseUrl) e verificação de prova de vida (liveness) (livenessBaseUrl).

• Flags para habilitar captura de tela (screen capture) e modo de depuração (debug mode).

• Suporte à múltiplos provedores de autenticação.

O que é Document Detector

É o módulo que permite a captura e o processamento de documentos (Ex.: RG, CPF, Passaporte, etc.).

Características técnicas:

• Configuração de um fluxo de etapas (flow) definidas por DocumentDetectorStep para a captura do documento.

• Parâmetros operacionais, como timeout, flags de captura manual, entre outras configurações.

• Possibilidade de uso da câmera para validações de enquadramento, ou upload de arquivo do documento.

---

Comece a usar o SDK

Adicione a dependência

O CafSDK oferece suporte à integração tanto pelo Swift Package Manager (SPM) quanto pelo CocoaPods, proporcionando flexibilidade para escolher o gerenciador de dependências que melhor se adapta ao seu projeto. Este guia explica as etapas necessárias para adicionar o CafSDK ao seu projeto iOS e fornece detalhes sobre os módulos disponíveis.

Requisitos para adicionar

Para usar os módulos do CafSDK no iOS, certifique-se de que seu projeto aos requisitos mínimos:

Requisito	Versão
iOS Deployment Target	13.0+
Xcode	15.4+
Swift	5.10+

Importante: configure o Info.plist do seu projeto com as permissões necessárias para acesso à câmera e à rede.

• CAF Mobile Token: valid CAF mobileToken

Etapas para adicionar

Pelo Swift Package Manager (SPM)

Etapa 1 - Adicionar a dependência

Abra o arquivo Package.swift do seu projeto e adicione a seguinte dependência. Isso informa ao Swift Package Manager onde localizar o repositório do CafSDK:

dependencies: [
    .package(url: "https://github.com/combateafraude/caf-ios-sdk.git", from: "0.1.1")
]

Etapa 2 - Inclua os produtos desejados

Após adicionar a dependência, inclua os produtos necessários no destino do seu aplicativo. Isso permite que você integre o SDK completo ou selecione apenas módulos específicos, conforme suas necessidades:

.target(
    name: "YourApp",
    dependencies: [
        .product(name: "CafSDK", package: "CafSDK"),            // Full SDK
        .product(name: "DocumentDetector", package: "CafSDK"),    // Only DocumentDetector
        .product(name: "CafFaceLiveness", package: "CafSDK"),       // Only CafFaceLiveness
        .product(name: "IproovProvider", package: "CafSDK"),        // Optional iProov provider
        .product(name: "FaceTec2DProvider", package: "CafSDK")      // Optional FaceTec 2D provider
    ]
)

Informações adicionais

• Modularidade: integre apenas os módulos necessários para manter seu projeto leve.

• Compatibilidade: o SDK é compatível com iOS 13.0+ e foi desenvolvido com Swift 5.10+.

• Gerenciamento de versão: a declaração de dependência de: "0.1.1" garante o uso de uma versão compatível. Sempre verifique o repositório oficial para obter a versão mais recente.

Pelo CocoaPods

Etapa 1 - Atualize seu Podfile

Para integrar o CafSDK usando CocoaPods, abra o Podfile do seu projeto e adicione as seguintes linhas. Isso instruirá o CocoaPods a baixar os artefatos necessários do repositório oficial:

# Full SDK
pod 'CafSDK'

# Only DocumentDetector
pod 'CafSDK/DocumentDetector'

# Only CafFaceLiveness
pod 'CafSDK/CafFaceLiveness'

# Optional iProov provider
pod 'CafSDK/IproovProvider'

# Optional FaceTec 2D provider
pod 'CafSDK/FaceTec2DProvider'

Etapa 2 - Instale as dependências

Após atualizar o seu Podfile, abra um terminal no diretório raiz do seu projeto e execute:

pod install

Esse comando baixa e integra todos os módulos específicos no seu projeto.

Informações adicionais

• Integração seletiva: escolha apenas os módulos necessários para o seu projeto, otimizando o desempenho.

• Gerenciamento automático de dependências: o CocoaPods gerencia automaticamente a resolução de versões e conflitos de dependências.

• Documentação e suporte: para instruções mais detalhadas ou solução de problemas, consulte a documentação do CafSDK.

---

Como inicializar o SDK

Este guia explica como inicializar o CafSDK no iOS. Ele abrange os requisitos, permissões, configuração global, configuração específica de módulos e a inicialização do builder.

Permissões

Para que os módulos do SDK funcionem corretamente, você deve declarar as seguintes permissões no seu Info.plist:

Para Face Liveness:

• Camera Usage Description (NSCameraUsageDescription): explica por que o aplicativo precisa de acesso à câmera para detecção de rostos.

• Network access: nenhuma permissão explícita é necessária, mas certifique-se de que seu aplicativo suporte conexões seguras (HTTPS/WSS).

Para Document Detector:

• Camera Usage Description (NSCameraUsageDescription): necessário para capturar imagens de documentos.

• Photo Library Usage Description (NSPhotoLibraryUsageDescription): necessário se o seu aplicativo suportar o envio de imagens da biblioteca (opcional).

---

Configurações

O processo de inicialização é dividido em 2 partes: configuração global e configuração específica dos módulos.

Configuração global

Crie um objeto CafSDKConfiguration, que serve como o contêiner central para todas as configurações. Essa configuração define a ordem de execução dos módulos e a identidade visual (por meio de uma configuração de cores).

Exemplo de código:

let sdkConfig = CafSDKConfiguration(
    presentationOrder: [.faceLiveness, .documentDetector] //Required
)

Configuração específica de módulos

Após as configurações globais, configure cada módulo individualmente para ajustar os parâmetros operacionais, de segurança e visuais.

Configuração do Document Detector

Configure o módulo Document Detector especificando o fluxo de captura e opções como captura manual e confirmações em pop-up.

Exemplo de código:

sdkConfig.setDocumentDetectorConfig(CafDocumentDetectorConfig(
    flow: [DocumentDetectorStep(document: .CNH_FULL)]
))

Consulte: DocumentDetector\

Configuração do Face Liveness

Configure o módulo Face Liveness para validar que o rosto capturado pertence a uma pessoa viva. Defina opções para indicadores de carregamento, endpoints e certificados de segurança.

Exemplo de código:

sdkConfig.setFaceLivenessConfig(CafFaceLivenessConfig())

Consulte: FaceLiveness

---

Inicialização do Builder

A inicialização do Builder é a etapa onde o fluxo de captura do CafSDK é configurado para a execução. Use o CafSdkProvider.Builder para fornecer os parâmetros necessários, incluindo um mobile token, person ID, ambiente e o callback unificado para tratar os eventos.

Exemplo de código:

// Create the SDK configuration with the desired modules and custom settings
var sdkConfig = CafSDKConfiguration(
        presentationOrder: viewModel.presentationOrder
    ).setDocumentDetectorConfig(CafDocumentDetectorConfig(flow: [DocumentDetectorStep(document: .CNH_FRONT)])) // Example required document
        .setFaceLivenessConfig(CafFaceLivenessConfig())

// Build the SDK with required parameters and a callback for events
let builder = CafSDKProvider.Builder(
    self,
    mobileToken: "your mobile token",
    personId: "person id",
    environment: .prod,
    configuration: sdkConfig,
    callback: { [weak self] event in
        self?.handleUnifiedEvent(event)
    }
)
let sdk = builder.build()

// Start the SDK session
sdk.start()

// Example unified event handler
private func handleUnifiedEvent(_ event: CafUnifiedEvent) {
    DispatchQueue.main.async { [weak self] in
        guard let self = self else { return }
        switch event {
        case .loading:
            print("🔄 Loading...")
        case .loaded:
            print("🔄 Loaded")
        case .success(let response):
            print("✅ Success from \(response.moduleName):\n\(response.result)")
        case .error(let message):
            print("❌ Error:\n\(message)")
        case .cancelled:
            print("⚠️ Cancelled")
        case .log(let level, let message):
            print("[\(level)] \(message)")
        }
    }
}

Detalhes do processo

• Configuração global: define o fluxo geral e a aparência usando presentationOrder e CafColorConfiguration.

• Configuração específica de módulo: personaliza os módulos Document Detector e Face Liveness com configurações individuais (Ex.: fluxo de captura, indicador de carregamento, endpoints da API).

• Inicialização com o Builder: o padrão builder reúne todos os parâmetros necessários (mobile token, person ID, ambiente, configuração e callback) para criar e iniciar o SDK.

Seguindo essas etapas, seu projeto iOS será configurado corretamente para usar o CafSDK, garantindo uma integração robusta e eficiente dos módulos de detecção de documentos e verificação de rosto.

---

Concluir uma sessão

Uma sessão completa no CafSDK abrange todo o fluxo, desde a inicialização até a finalização - seja essa finalização uma validação bem-sucedida, um erro ou um cancelamento pelo usuário.

Tratamento de Eventos da Sessão

O callback do builder retorna um conjunto de eventos definidos pela enumeração CafUnifiedEvent. Esses eventos, incluem:

• Loading: indica que o SDK está em processamento.

• Loaded: notifica que todos os módulos estão prontos.

• Success (response: CafUnifiedResponse): retorna o resultado após uma sessão bem-sucedida.

• Error (message: String): fornece uma mensagem de erro caso algo dê errado.

• Cancelled: indica que a sessão foi cancelada pelo usuário.

• Log (level: CafLogLevel, message: String): oferece informações detalhadas de log.

Importante

Uma sessão é considerada concluída quando todos os módulos do fluxo de captura tiverem terminado a sua operação com êxito ou quando o processo for interrompido por um erro ou um cancelamento. Em uma sessão completa:

Execução completa: Cada módulo que termina com sucesso, envia um Success event, incluindo:

• moduleName: identifica o módulo (Ex.: "documentDetector" or "faceLiveness") que concluiu a operação.

• result: Um mapa ([String: Any]) que contém os dados da execução do módulo (tais como imagens captadas ou resultados de validação).

Fluxo interrompido: If an error occurs or the user cancels the process:

• Error: Um CafUnifiedEvent.Error evento é disparado com uma mensagem de erro descritiva, permitindo que você faça a recuperação ou notifique a pessoa usuária.

• Cancelled: Um CafUnifiedEvent.Cancelled evento é ativado, o que permite a você limpar recursos ou apresentar uma mensagem de cancelamento.

Exemplo de tratamento de eventos

Confira um exemplo de como tratar estes eventos em unified callback para iOS:

func handleUnifiedEvent(_ event: CafUnifiedEvent) {
    switch event {
    case .loading:
        // Show a loading indicator
        break
    case .loaded:
        // Update UI to show that modules are ready
        break
    case .success(let response):
        // Process the successful response from the completed module
        print("Module: \(response.moduleName) Result: \(response.result)")
    case .error(let message):
        // Handle error state (display an alert, retry, etc.)
        print("Error: \(message)")
    case .cancelled:
        // Handle cancellation gracefully
        break
    case .log(let level, let message):
        // Log internal messages for debugging purposes
        print("[\(level)] \(message)")
    }
}

Resumo

• Sessão completa: uma sessão é considerada completa quando todos os módulos configurados concluem suas tarefas com sucesso, ou quando ocorre um erro/cancelamento.

• Gerenciamento centralizado: O callback unificado garante que, independentemente do resultado, seu aplicativo será notificado e poderá tomar a ação apropriada.

Essa abordagem garante uma integração robusta com o CafSDK, lidando de forma eficiente com cada estado do fluxo de captura, do início ao fim.

---

Fluxo avançado

Esta seção explica como personalizar e ajustar o fluxo de captura do CafSDK para atender a requisitos específicos de negócios e aprimorar a experiência de usuários no iOS.

Ordem de execução dos módulos

A ordem em qual os módulos são executados, é definida pelo campo presentationOrder do objeto CafSDKConfiguration.

Essa sequência é crucial, pois impacta diretamente a lógica do fluxo. Por exemplo, se o processo exigir que o documento seja capturado antes da validação facial, a ordem deve refletir essa prioridade.

Exemplo de código:

let sdkConfig = CafSDKConfiguration(
    presentationOrder: [.documentDetector, .faceLiveness],
    colorConfig: CafColorConfiguration(
        primaryColor: "#FF0000",
        secondaryColor: "#FFFFFF",
        contentColor: "#FF0000",
        backgroundColor: "FFFFFFF",
        mediumColor: "00FF00"
    )
)

Configuração específica de módulos

Personalize módulos individuais usando os métodos setDocumentDetectorConfig e setFaceLivenessConfig. Esses métodos permitem ajustar parâmetros essenciais, como:

• Tempo limite de captura: define o tempo máximo para a captura manual.

• Tempo limite de requisição: estabelece o tempo máximo de espera por uma resposta do serviço.

• Flags de depuração: ativam ou desativam modos de depuração para identificar problemas durante o desenvolvimento.

• Layout e outras configurações: ajustam parâmetros visuais e operacionais específicos de cada módulo.

Personalização visual

Com o objeto CafColorConfiguration, é possível alinhar a identidade visual do fluxo de captura com o design do seu aplicativo. Isso garante que elementos visuais (botões, fundos e indicadores) sejam consistentes com a identidade da sua marca.

Registro de logs e monitoramento

O callback unificado implementa diferentes níveis de log (DEBUG, USAGE, INFO), permitindo o monitoramento detalhado de cada etapa do fluxo. Esses logs são essenciais para integração com ferramentas de monitoramento, ajustes de desempenho e identificação de problemas em tempo real.

Exemplo no callback:

callback = { event in
    switch event {
    case .log(let level, let message):
        // Log messages for detailed monitoring of the flow
        print("[LOG] \(level): \(message)")
    default:
        break
    }
}

Exemplo de encadeamento de configurações:

var sdkConfig = CafSDKConfiguration(
    presentationOrder: [.faceLiveness, .documentDetector],
    colorConfig: CafColorConfiguration(
        primaryColor: "#FF0000",
        secondaryColor: "#FFFFFF",
        contentColor: "#FF0000",
        backgroundColor: "FFFFFFF",
        mediumColor: "00FF00"
    )
)
.setDocumentDetectorConfig(CafDocumentDetectorConfig(
    flow: [DocumentDetectorStep(document: .CNH_FULL)]
))
.setFaceLivenessConfig(CafFaceLivenessConfig())

Consulte: DocumentDetector and FaceLiveness

*Ao encadear essas chamadas de configuração, você pode controlar com precisão o comportamento e a aparência de cada módulo no fluxo unificado.

---

Configurações personalizadas - Face Liveness

O módulo Face Liveness no CafSDK oferece medidas robustas para garantir que o rosto da pessoa usuária seja real e de uma pessoa viva. Ele suporta vários provedores, como iProov e FaceTec2D, permitindo que você escolha ou combine soluções com base em seus requisitos.

Para opções de personalização detalhadas, consulte: FaceLiveness Configurations.

Para configurar o Face Liveness

O objeto de configuração principal é o CafFaceLivenessConfig, que inclui:

• Configuração de instruções: instruções e etapas personalizáveis (via CafInstructionsConfiguration) que orientam a pessoa usuária.

• Indicador de carregamento: uma flag (loadingEnabled) para exibir um indicador de carregamento durante o processamento.

• URLs de Endpoint: especificação do authBaseUrl (HTTPS) e livenessBaseUrl (WSS) para comunicação com a API.

• Certificados: uma lista de certificados para comunicação segura (hashes base64 codificados em SHA-256 SPKI).

Exemplo de configuração:

    sdkConfig.setFaceLivenessConfig(CafFaceLivenessConfig(
    instructionsConfig: CafInstructionsConfiguration(
        enabled: true,
        title: "Scan Your Face",
        descriptionText: "Follow these steps:",
        steps: ["Hold the phone steady", "Ensure good lighting"],
        buttonTitle: "Start Scan",
        headerImage: UIImage(named: "scan_icon")
    ),
    loadingEnabled: true,
    authBaseUrl: "https://my.proxy.io/v1/faces/",
    livenessBaseUrl: "wss://my.proxy.io/ws/",
    certificates: ["4d69f16113bed7d62ca56feb68d32a0fcb7293d3960="]
))

Como funciona

Quando o faceLivenessConfig é definido na sua CafSDKConfiguration, o módulo Face Liveness será executado automaticamente quando a sua posição na ordem de apresentação for atingida.

Após a execução bem-sucedida, um evento CafUnifiedEvent.Success é acionado, contendo:

• moduleName: o identificador do módulo (Ex.: "faceLiveness").

• result: um dicionário ([String: Any]) contendo os dados resultantes da verificação de vivacidade.

Estes resultados podem então ser processados no seu retorno de chamada unificado para atualizar a UI ou prosseguir com o fluxo da sua aplicação.

---

Configurações personalizadas

Resumo da configuração do SDK

The SDK is configured via CafSDKConfiguration, which includes settings for:

• Ordem de fluxo (Ex.: etapas FaceLiveness e DocumentDetector).

• Personalização da UI (cores, instruções e imagens).

• Endpoints de proxy reverso e certificados de segurança.

• Parâmetros opcionais como personId.

Configuração de proxy reverso

Para Face Liveness

Configure o endpoint WebSocket Seguro (WSS) e os certificados para o Face Liveness.

Requisitos:

• Protocolo: wss:// (WebSocket Secure).

• Certificados: Base64-encoded SHA-256 hashes of the certificate's Subject Public Key Info (SPKI).

Configuração:

Todas as configurações de proxy reverso para o Face Liveness são definidas usando a estrutura CafFaceLivenessConfig.

1- Definia a URL base

Use a propriedade livenessBaseUrl para definir o endpoint WSS. Exemplo: "wss://my.proxy.io/ws/"

2 - Defina os certificados

Use a propriedade certificates para fornecer os hashes SPKI. Exemplo: ["4d69f16113bed7d62ca56feb68d32a0fcb7293d3960="]

Exemplo de código:

.setFaceLivenessConfig(CafFaceLivenessConfig(
    livenessBaseUrl: "wss://my.proxy.io/ws/",
    certificates: ["4d69f16113bed7d62ca56feb68d32a0fcb7293d3960=",
        "50f71c5dda30741ee4be1ac378e12539b0d1d511f99=",
        "9f85e26c1ae41f7ac97adc4099be7f2a40759510ab9="]
))

Proxy reverso de autenticação

Configure o endpoint HTTPS para solicitações de autenticação.

• Requisito: protocolo: https://

• Configuração: todas as configurações de proxy reverso para autenticação são definidas usando a estrutura CafFaceLivenessConfig.

1- Defina a URL Base

Use a propriedade authBaseUrl para definir o endpoint HTTPS. Exemplo: "https://my.proxy.io/v1/faces/"

Exemplo de código:

.setFaceLivenessConfig(CafFaceLivenessConfig(
    authBaseUrl: "https://my.proxy.io/v1/faces/"
))

---

Estruturas de configuração

Caf Face Liveness

Configuração para o fluxo Face Liveness.

Property	Type	Description	Default
loadingEnabled	Bool	Enables/disables the loading screen.	true
authBaseUrl	String	HTTPS URL for authentication requests. Required for reverse proxy.	""
livenessBaseUrl	String	WSS URL for FaceLiveness WebSocket. Required for reverse proxy.	""
certificates	[String]	Base64-encoded SHA-256 SPKI hashes. Required for WSS.	[]
instructionsConfig	CafInstructionsConfiguration	Customize instructions screen (title, steps, images).	See below

Instruções de configuração

Personalize a tela de instruções do Face Liveness.

Property	Type	Description	Default
enabled	Bool	Show/hide the instructions screen.	true
title	String?	Header title (e.g., "Face Scan Instructions").	nil
descriptionText	String?	Brief description (e.g., "Follow these steps").	nil
steps	[String]?	Ordered list of instructions (e.g., ["Step 1", "Step 2"]).	nil
buttonTitle	String?	Text for the confirmation button (e.g., "Start Scan").	nil
headerImage	UIImage?	Image displayed at the top of the screen.	nil

Configuração de cores

Personalize a UI.

Property	Type	Description	Format
primaryColor	String	Primary buttons, highlights.	Hex code (e.g., #FF0000)
secondaryColor	String	Secondary elements, borders.	Hex code
contentColor	String	Text and icons.	Hex code
backgroundColor	String	Screen background.	Hex code
mediumColor	String	Neutral elements (e.g., progress bars).	Hex code

Exemplo de códigos

Exemplo de código de configuração completa.

var facelivenessConfig = CafFaceLivenessConfig(
        instructionsConfig: CafInstructionsConfiguration(
            enabled: true,
            title: "Scan Your Face",
            descriptionText: "Follow these steps:",
            steps: ["Hold the phone steady", "Ensure good lighting"],
            buttonTitle: "Start Scan",
            headerImage: UIImage(named: "scan_icon")
        ), loadingEnabled: true,
        authBaseUrl: "https://my.proxy.io/v1/faces/",
        livenessBaseUrl: "wss://my.proxy.io/ws/",
        certificates: ["4d69f16113bed7d62ca56feb68d32a0fcb7293d3960="]
    )

---

Mais informações

Requisitos de certificado

• Os certificados devem ser o base64-encoded SHA-256 hash do certificado Subject Public Key Info (SPKI).

Aplicação de protocolo

• A URL do Face Liveness deve usar wss://.

• A URL de autenticação deve usar https://.

Valores padrão

• loadingEnabled é true por padrão.

• instructionsConfig.enabled é true por padrão.

---

Configurações personalizadas - Document Detector

O módulo DocumentDetector utiliza machine learning (via TensorFlow Lite) para detectar e validar documentos com segurança. Este módulo é altamente configurável, permitindo definir fluxos de documentos personalizados, telas de pré-visualização e configurações de captura manual.

Consulte: DocumentDetector Configurations.

Configuração do Document Detector

O principal objeto de configuração para este módulo é o CafDocumentDetectorConfig, que oferece opções, como:

• Fluxo: um array de objetos DocumentDetectorStep para determinar a ordem e o tipo de capturas de documentos.

• Personalização de layout: defina a aparência da interface de captura usando a classe DocumentDetectorLayout.

• Configurações de upload: controle o formato do arquivo, compressão e tamanho máximo do arquivo com CafUploadSettings.

• Opções de captura manual: ative a captura manual, ajuste o tempo limite e configure detalhes da pré-visualização (como título, subtítulo, confirmação e rótulos de tentativa).

• Configurações de proxy e timeout: configure um proxy e ajuste o tempo limite de rede para uploads seguros de documentos (opcional)

Exemplo de código:

let documentConfig = CafDocumentDetectorConfig(
    flow: [/* Array of DocumentDetectorStep items */],
    layout: DocumentDetectorLayout(),
    uploadSettings: CafUploadSettings(enable: true),
    manualCaptureEnabled: true,
    manualCaptureTime: 45,
    requestTimeout: 60,
    showPopup: true
)

Documentos disponíveis e personalização

O CafSDK fornece um conjunto de documentos pré-configurados (Ex.: RG_FRONT, CNH_FRONT, PASSPORT, etc.). Você pode personalizar esses documentos ou criar seus próprios fluxos ajustando as propriedades de cada DocumentDetectorStep eCafDocument

Como funciona

Quando o documentConfig é definido na sua CafSDKConfiguration, o módulo Document Detector é automaticamente executado quando a sua posição na ordem de apresentação é atingida.

Após uma execução bem-sucedida, é disparado um evento CafUnifiedEvent.Success, que contém:

• result: um dicionário ([String: Any]) com os dados do documento capturado.

• moduleName: o identificador do módulo (Ex.: "documentDetector").

Estes resultados então processados na sua resposta de chamada unificada, permitindo que você avance o fluxo ou armazene as informações capturadas, conforme necessário.

Exemplo de código:

sdkConfig.setDocumentDetectorConfig(CafDocumentDetectorConfig(
    flow: [DocumentDetectorStep(document: .RG_FRONT)],
    manualCaptureEnabled: true,
    manualCaptureTime: 45,
    requestTimeout: 60,
    showPopup: true
))

Após a conclusão da captura e do processamento do documento, o módulo Document Detector dispara um evento CafUnifiedEvent.Success , que contémmoduleName (Ex.: "documentDetector") e um result com o documento capturado.

Configurações personalizadas

Configure o SDK do Document Detector usando a estrutura CafDocumentDetectorConfig , que inclui:

• Etapas do fluxo de captura de documentos.

• Personalização do layout da UI.

• Mensagens de feedback

• Comportamento de upload

• Configurações de proxy

Configurações principais

Propriedades doCafDocumentDetectorConfig .

Property	Type	Description	Default
flow	[DocumentDetectorStep]	Ordered list of document capture steps.	[]
layout	DocumentDetectorLayout	UI customization (colors, buttons, fonts).	Default layout
uploadSettings	CafUploadSettings	Controls document upload behavior.	enable: false
manualCaptureEnabled	Bool	Enables manual capture button.	true
manualCaptureTime	TimeInterval	Timeout (seconds) for manual capture.	45
requestTimeout	TimeInterval	HTTP request timeout.	60
showPopup	Bool	Shows/hides the initial instruction popup.	true
proxySettings	CafProxySettings?	Reverse proxy configuration (host, port, auth).	nil
previewShow	Bool	Enables post-capture preview screen.	false
previewTitle	String?	Title text on preview screen.	nil
previewSubtitle	String?	Subtitle text on preview screen.	nil
previewConfirmLabel	String?	Text for the confirmation button on preview.	nil
previewRetryLabel	String?	Text for the retry button on preview.	nil
messageSettings	CafMessageSettings	Customizable feedback messages.	Default messages
enableMultiLanguage	Bool	Enables auto-translation of default messages.	true
allowedPassportCountryList	[CafCountryCodes]?	Whitelist of allowed passport countries (e.g., .BR, .US).	nil

Personalização de layout

Propriedades do DocumentDetectorLayout .

Property	Type	Description	Default
closeButtonImage	UIImage?	Image for the close button.	System default
closeButtonColor	UIColor?	Color of the close button.	Primary color
closeButtonSize	CGFloat?	Size (width/height) of the close button.	44
closeButtonContentMode	UIView.ContentMode?	Content mode for the close button image.	.scaleAspectFit
uploadBackGroundColor	UIColor	Background color during upload.	Primary color
previewBackGroundColor	UIColor	Background color for preview screen.	.white
primaryColor	UIColor	Color for buttons/progress indicators.	#34D690 (green)
feedbackColors	DocumentFeedbackColors	Colors for feedback overlays (default/error/success).	Predefined colors
font	String?	Custom font name (e.g., "Avenir-Bold").	System font

Exemplo de código:

let layout = DocumentDetectorLayout()
layout.closeButtonImage = UIImage(named: "close_icon")
layout.primaryColor = .blue
layout.font = "Helvetica-Bold"
layout.feedbackColors = DocumentFeedbackColors(
    defaultColor: .gray, 
    errorColor: .red, 
    successColor: .green
)

Personalização de mensagens

Propriedades doCafMessageSettings .

Property	Description	Default Value
waitMessage	Shown during SDK initialization.	"Aguarde" (Waiting)
fitTheDocumentMessage	Advises aligning document to the mask.	"Encaixe o documento na marcação"
verifyingQualityMessage	Shown during quality check.	"Verificando qualidade…"
lowQualityDocumentMessage	Shown on capture failure.	"Ops, tente novamente"
sensorLuminosityMessage	Low brightness warning.	"Ambiente muito escuro"
sensorOrientationMessage	Device orientation warning.	"Celular não está na horizontal"
aiScanDocumentMessage	Prompt to scan a document.	"Escaneie um documento"
aiGetCloserMessage	Prompt to move closer.	"Se aproxime do documento"
aiCapturedMessage	Confirmation of successful capture.	"Capturando o documento"

Full list: 20+ mensagens. Use .set[MessageName](message: String) para personalizar qualquer texto.

Exemplo de código:

let messages = CafMessageSettings()
        .setWaitMessage(message: "Please wait...")
        .setLowQualityDocumentMessage(message: "Poor quality. Retry.")

Fluxo de captura de documento

Propriedades do DocumentDetectorStep.

Property	Type	Description	Required
document	CafDocument	Document type to capture (e.g., .RG_FRONT).	Yes
stepLabel	String?	Text shown at the bottom of the screen.	No
illustration	UIImage?	Image shown in the instruction popup.	No
showStepLabel	Bool	Toggles visibility of the step label.	No (true)

Exemplo de código:

let step = DocumentDetectorStep(
    document: .RG_FRONT,
    stepLabel: "Front of ID",
    illustration: UIImage(named: "id_front_icon")
)

Configurações de upload

Propriedades do CafUploadSettings.

Property	Type	Description	Default
enable	Bool	Enables document upload functionality.	false
compress	Bool	Compresses files before upload.	true
fileFormats	[FileFormat]	Allowed formats: .png, .jpeg, .pdf.	All formats
maximumFileSize	Int	Max file size in KB.	10000 (10MB)

Exemplo de código:

let uploadSettings = CafUploadSettings(
    enable: true,
    fileFormats: [.jpeg, .pdf],
    maximumFileSize: 5000
)

Configurações de Proxy

Propriedades do CafProxySettings.

Property	Type	Description	Required
hostname	String	Proxy host (e.g., "proxy.com").	Yes
port	Int	Proxy port (e.g., 8080).	Yes
user	String?	Authentication username.	No
password	String?	Authentication password.	No

Exemplo de código:

let proxy = CafProxySettings(hostname: "my.proxy.io", port: 443)
    .setAutentication(user: "admin", password: "secret")

Documentos suportados no Document Detector

Use esses valores estáticos de CafDocument:

Document Type	Description
.RG_FRONT	Front of Brazilian ID (RG)
.RG_BACK	Back of Brazilian ID (RG)
.RG_FULL	Brazilian ID (opened, showing front and back)
.CNH_FRONT	Front of Brazilian Driver’s License (CNH)
.CNH_BACK	Back of Brazilian Driver’s License (CNH)
.CNH_FULL	Brazilian Driver’s License (opened)
.CRLV	Brazilian Vehicle Registration (CRLV)
.RNE_FRONT	Front of Brazilian Foreigner ID (RNE)
.RNE_BACK	Back of Brazilian Foreigner ID (RNE)
.CTPS_FRONT	Front of Brazilian Work Card (CTPS)
.CTPS_BACK	Back of Brazilian Work Card (CTPS)
.PASSPORT	Passport (any country)
.ANY	Generic document (no specific validation)

Exemplo de código:

let layout = DocumentDetectorLayout()
layout.primaryColor = .blue
layout.closeButtonImage = UIImage(named: "close")

let config = CafDocumentDetectorConfig(
    flow: [
        DocumentDetectorStep(document: .RG_FRONT),
        DocumentDetectorStep(document: .RG_BACK)
    ],
    layout: layout,
    uploadSettings: CafUploadSettings(enable: true),
    proxySettings: CafProxySettings(hostname: "proxy.example.com", port: 8443),
    messageSettings: CafMessageSettings()
        .setWaitMessage(message: "Initializing...")
        .setLowQualityDocumentMessage(message: "Retry capture")
)

Mais informações

Para mais detalhes e cenários avançados de uso, consulte os seguintes recursos:

• GitHub Repository: acesse o código fonte, rastreamento de problemas e notas de lançamento no repositório do CafSDK GitHub repository.
• Perguntas frequentes e Solução de problemas: verifique nossa seção de FAQs para problemas comuns e dicas de solução de problemas.

• Suporte: para assistência adicional, entre em contato com nossa equipe de suporte ou participe do nosso fórum da comunidade de desenvolvedores.

Estamos atualizando continuamente a documentação à medida que novos recursos e melhorias são lançados. Mantenha seu acesso atualizado para futuras atualizações!