🆕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 a 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 a 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 atenda aos requisitos mínimos:

Requisito	Versão
Target de implantação do iOS	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.

• Token Móvel CAF: válido mobileToken CAF

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"),            // SDK completo
        .product(name: "DocumentDetector", package: "CafSDK"),    // Apenas DocumentDetector
        .product(name: "CafFaceLiveness", package: "CafSDK"),       // Apenas CafFaceLiveness
        .product(name: "IproovProvider", package: "CafSDK"),        // Provedor iProov opcional
        .product(name: "FaceTec2DProvider", package: "CafSDK")      // Provedor FaceTec 2D opcional
    ]
)

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:

# SDK completo
pod 'CafSDK'

# Apenas DocumentDetector
pod 'CafSDK/DocumentDetector'

# Apenas CafFaceLiveness
pod 'CafSDK/CafFaceLiveness'

# Provedor iProov opcional
pod 'CafSDK/IproovProvider'

# Provedor FaceTec 2D opcional
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:

• Descrição de uso da câmera (NSCameraUsageDescription): explica por que o aplicativo precisa de acesso à câmera para detecção de rostos.
• Acesso à rede: nenhuma permissão explícita é necessária, mas certifique-se de que seu aplicativo suporte conexões seguras (HTTPS/WSS).

Para Document Detector:

