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.
Mapeamento de eventos e resultados
CerttaDocumentDetectorDelegate é intencionalmente pequeno: sucesso e erros bloqueadores apenas.
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()emCertta.shared.delegate(não emCerttaDocumentDetectorDelegate).Logs do pipeline (nÃveis/mensagens) →
certtaDidLog(level:message:)emCerttaDelegate..loading/.loadeddo pipeline unificado são não encaminhados paraCerttaDocumentDetectorDelegate(useloadSessionapenas para aquecimento).
Falhas de processamento (CafUnifiedEvent.failure)
Não há nenhum separado
didFail(_: CerttaDocumentDetectorFailure)emCerttaDocumentDetectorDelegate.As falhas são registradas pelo SDK e expostas em
didFinishWithcomoCerttaError.unknownError(String), onde a string inclui contexto de resultado/causa quando disponÃvel.
Migração de amostras antigas
Substitua
didFinish(signedResponse:)pordidFinish(result:)(mesma semântica de string).Implemente
CerttaDelegatese você antes tratava cancelamento ou logs no delegate do Document Detector.
Pré-requisitos
SDK CAF instalado — guia de instalação (Swift Package Manager ou CocoaPods).
DocumentDetector vinculado com CafSDK, conforme sua distribuição (SPM / CocoaPods / XCFramework).
Info.plist — uso da câmera (obrigatório):
Biblioteca de fotos — adicione
NSPhotoLibraryUsageDescriptionsomente se seu produto permitir que os usuários escolham imagens da biblioteca.Sessão ativa do Certta — chame
Certta.shared.configure(configuration:)para que token móvel e ID do usuário estejam não vazios antesabrir. Sessão ou credenciais ausentes exibemCerttaError(normalmenteinitializationError) por meio dedidFinishWith.
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 aolayoutId).
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
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.
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:
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
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 (comounknownError).
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
permissionErrorviadidFinishWith.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

