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

Detector de Documentos

Instale e configure o Detector de Documentos para iOS com Certta e CafSDK. Saiba mais sobre requisitos, configuração de sessão, fluxo de captura de documentos, configuração de 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 guia o usuário pela 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 depois abra o fluxo nativo com CerttaDocumentDetector.

Este guia aborda os pré-requisitos, Certta requisitos de 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 Detector de Documentos

Mapeamento de eventos e resultados

CerttaDocumentDetectorDelegate é intencionalmente pequeno: sucesso e erros bloqueantes apenas.

Retorno de chamada
Finalidade

didFinish(result:)

Conclusão bem-sucedida do fluxo. result é a string da carga útil assinada / JWT da CAF (trate como sensível).

didFinishWith(_ error: CerttaError)

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

Garanta que a resposta JWT seja avaliada no backend. Esse processo deve incluir a validação da assinatura do token e a verificação dos estáVivo e éCorrespondente campos. Não realize essas validações no lado do cliente.

O que foi movido 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 registre encaminhadas 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 apresentadas em didFinishWith como CerttaError.unknownError(String), onde a string inclui o contexto do resultado/causa quando disponível.

Migração de exemplos antigos

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

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

Pré-requisitos

  1. SDK da 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 o seu produto permitir que os usuários escolham imagens da biblioteca.

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

Iniciar o Detector de Documentos

Use CerttaDocumentDetector.shared. Defina delegate, ou faça o controlador de apresentação adotar o UIViewController para CerttaDocumentDetectorDelegate — 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 demais parâmetros usam os padrões em init(flow:layout:uploadSettings:instructionsConfig:requestTimeout:showPreCapturePopup:showPreview:ddCustomizations:enableMultiLanguage:selectDocumentConfig:maxRetryAttempts:).

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

Recomendado: CerttaDocumentDetectorUIConfiguration

Use CerttaDocumentDetectorConfiguration.init(flow:ui:enableMultiLanguage:). fluxo permanece em CerttaDocumentDetectorConfiguration. Texto, estilo de captura (captureScreen), upload, timeouts, preview, popup, tentativas e [CafDDCustomization] ficam em CerttaDocumentDetectorUIConfiguration, alinhado com o DocumentDetectorUiConfiguration. Internamente, eles mapeiam para CafDocumentDetectorLayout, relacionados à captura CafInstructionsConfiguration, e CafSelectDocumentConfig.

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

  • layoutResourceName — opcional; reservado para futuros hooks nativos de layout, não utilizado pela UI padrão (intenção semelhante ao Android 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 pacote de UI existente com CerttaDocumentDetectorUIConfiguration.init(layout:instructions:documentTypeSelection:).

loadSession

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

CerttaDocumentDetectorConfiguration parâmetros

Inicializador
Quando

init(flow:ui:enableMultiLanguage:)

Recomendado — estruturado CerttaDocumentDetectorUIConfiguration.

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

Bruto Caf* tipos sem a struct de UI unificada.

init(from: CafDocumentDetectorConfig)

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

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

Campo
Observações

fluxo

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

layout

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

uploadSettings

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

instructionsConfig

Legado. Caminho da UI: a partir de instructionsScreen.

requestTimeout

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

showPreCapturePopup / showPopup

Caminho da UI: showPopup, padrão true.

showPreview

Padrão do caminho da UI true (alinhado com Android); padrão legado false no init longo.

ddCustomizations

Caminho da UI: customization.ddCustomizations.

enableMultiLanguage

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

selectDocumentConfig

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

maxRetryAttempts

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

Mapeamento do Hub e padrões fixos

init(from:) e os inits da 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

true / 0 no mapeamento interno

Para controle total (proxy, string de expiração, atraso da etapa, lista de passaportes, ajustes de captura manual), use CafSDKProvider.Builder por CafDocumentDetectorConfig — veja 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 os eventos e resultados do Document Detector

Eventos e resultados

CerttaDocumentDetectorDelegate

CerttaError expõe message e está em conformidade com LocalizedError (errorDescription).

  • didFinish(result:) — Não registre 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 cancelamento ou linhas de log. Os métodos do protocolo têm implementações vazias padrão.

Permissões e UX

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

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

  • No 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 configure primeiro). O Document Detector consome a mesma paleta global que os 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 tema escuro usando os verdes padrão do SDK — ajuste para o seu app):

Legado CafSDKProvider

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

Notas de versão

Veja Registro de alterações / 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