• Descrição de uso da câmera (NSCameraUsageDescription): necessário para capturar imagens de documentos.
• Descrição de uso da biblioteca de fotos (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 Detector de Documentos

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 em que o fluxo de captura do CafSDK é configurado para 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:

// Crie a configuração do SDK com os módulos desejados e configurações personalizadas
var sdkConfig = CafSDKConfiguration(
        presentationOrder: viewModel.presentationOrder
    ).setDocumentDetectorConfig(CafDocumentDetectorConfig(flow: [DocumentDetectorStep(document: .CNH_FRONT)])) // Exemplo de documento obrigatório
        .setFaceLivenessConfig(CafFaceLivenessConfig())

// Construa o SDK com os parâmetros necessários e um callback para eventos
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()

// Inicie a sessão do SDK
sdk.start()

// Exemplo de manipulador de evento unificado
private func handleUnifiedEvent(_ event: CafUnifiedEvent) {
    DispatchQueue.main.async { [weak self] in
        guard let self = self else { return }
        switch event {
        case .loading:
            print("🔄 Carregando...")
        case .loaded:
            print("🔄 Carregado")
        case .success(let response):
            print("✅ Sucesso de \(response.moduleName):\n\(response.result)")
        case .error(let message):
            print("❌ Erro:\n\(message)")
        case .cancelled:
            print("⚠️ Cancelado")
        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:

• Carregando: indica que o SDK está em processamento.
• Carregado: notifica que todos os módulos estão prontos.
• Sucesso (response: CafUnifiedResponse): retorna o resultado após uma sessão bem-sucedida.
• Erro (message: String): fornece uma mensagem de erro caso algo dê errado.
• Cancelado: 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 Sucesso evento, incluindo:

• moduleName: identifica o módulo (Ex.: "documentDetector" ou "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: Se ocorrer um erro ou o usuário cancelar o processo:

• Erro: 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.
• Cancelado: 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:
        // Exibir um indicador de carregamento
        break
    case .loaded:
        // Atualizar a UI para mostrar que os módulos estão prontos
        break
    case .success(let response):
        // Processar a resposta bem-sucedida do módulo concluído
        print("Módulo: \(response.moduleName) Resultado: \(response.result)")
    case .error(let message):
        // Tratar o estado de erro (exibir um alerta, tentar novamente etc.)
        print("Erro: \(message)")
    case .cancelled:
        // Tratar o cancelamento de forma adequada
        break
    case .log(let level, let message):
        // Registrar mensagens internas para fins de depuração
        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 que 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):
        // Registrar mensagens para monitoramento detalhado do fluxo
        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 e 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 detalhadas de personalização, consulte: Configurações de Face Liveness.

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 (por meio de CafInstructionsConfiguration) que orientam a pessoa usuária.
• Indicador de carregamento: um sinalizador (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: "Escaneie seu rosto",
        descriptionText: "Siga estas etapas:",
        steps: ["Segure o telefone firme", "Garanta boa iluminação"],
        buttonTitle: "Iniciar escaneamento",
        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

O SDK é configurado por meio de CafSDKConfiguration, que inclui configurações para:

• 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: hashes SHA-256 codificados em Base64 do Subject Public Key Info (SPKI) do certificado.

Configuração:

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

1 - Defina 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.

Propriedade	Tipo	Descrição	Padrão
loadingEnabled	Bool	Ativa/desativa a tela de carregamento.	true
authBaseUrl	String	URL HTTPS para solicitações de autenticação. Obrigatório para proxy reverso.	""
livenessBaseUrl	String	URL WSS para o WebSocket do Face Liveness. Obrigatório para proxy reverso.	""
certificates	[String]	Hashes SPKI SHA-256 codificados em Base64. Obrigatório para WSS.	[]
a configuração de instruções	CafInstructionsConfiguration	Personalize a tela de instruções (título, etapas, imagens).	Veja abaixo

Instruções de configuração

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

Propriedade	Tipo	Descrição	Padrão
ativado	Bool	Exibir/ocultar a tela de instruções.	true
título	String?	Título do cabeçalho (ex.: "Instruções de Escaneamento Facial").	nil
descriptionText	String?	Breve descrição (ex.: "Siga estas etapas").	nil
steps	[String]?	Lista ordenada de instruções (ex.: ["Etapa 1", "Etapa 2"]).	nil
buttonTitle	String?	Texto do botão de confirmação (ex.: "Iniciar escaneamento").	nil
headerImage	UIImage?	Imagem exibida na parte superior da tela.	nil

Configuração de cores

Personalize a UI.

Propriedade	Tipo	Descrição	Formato
primaryColor	String	Botões principais, destaques.	Código hexadecimal (ex.: #FF0000)
secondaryColor	String	Elementos secundários, bordas.	Código hexadecimal
contentColor	String	Textos e ícones.	Código hexadecimal
cor de fundo	String	Fundo da tela.	Código hexadecimal
mediumColor	String	Elementos neutros (ex.: barras de progresso).	Código hexadecimal

Exemplo de códigos

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

var facelivenessConfig = CafFaceLivenessConfig(
        instructionsConfig: CafInstructionsConfiguration(
            enabled: true,
            title: "Escaneie seu rosto",
            descriptionText: "Siga estas etapas:",
            steps: ["Segure o telefone firme", "Garanta boa iluminação"],
            buttonTitle: "Iniciar escaneamento",
            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 hash SHA-256 codificado em Base64 do Subject Public Key Info (SPKI) do certificado.

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 - Detector de Documentos

O módulo DocumentDetector utiliza machine learning (por meio de 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: Configurações do DocumentDetector.

Configuração do Detector de Documentos

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, a compressão e o 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 de itens DocumentDetectorStep */],
    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 são 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 resultado 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 deCafDocumentDetectorConfig .

Propriedade	Tipo	Descrição	Padrão
o fluxo	[DocumentDetectorStep]	Lista ordenada de etapas de captura de documentos.	[]
o layout	DocumentDetectorLayout	Personalização da UI (cores, botões, fontes).	Layout padrão
as configurações de upload	CafUploadSettings	Controla o comportamento de upload de documentos.	enable: false
manualCaptureEnabled	Bool	Ativa o botão de captura manual.	true
manualCaptureTime	TimeInterval	Tempo limite (em segundos) para captura manual.	45
requestTimeout	TimeInterval	Tempo limite da solicitação HTTP.	60
showPopup	Bool	Mostra/oculta o popup de instrução inicial.	true
proxySettings	CafProxySettings?	Configuração de proxy reverso (host, porta, autenticação).	nil
previewShow	Bool	Ativa a tela de pré-visualização após a captura.	false
previewTitle	String?	Texto do título na tela de pré-visualização.	nil
previewSubtitle	String?	Texto do subtítulo na tela de pré-visualização.	nil
previewConfirmLabel	String?	Texto do botão de confirmação na pré-visualização.	nil
previewRetryLabel	String?	Texto do botão de tentar novamente na pré-visualização.	nil
messageSettings	CafMessageSettings	Mensagens de feedback personalizáveis.	Mensagens padrão
enableMultiLanguage	Bool	Ativa a tradução automática das mensagens padrão.	true
allowedPassportCountryList	[CafCountryCodes]?	Lista de permissões dos países de passaporte permitidos (por exemplo, .BR, .US).	nil

Personalização de layout

Propriedades de DocumentDetectorLayout .

Propriedade	Tipo	Descrição	Padrão
closeButtonImage	UIImage?	Imagem para o botão de fechar.	Padrão do sistema
closeButtonColor	UIColor?	Cor do botão de fechar.	Cor primária
closeButtonSize	CGFloat?	Tamanho (largura/altura) do botão de fechar.	44
closeButtonContentMode	UIView.ContentMode?	Modo de conteúdo para a imagem do botão de fechar.	.scaleAspectFit
uploadBackGroundColor	UIColor	Cor de fundo durante o upload.	Cor primária
previewBackGroundColor	UIColor	Cor de fundo da tela de pré-visualização.	.white
primaryColor	UIColor	Cor dos botões/indicadores de progresso.	#34D690 (verde)
feedbackColors	DocumentFeedbackColors	Cores das sobreposições de feedback (padrão/erro/sucesso).	Cores predefinidas
fonte	String?	Nome da fonte personalizada (ex.: "Avenir-Bold").	Fonte do sistema

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 deCafMessageSettings .

Propriedade	Descrição	Valor Padrão
waitMessage	Exibida durante a inicialização do SDK.	"Aguarde" (aguardando)
fitTheDocumentMessage	Orienta a alinhar o documento com a máscara.	"Encaixe o documento na marcação"
verifyingQualityMessage	Exibida durante a verificação de qualidade.	"Verificando qualidade…"
lowQualityDocumentMessage	Exibida na falha de captura.	"Ops, tente novamente"
sensorLuminosityMessage	Aviso de pouca iluminação.	"Ambiente muito escuro"
sensorOrientationMessage	Aviso de orientação do dispositivo.	"Celular não está na horizontal"
aiScanDocumentMessage	Solicitação para escanear um documento.	"Escaneie um documento"
aiGetCloserMessage	Solicitação para se aproximar.	"Se aproxime do documento"
aiCapturedMessage	Confirmação de captura bem-sucedida.	"Capturando o documento"

Lista completa: mais de 20 mensagens. Use .set[MessageName](message: String) para personalizar qualquer texto.

Exemplo de código:

let messages = CafMessageSettings()
        .setWaitMessage(message: "Aguarde...")
        .setLowQualityDocumentMessage(message: "Qualidade ruim. Tente novamente.")

Fluxo de captura de documento

Propriedades de DocumentDetectorStep.

Propriedade	Tipo	Descrição	Obrigatório
document	CafDocument	Tipo de documento a ser capturado (por exemplo, .RG_FRONT).	Sim
stepLabel	String?	Texto exibido na parte inferior da tela.	Não
illustration	UIImage?	Imagem exibida no popup de instrução.	Não
showStepLabel	Bool	Alterna a visibilidade do rótulo da etapa.	Não (true)

Exemplo de código:

let step = DocumentDetectorStep(
    document: .RG_FRONT,
    stepLabel: "Frente do documento de identidade",
    illustration: UIImage(named: "id_front_icon")
)

Configurações de upload

Propriedades de CafUploadSettings.

Propriedade	Tipo	Descrição	Padrão
ativar	Bool	Ativa a funcionalidade de upload de documentos.	false
comprimir	Bool	Compacta os arquivos antes do upload.	true
fileFormats	[FileFormat]	Formatos permitidos: .png, .jpeg, .pdf.	Todos os formatos
maximumFileSize	Int	Tamanho máximo do arquivo em KB.	10000 (10MB)

Exemplo de código:

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

Configurações de Proxy

Propriedades de CafProxySettings.

Propriedade	Tipo	Descrição	Obrigatório
hostname	String	Host do proxy (ex.: "proxy.com").	Sim
port	Int	Porta do proxy (ex.: 8080).	Sim
user	String?	Nome de usuário de autenticação.	Não
password	String?	Senha de autenticação.	Não

Exemplo de código:

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

Documentos suportados no Detector de Documentos

Use esses valores estáticos de CafDocument:

Tipo de documento	Descrição
.RG_FRONT	Frente do RG brasileiro
.RG_BACK	Verso do RG brasileiro
.RG_FULL	RG brasileiro (aberto, mostrando frente e verso)
.CNH_FRONT	Frente da CNH brasileira
.CNH_BACK	Verso da CNH brasileira
.CNH_FULL	CNH brasileira (aberta)
.CRLV	CRLV brasileiro
.RNE_FRONT	Frente do RNE brasileiro
.RNE_BACK	Verso do RNE brasileiro
.CTPS_FRONT	Frente da CTPS brasileira
.CTPS_BACK	Verso da CTPS brasileira
.PASSPORT	Passaporte (qualquer país)
.ANY	Documento genérico (sem validação específica)

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: "Inicializando...")
        .setLowQualityDocumentMessage(message: "Tente capturar novamente")
)

Mais informações

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

• Repositório no GitHub: acesse o código-fonte, o rastreamento de problemas e as notas de lançamento no repositório do repositório GitHub do CafSDK.
• 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!