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

Document Detector

Instale e configure o Document Detector para iOS com Certta e CafSDK. Aprenda sobre requisitos, configuração de sessão, fluxo de captura de documentos, configuração da UI, delegates, temas e suporte.

Este guia abrange a versão 7.0.0 e superiores. Para versões anteriores à 7.0.0, consulte a documentação legada.

Visão geral

Detector de Documentos para iOS orienta o usuário durante a captura e validação de documentos de identidade (RG, CNH, passaporte etc.). Com Certta, você o executa na mesma sessão que Face Liveness e Smart Capture: configure as credenciais uma vez e, em seguida, abra o fluxo nativo com CerttaDocumentDetector.

Este guia aborda pré-requisitos, Certta requisitos da sessão, CerttaDocumentDetectorConfiguration (incluindo CerttaDocumentDetectorUIConfiguration), abrir / loadSession, resultados em CerttaDocumentDetectorDelegate, cancelamento e logs em CerttaDelegate, e personalização de tema.

Guia de InstalaçãoPersonalizando o Document Detector

Mapeamento de eventos e resultados

CerttaDocumentDetectorDelegate é intencionalmente pequeno: sucesso e erros bloqueadores apenas.

Callback
Finalidade

didFinish(result:)

Fim bem-sucedido do fluxo. resultado é o payload assinado / string JWT do CAF (trate como confidencial).

didFinishWith(_ error: CerttaError)

Sessão inválida, problemas de câmera/rede/segurança/inicialização e falhas no processamento do pipeline unificado (veja abaixo).

O que mudou para CerttaDelegate

  • Cancelamento do usuário → certtaDidCancel() em Certta.shared.delegate (não em CerttaDocumentDetectorDelegate).

  • Logs do pipeline (níveis/mensagens) → certtaDidLog(level:message:) em CerttaDelegate.

  • .loading / .loaded do pipeline unificado são não encaminhados para CerttaDocumentDetectorDelegate (use loadSession apenas para aquecimento).

Falhas de processamento (CafUnifiedEvent.failure)

  • Não há nenhum separado didFail(_: CerttaDocumentDetectorFailure) em CerttaDocumentDetectorDelegate.

  • As falhas são registradas pelo SDK e expostas em didFinishWith como CerttaError.unknownError(String), onde a string inclui contexto de resultado/causa quando disponível.

Migração de amostras antigas

  • Substitua didFinish(signedResponse:) por didFinish(result:) (mesma semântica de string).

  • Implemente CerttaDelegate se você antes tratava cancelamento ou logs no delegate do Document Detector.


Pré-requisitos

  1. SDK CAF instalado — guia de instalação (Swift Package Manager ou CocoaPods).

  2. DocumentDetector vinculado com CafSDK, conforme sua distribuição (SPM / CocoaPods / XCFramework).

  3. Info.plist — uso da câmera (obrigatório):

  1. Biblioteca de fotos — adicione NSPhotoLibraryUsageDescription somente se seu produto permitir que os usuários escolham imagens da biblioteca.

  2. Sessão ativa do Certta — chame Certta.shared.configure(configuration:) para que token móvel e ID do usuário estejam não vazios antes abrir. Sessão ou credenciais ausentes exibem CerttaError (normalmente initializationError) por meio de didFinishWith.


Iniciar Document Detector

Use CerttaDocumentDetector.shared. Defina delegate, ou para que o UIViewController a CerttaDocumentDetectorDelegate apresentador — ordem de resolução: delegate ?? (presenter as? CerttaDocumentDetectorDelegate).

Configuração mínima (inicializador no estilo legado)

Apenas fluxo é necessário para uma sessão real. Os outros parâmetros usam os padrões em init(flow:layout:uploadSettings:instructionsConfig:requestTimeout:showPreCapturePopup:showPreview:ddCustomizations:enableMultiLanguage:selectDocumentConfig:maxRetryAttempts:captureType:). A captura é manual por padrão; para ativar a captura automática, veja DocumentDetectorCaptureType.

Evite publicar CerttaDocumentDetectorConfiguration(flow: []) com um fluxo vazio.

Recomendado: CerttaDocumentDetectorUIConfiguration

Use CerttaDocumentDetectorConfiguration.init(flow:ui:enableMultiLanguage:captureType:). fluxo permanece em CerttaDocumentDetectorConfiguration. Copiar, estilo de captura (captureScreen), upload, timeouts, preview, popup, tentativas e [CafDDCustomization] vivem em CerttaDocumentDetectorUIConfiguration, alinhados com o DocumentDetectorUiConfiguration. Internamente, isso mapeia para CafDocumentDetectorLayout, relacionados à captura CafInstructionsConfiguration, e CafSelectDocumentConfig.

  • ui: CerttaDocumentDetectorUIConfiguration() — padrões do SDK para todos os campos de UI.

  • layoutResourceName — opcional; reservado para futuros hooks de layout nativo, não utilizado pela UI padrão (intenção semelhante ao layoutId).

O inicializador legado init(flow:layout:uploadSettings:instructionsConfig:…) continua disponível se você montar CafDocumentDetectorLayout, CafInstructionsConfiguration, e CafSelectDocumentConfig você mesmo.

Você também pode integrar um bundle de UI existente com CerttaDocumentDetectorUIConfiguration.init(layout:instructions:documentTypeSelection:).

loadSession

Chame CerttaDocumentDetector.shared.loadSession(from:configuration:) antes abrir com o mesmo CerttaDocumentDetectorConfiguration para aquecer caches e recursos. .loading / .loaded são não entregues para CerttaDocumentDetectorDelegate.


CerttaDocumentDetectorConfiguration parâmetros

Inicializador
Quando

