Guia Detalhado de Uso

Guia completo de integração e customização do Certiface Doc SDK para iOS, abordando instalação, configuração, captura de documentos, tratamento de eventos e personalização da experiência do usuário.

Sumário

  1. 📌 Visão geral
  2. ✅ Requisitos de compatibilidade
  3. ⚙️ Instalação
  4. 🚀 Inicialização e execução
  5. 📦 DocumentManagerOptions
  6. 🔔 Callbacks e erros
  7. 🎨 Customização - DocCoreCustomization
  8. 🖼️ Telas completamente próprias - DocCoreCustomViews
  9. 🧪 Ambiente de testes
  10. 🛠️ Boas práticas
  11. 💻 Aplicativo de exemplo

1. 📌 Visão geral

O Certiface Doc SDK oferece documentoscopia (instruções, permissão de câmera, captura frente/verso, QR Code, upload, resultado) em UIKit, com aparência totalmente configurável. O ponto de entrada público é CertifaceDocSDKFactory.


2. ✅ Requisitos de compatibilidade

ItemValor
iOS mínimo13.0
Swift5.0
UI frameworkUIKit
Ambientes.HML, .PRD

3. ⚙️ Instalação

Podfile

source 'https://github.com/oititec/ios-artifactory.git'
source 'https://github.com/CocoaPods/Specs.git'

# platform :ios, '13.0' ou superior
use_frameworks!

target 'SeuApp' do
  pod 'CertifaceDocSDK', 'x.y.z'
end

Execute pod install. Substitua x.y.z pela versão publicada.


4. 🚀 Inicialização e execução

import CertifaceDocSDK

let options = DocumentManagerOptions
    .builder(appKey: appKey, environment: .HML)
    .build()

let manager = CertifaceDocSDKFactory.createDocumentManager()
manager.start(at: self, options: options, callback: self)

O SDK apresenta o fluxo em modo fullScreen sobre o UIViewController passado em at:.


5. 📦 DocumentManagerOptions

Criado com o builder DocumentManagerOptions.builder(appKey:environment:).

ParâmetroTipoPadrãoDescrição
appKeyStringobrigatórioChave da aplicação fornecida pelo backend.
environmentEnvironmentobrigatório.HML (homologação) ou .PRD (produção).
additionalOptionsSet<AdditionalDocumentOption>[].digitalDocument e/ou .uploadDocument.
showFeedbackBooltrueExibe a tela de resultado ao fim do fluxo.
docCoreCustomizationDocCoreCustomizationtema padrãoCustomização granular por região de tela.
docCoreCustomViewsDocCoreCustomViewstelas padrõesSubstituição completa de telas por UIViews.
let options = DocumentManagerOptions
    .builder(appKey: appKey, environment: .HML)
    .setAdditionalOptions([.digitalDocument, .uploadDocument])
    .setShowFeedback(true)
    .setDocCoreCustomization(minhaCustomizacao)
    .setDocCoreCustomViews(minhasCustomViews)
    .build()

6. 🔔 Callbacks e erros

Implemente DocumentCallback em qualquer objeto (UIViewController, ViewModel, etc.):

import CertifaceDocSDK

extension MeuViewController: DocumentCallback {
    func onSuccess() {
        // Documento enviado com sucesso
    }

    func onError(_ error: DocumentError) {
        // Erro na captura ou envio do documento
    }
}

Tabela de erros - DocumentError

Casocodemessage
.invalidAppKey0App Key inválido.
.certifaceOff1Serviço indisponível.
.cameraSetupFailed2Falha ao configurar a câmera.
.noCameraPermission3Não foi concedida permissão de acesso à câmera do aparelho.
.errorCapturePicture4Falha na captura do documento.
.noInternetConnection5Sem conexão à Internet.
.validationError6Não foi possível concluir a validação, tente novamente.
.userCancelled7Jornada cancelada pelo usuário.

7. 🎨 Customização - DocCoreCustomization

A customização é granular: você ajusta apenas as regiões que quiser e o SDK usa os valores padrão para o restante.

let customization = DocCoreCustomization.builder()
    .setInstructionCustomization { $0 /* ... */ }
    .setCameraPermissionCustomization { $0 /* ... */ }
    .setCaptureCustomization { $0 /* ... */ }
    .setQrCodeCustomization { $0 /* ... */ }
    .setUploadCustomization { $0 /* ... */ }
    .setLoadingCustomization { $0 /* ... */ }
    .setResultCustomization { $0 /* ... */ }
    .build()

Passe o resultado em .setDocCoreCustomization(customization) no builder de DocumentManagerOptions.


📝 Instruções