init(flow:ui:enableMultiLanguage:)

Recomendado — estruturado CerttaDocumentDetectorUIConfiguration.

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

Raw Caf* tipos sem a struct de UI unificada.

init(from: CafDocumentDetectorConfig)

Você já tem uma CafDocumentDetectorConfig completa (por exemplo, migração).

No caminho de UI , timeouts, upload, preview, popup, tentativas e personalizações vêm de CerttaDocumentDetectorUIConfiguration. No caminho legado , sobrescreva os padrões por campo no longo init.

Campo
Notas

fluxo

[CafDocumentDetectorStep] — necessário para uma sessão real.

o layout

Somente legado. Caminho de UI: construído a partir de captureScreen → CafDocumentDetectorLayout.

uploadSettings

Padrões legados vs caminho de UI (CerttaDocumentDetectorUIConfiguration.uploadSettings, upload padrão desativado / alinhado ao Android).

instructionsConfig

Legado. Caminho de UI: de instructionsScreen.

requestTimeout

Legado: TimeInterval. Caminho de UI: Int segundos em CerttaDocumentDetectorUIConfiguration, padrão 60.

showPreCapturePopup / showPopup

Caminho de UI: showPopup, padrão verdadeiro.

showPreview

padrão do caminho de UI verdadeiro (alinhado ao Android); padrão legado falso no init longo.

ddCustomizations

Caminho de UI: customization.ddCustomizations.

enableMultiLanguage

Padrão verdadeiro; pode ser definido em init(flow:ui:enableMultiLanguage:).

selectDocumentConfig

Caminho de UI: derivado de documentSelectionScreen quando títulos/subtítulos/mapas personalizados são definidos.

maxRetryAttempts

Caminho de UI: CerttaDocumentDetectorUIConfiguration.maxRetryAttempts, padrão 2.

Mapeamento do hub e padrões fixos

init(from:) e os inits de UI/legado ainda mapeiam para CafDocumentDetectorConfig por fixos valores para campos que o tipo Certta não expõe:

Campo
Comportamento do hub

proxySettings

nil (não definido via Certta)

getUrlExpireTime

nil

currentStepDoneDelay

1 (segundos)

allowedPassportCountryList

nil

manualCaptureEnabled / manualCaptureTime

Inits de UI/legado: verdadeiro / 0 (.manual) ou 10 (.automatic). init(from:) mantém os valores de origem.

Para full controle (proxy, string de expiração, atraso entre etapas, lista de passaportes, ajuste de captura manual), use CafSDKProvider.Builder por CafDocumentDetectorConfig — veja o a referência de configuração.

Documentos suportados

Documento
Descrição

RG_FRENTE

Lado frontal do documento RG, onde a foto está localizada.

RG_VERSO

Lado de trás do documento RG.

RG_COMPLETO

Documento RG aberto, exibindo juntos os lados frontal e traseiro.

CNH_FRENTE

Lado frontal do documento CNH, onde a foto está localizada.

CNH_VERSO

Lado de trás do documento CNH.

CNH_COMPLETO

Documento CNH aberto, exibindo juntos os lados frontal e traseiro.

CRLV

Documento CRLV.

RNE_FRENTE

Lado frontal do documento RNE ou RNM.

RNE_VERSO

Lado de trás do documento RNE ou RNM.

PASSAPORTE

Documento de passaporte, exibindo a foto e os dados pessoais.

CTPS_FRENTE

Lado frontal do documento CTPS, onde a foto está localizada.

CTPS_VERSO

Lado de trás do documento CTPS.

QUALQUER

Permite o envio de qualquer tipo de documento, incluindo todos os listados acima ou qualquer outro documento não classificado.

Entendendo eventos e resultados do Document Detector


Eventos e resultados

CerttaDocumentDetectorDelegate

CerttaError expõe mensagem e conforma-se a LocalizedError (errorDescription).

  • didFinish(result:) — Não não registre o token completo em produção.

  • didFinishWith — Sessão inválida, permissões, rede, segurança, inicialização e falhas de processamento (como unknownError).

CerttaDelegate (cancelamento e logs)

Defina Certta.shared.delegate quando você precisar de linhas de cancelamento ou log. Os métodos do protocolo têm implementações vazias padrão.


Permissões e UX

  • Solicite a câmera o quanto antes, se possível; caso contrário, espere permissionError via didFinishWith.

  • Use texto claro em instructionsScreen / seleção para que os usuários saibam como alinhar o documento.

  • Em cancelamento, trate certtaDidCancel() com navegação previsível (voltar ou tentar novamente).


Cores e tema

Passe CafColorConfiguration quando você chamar Certta.shared.configure(configuration:), ou atualize a sessão ativa com Certta.shared.setColorConfiguration(_:)", (sem efeito se não houver sessão — chame configurar primeiro). O Document Detector consome a mesma paleta global que outros módulos Certta.

Para claro vs escuro paletas, resolva strings hex de UITraitCollection.current.userInterfaceStyle (ou o tema do seu app) antes de construir CafColorConfiguration.

Exemplo (uma única paleta amigável ao modo escuro usando os verdes padrão do SDK — ajuste para o seu app):


Legado CafSDKProvider

Se você fizer não uso do hub da Certta para Document Detector, integre com CafSDKProvider.Builder e um completo CafDocumentDetectorConfig para proxy, expiração de URL, atrasos, lista de passaportes e captura manual — veja a referência de configuração.


Notas de versão

Veja Changelog / GitHub Releases para versões, mudanças incompatíveis e mínimo Xcode / iOS.


Suporte

Use seu CAF / Certta canal de suporte, FAQ, e repositório para problemas e atualizações.

Atualizado