setInstructionCustomization { builder in ... } — tela inicial com as opções de documento.

GrupoMétodos
Botão voltarsetBackButtonIcon
setBackButtonIconColor
setBackButtonBackgroundColor
setBackButtonBorderColor
FundosetBackgroundColor
Imagem de contextosetContextImage
LoadingsetLoadingColor
Bottom sheetsetBottomSheetColor
setBottomSheetCornerRadius
TítulosetTitle
setTitleColor
setTitleFont
LegendasetCaption
setCaptionColor
setCaptionFont
Opção documento físicosetPhysicalDocumentOptionImage
setPhysicalDocumentOptionTitle
setPhysicalDocumentOptionTitleColor
setPhysicalDocumentOptionTitleFont
setPhysicalDocumentOptionDescription
setPhysicalDocumentOptionDescriptionColor
setPhysicalDocumentOptionDescriptionFont
setPhysicalDocumentOptionBackgroundColor
setPhysicalDocumentOptionCircleBackgroundColor
setPhysicalDocumentOptionBorderRadius
setPhysicalDocumentOptionBorderWidth
setPhysicalDocumentOptionBorderColor
setPhysicalDocumentOptionIconColor
Opção CNH digitalsetDigitalDocumentOptionImage
setDigitalDocumentOptionTitle
setDigitalDocumentOptionTitleColor
setDigitalDocumentOptionTitleFont
setDigitalDocumentOptionDescription
setDigitalDocumentOptionDescriptionColor
setDigitalDocumentOptionDescriptionFont
setDigitalDocumentOptionBackgroundColor
setDigitalDocumentOptionCircleBackgroundColor
setDigitalDocumentOptionBorderRadius
setDigitalDocumentOptionBorderWidth
setDigitalDocumentOptionBorderColor
setDigitalDocumentOptionIconColor
Opção upload PDFsetUploadDocumentOptionImage
setUploadDocumentOptionTitle
setUploadDocumentOptionTitleColor
setUploadDocumentOptionTitleFont
setUploadDocumentOptionDescription
setUploadDocumentOptionDescriptionColor
setUploadDocumentOptionDescriptionFont
setUploadDocumentOptionBackgroundColor
setUploadDocumentOptionCircleBackgroundColor
setUploadDocumentOptionBorderRadius
setUploadDocumentOptionBorderWidth
setUploadDocumentOptionBorderColor
setUploadDocumentOptionIconColor
.setInstructionCustomization { builder in
    builder
        .setBackgroundColor(.systemBackground)
        .setTitle("Envio de documentos")
        .setTitleColor(.label)
        .setCaption("Escolha o tipo de documento:")
        .setCaptionColor(.secondaryLabel)
        .setPhysicalDocumentOptionTitle("Documento Físico")
        .setPhysicalDocumentOptionDescription("Use RG, CNH, DNI ou CIN.")
}

📷 Permissão de câmera

setCameraPermissionCustomization { builder in ... }

GrupoMétodos
FundosetBackgroundColor
Botão voltarsetBackButtonIcon
setBackButtonIconColor
setBackButtonBackgroundColor
setBackButtonBorderColor
Ícone câmerasetCameraImage
setCameraImageColor
TítulosetTitle · setTitleColor · setTitleFont
LegendasetCaption
setCaptionColor
setCaptionFont
Botão permissãosetCheckPermissionButtonText
setCheckPermissionButtonTextFont
setCheckPermissionButtonTextColor
setCheckPermissionButtonBackgroundColor
setCheckPermissionButtonBorderColor
Bottom sheetsetBottomSheetColor
setBottomSheetCornerRadius
setBottomSheetTitle
setBottomSheetTitleColor
setBottomSheetTitleFont
setBottomSheetCaption
setBottomSheetCaptionColor
setBottomSheetCaptionFont
Botão configuraçõessetOpenSettingsButtonText
setOpenSettingsButtonTextFont
setOpenSettingsButtonTextColor
setOpenSettingsButtonBackgroundColor
setOpenSettingsButtonBorderColor
Botão fecharsetCloseButtonText
setCloseButtonTextFont
setCloseButtonTextColor
setCloseButtonBackgroundColor
setCloseButtonBorderColor

📸 Captura (frente/verso)

setCaptureCustomization { builder in ... }

GrupoMétodos
Botão voltarsetBackButtonIcon
setBackButtonIconColor
setBackButtonBackgroundColor
setBackButtonBorderColor
Botão fecharsetCloseButtonIcon
setCloseButtonIconColor
setCloseButtonBackgroundColor
setCloseButtonBorderColor
Indicador frentesetFrontIndicatorText
setFrontIndicatorColor
setFrontIndicatorFocusedStateImage
setFrontIndicatorFocusedStateTextColor
setFrontIndicatorFocusedStateTextFont
setFrontIndicatorUnfocusedStateImage
setFrontIndicatorUnfocusedStateTextColor
setFrontIndicatorUnfocusedStateTextFont
Indicador versosetBackIndicatorText
setBackIndicatorColor
setBackIndicatorFocusedStateImage
setBackIndicatorFocusedStateTextColor
setBackIndicatorFocusedStateTextFont
setBackIndicatorUnfocusedStateImage
setBackIndicatorUnfocusedStateTextColor
setBackIndicatorUnfocusedStateTextFont
Texto guiasetInstructionGuideFrontText
setInstructionGuideBackText
setInstructionConfirmationText
setInstructionTextColor setInstructionTextFont
Área de previewsetPreviewCapturedBorderColor
setPreviewUncapturedBorderColor
FundosetBackgroundColor
Botão captura (normal)setCaptureButtonIcon
setCaptureButtonNormalIconColor
setCaptureButtonNormalBackgroundColor
setCaptureButtonNormalBorderColor
Botão captura (disabled)setCaptureButtonDisabledIconColor
setCaptureButtonDisabledBackgroundColor
setCaptureButtonDisabledBorderColor
Bottom sheetsetBottomSheetColor
setBottomSheetCornerRadius
Mensagem de confirmaçãosetConfirmationMessageText
setConfirmationMessageColor
setConfirmationMessageFont
Botão confirmarsetConfirmButtonText
setConfirmButtonConfirmationText
setConfirmButtonTextFont
setConfirmButtonTextColor
setConfirmButtonBackgroundColor
setConfirmButtonBorderColor
Botão refazersetRetryButtonText
setRetryButtonTextFont
setRetryButtonTextColor
setRetryButtonBackgroundColor
setRetryButtonBorderColor

🔳 QR Code

setQrCodeCustomization { builder in ... }

GrupoMétodos
Botão voltarsetBackButtonIcon
setBackButtonIconColor
setBackButtonBackgroundColor
setBackButtonBorderColor
Alvo QRsetSquareTargetColor
Bottom sheetsetBottomSheetColor
setBottomSheetCornerRadius
TítulosetTitle
setTitleColor
setTitleFont
LegendasetCaption
setCaptionColor
setCaptionFont
Botão arquivosetFileButtonText
setFileButtonTextFont
setFileButtonTextColor
setFileButtonBackgroundColor
setFileButtonBorderColor

📤 Upload

setUploadCustomization { builder in ... }

GrupoMétodos
FundosetBackgroundColor
Botão voltarsetBackButtonIcon
setBackButtonIconColor
setBackButtonBackgroundColor
setBackButtonBorderColor
Botão fecharsetCloseButtonIcon
setCloseButtonIconColor
setCloseButtonBackgroundColor
setCloseButtonBorderColor
Título / descriçãosetFileTitle
setFileTitleFont
setFileTitleColor
setFileDescription
setFileDescriptionFont
setFileDescriptionColor
Área de uploadsetUploadAreaIcon
setUploadAreaIconUnselectedColor
setUploadAreaIconSelectedColor
setUploadAreaCallout
setUploadAreaCalloutFont
setUploadAreaTitle
setUploadAreaTitleFont
setUploadAreaTextColor
setUploadAreaBackgroundUnselectedColor
setUploadAreaBackgroundSelectedColor
setUploadAreaBorderUnselectedColor
setUploadAreaBorderSelectedColor
setUploadAreaBorderWidth
setUploadAreaBorderRadius
Nome do arquivosetFilenameColor
setFilenameFont
setFilenameBackgroundColor
Botão excluirsetDeleteButtonIcon
setDeleteButtonIconColor
Feedback seleçãosetFeedbackImage
setFeedbackTitle
setFeedbackTitleFont
setFeedbackTitleColor
Botão enviar (normal)setSendButtonText
setSendButtonTextFont
setSendButtonNormalTextColor
setSendButtonNormalBackgroundColor
setSendButtonNormalBorderColor
Botão enviar (disabled)setSendButtonDisabledTextColor
setSendButtonDisabledBackgroundColor
setSendButtonDisabledBorderColor

⏳ Loading

setLoadingCustomization { builder in ... }

GrupoMétodos
FundosetBackgroundColor
SpinnersetSpinnerColor
setSpinnerWidth
setSpinnerScaleFactor

🧾 Resultado

setResultCustomization { builder in ... }

GrupoMétodos
FundosetSuccessBackgroundColor
setErrorBackgroundColor
setRetryBackgroundColor
ImagemsetSuccessImage
setErrorImage
setRetryImage
MensagemsetMessageFont
setSuccessMessage
setSuccessMessageColor
setErrorMessage
setErrorMessageColor
setRetryMessage
setRetryMessageColor
Botão tentar novamentesetRetryButtonText
setRetryButtonTextFont
setRetryButtonTextColor
setRetryButtonBackgroundColor
setRetryButtonBorderColor

8. 🖼️ Telas completamente próprias - DocCoreCustomViews

Para substituir uma tela inteira, implemente o protocolo correspondente e passe a view no builder:

let customViews = DocCoreCustomViews.builder()
    .setInstructionView(MinhaInstructionView())
    .setCameraPermissionView(MinhaCameraPermissionView())
    .setCaptureView(MinhaCaptureView())
    .setQrCodeView(MinhaQrCodeView())
    .setUploadView(MinhaUploadView())
    .setLoadingView(MinhaLoadingView()) // UIView puro
    .setResultView(MinhaResultView())
    .build()

Protocolos de custom views

TelaProtocoloTipo base
InstruçõesDocCoreCustomInstructionViewUIView
Permissão câmeraDocCoreCustomCameraPermissionViewUIView
CapturaDocCoreCustomCaptureViewUIView
QR CodeDocCoreCustomQrCodeViewUIView
UploadDocCoreCustomUploadViewUIView
LoadingDocCoreCustomLoadingViewUIView
ResultadoDocCoreCustomResultViewUIView

DocCoreCustomInstructionView

public protocol DocCoreCustomInstructionView: UIView {
    var backButton: UIButton! { get }
    var physicalDocumentOption: UIView! { get }
    var digitalDocumentOption: UIView? { get }   // opcional
    var uploadDocumentOption: UIView? { get }    // opcional

    func changeLoadingVisibility(to visibility: Visibility)
}

DocCoreCustomCameraPermissionView

public protocol DocCoreCustomCameraPermissionView: UIView {
    var backButton: UIButton! { get }
    var checkPermissionButton: UIButton! { get }
    var openSettingsButton: UIButton! { get }
    var closeButton: UIButton! { get }

    func showBottomSheet(visibility: Visibility)
}

DocCoreCustomCaptureView

public protocol DocCoreCustomCaptureView: UIView {
    var cameraPreview: CameraPreviewView! { get }
    var cameraMask: UIView! { get }
    var backButton: UIButton! { get }
    var closeButton: UIButton! { get }
    var instructionLabel: UILabel! { get }
    var cameraVisualizer: UIView! { get }
    var previewImageView: UIImageView! { get }
    var captureButton: UIButton! { get }
    var confirmButton: UIButton! { get }
    var retryButton: UIButton! { get }

    func displayConfirmationSheet(visibility: Visibility, animated: Bool)
    func setFocus(to focusElement: FocusIndicator, animated: Bool)
    func setConfirmButtonTitle(to newTitle: String)
}

DocCoreCustomQrCodeView

public protocol DocCoreCustomQrCodeView: UIView {
    var cameraPreview: CameraPreviewView! { get }
    var cameraMask: UIView! { get }
    var cameraVisualizer: UIView! { get }
    var backButton: UIButton! { get }
    var fileButton: UIButton! { get }

    func displayBottomSheet(animated: Bool)
    func hideBottomSheet(animated: Bool)
}

DocCoreCustomUploadView

public protocol DocCoreCustomUploadView: UIView {
    var backButton: UIButton! { get }
    var closeButton: UIButton! { get }
    var uploadArea: UIView! { get }
    var deleteButton: UIButton! { get }
    var sendButton: UIButton! { get }

    func displayFileContainer(with fileName: String)
    func hideFileContainer()
}

DocCoreCustomLoadingView

public typealias DocCoreCustomLoadingView = UIView

DocCoreCustomResultView

public protocol DocCoreCustomResultView: UIView {
    var resultButton: UIButton! { get }
    
    func display(for resultType: DocCoreResultType)
}

9. 🧪 Ambiente de testes

  • Use .HML e AppKey de homologação.
  • Teste em dispositivo físico (a câmera não funciona no Simulator).
  • Verifique que NSCameraUsageDescription está preenchido no Info.plist.

10. 🛠️ Boas práticas

  • Crie o DocumentManager em cada jornada — não o reutilize entre apresentações.
  • Trate sempre .userCancelled separadamente dos erros reais.
  • Prefira a customização granular (DocCoreCustomization); use DocCoreCustomViews apenas quando precisar de layout completamente próprio.

11. 💻 Aplicativo de exemplo

O repositório modules-certiface traz integrações prontas dos três modos (padrão, aparência customizada e telas próprias):