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
- 📌 Visão geral
- ✅ Requisitos de compatibilidade
- ⚙️ Instalação
- 🚀 Inicialização e execução
- 📦 DocumentManagerOptions
- 🔔 Callbacks e erros
- 🎨 Customização - DocCoreCustomization
- 🖼️ Telas completamente próprias - DocCoreCustomViews
- 🧪 Ambiente de testes
- 🛠️ Boas práticas
- 💻 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
| Item | Valor |
|---|---|
| iOS mínimo | 13.0 |
| Swift | 5.0 |
| UI framework | UIKit |
| 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'
endExecute 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âmetro | Tipo | Padrão | Descrição |
|---|---|---|---|
appKey | String | obrigatório | Chave da aplicação fornecida pelo backend. |
environment | Environment | obrigatório | .HML (homologação) ou .PRD (produção). |
additionalOptions | Set<AdditionalDocumentOption> | [] | .digitalDocument e/ou .uploadDocument. |
showFeedback | Bool | true | Exibe a tela de resultado ao fim do fluxo. |
docCoreCustomization | DocCoreCustomization | tema padrão | Customização granular por região de tela. |
docCoreCustomViews | DocCoreCustomViews | telas padrões | Substituiçã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
DocumentError| Caso | code | message |
|---|---|---|
.invalidAppKey | 0 | App Key inválido. |
.certifaceOff | 1 | Serviço indisponível. |
.cameraSetupFailed | 2 | Falha ao configurar a câmera. |
.noCameraPermission | 3 | Não foi concedida permissão de acesso à câmera do aparelho. |
.errorCapturePicture | 4 | Falha na captura do documento. |
.noInternetConnection | 5 | Sem conexão à Internet. |
.validationError | 6 | Não foi possível concluir a validação, tente novamente. |
.userCancelled | 7 | Jornada 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.
| Grupo | Métodos |
|---|---|
| Botão voltar | setBackButtonIconsetBackButtonIconColorsetBackButtonBackgroundColorsetBackButtonBorderColor |
| Fundo | setBackgroundColor |
| Imagem de contexto | setContextImage |
| Loading | setLoadingColor |
| Bottom sheet | setBottomSheetColorsetBottomSheetCornerRadius |
| Título | setTitlesetTitleColorsetTitleFont |
| Legenda | setCaptionsetCaptionColorsetCaptionFont |
| Opção documento físico | setPhysicalDocumentOptionImagesetPhysicalDocumentOptionTitlesetPhysicalDocumentOptionTitleColorsetPhysicalDocumentOptionTitleFontsetPhysicalDocumentOptionDescriptionsetPhysicalDocumentOptionDescriptionColorsetPhysicalDocumentOptionDescriptionFontsetPhysicalDocumentOptionBackgroundColorsetPhysicalDocumentOptionCircleBackgroundColorsetPhysicalDocumentOptionBorderRadiussetPhysicalDocumentOptionBorderWidthsetPhysicalDocumentOptionBorderColorsetPhysicalDocumentOptionIconColor |
| Opção CNH digital | setDigitalDocumentOptionImagesetDigitalDocumentOptionTitlesetDigitalDocumentOptionTitleColorsetDigitalDocumentOptionTitleFontsetDigitalDocumentOptionDescriptionsetDigitalDocumentOptionDescriptionColorsetDigitalDocumentOptionDescriptionFontsetDigitalDocumentOptionBackgroundColorsetDigitalDocumentOptionCircleBackgroundColorsetDigitalDocumentOptionBorderRadiussetDigitalDocumentOptionBorderWidthsetDigitalDocumentOptionBorderColorsetDigitalDocumentOptionIconColor |
| Opção upload PDF | setUploadDocumentOptionImagesetUploadDocumentOptionTitlesetUploadDocumentOptionTitleColorsetUploadDocumentOptionTitleFontsetUploadDocumentOptionDescriptionsetUploadDocumentOptionDescriptionColorsetUploadDocumentOptionDescriptionFontsetUploadDocumentOptionBackgroundColorsetUploadDocumentOptionCircleBackgroundColorsetUploadDocumentOptionBorderRadiussetUploadDocumentOptionBorderWidthsetUploadDocumentOptionBorderColorsetUploadDocumentOptionIconColor |
.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 ... }
| Grupo | Métodos |
|---|---|
| Fundo | setBackgroundColor |
| Botão voltar | setBackButtonIconsetBackButtonIconColorsetBackButtonBackgroundColorsetBackButtonBorderColor |
| Ícone câmera | setCameraImagesetCameraImageColor |
| Título | setTitle · setTitleColor · setTitleFont |
| Legenda | setCaptionsetCaptionColorsetCaptionFont |
| Botão permissão | setCheckPermissionButtonTextsetCheckPermissionButtonTextFontsetCheckPermissionButtonTextColorsetCheckPermissionButtonBackgroundColorsetCheckPermissionButtonBorderColor |
| Bottom sheet | setBottomSheetColorsetBottomSheetCornerRadiussetBottomSheetTitlesetBottomSheetTitleColorsetBottomSheetTitleFontsetBottomSheetCaptionsetBottomSheetCaptionColorsetBottomSheetCaptionFont |
| Botão configurações | setOpenSettingsButtonTextsetOpenSettingsButtonTextFontsetOpenSettingsButtonTextColorsetOpenSettingsButtonBackgroundColorsetOpenSettingsButtonBorderColor |
| Botão fechar | setCloseButtonTextsetCloseButtonTextFontsetCloseButtonTextColorsetCloseButtonBackgroundColorsetCloseButtonBorderColor |
📸 Captura (frente/verso)
setCaptureCustomization { builder in ... }
| Grupo | Métodos |
|---|---|
| Botão voltar | setBackButtonIconsetBackButtonIconColorsetBackButtonBackgroundColorsetBackButtonBorderColor |
| Botão fechar | setCloseButtonIconsetCloseButtonIconColorsetCloseButtonBackgroundColorsetCloseButtonBorderColor |
| Indicador frente | setFrontIndicatorTextsetFrontIndicatorColorsetFrontIndicatorFocusedStateImagesetFrontIndicatorFocusedStateTextColorsetFrontIndicatorFocusedStateTextFontsetFrontIndicatorUnfocusedStateImagesetFrontIndicatorUnfocusedStateTextColorsetFrontIndicatorUnfocusedStateTextFont |
| Indicador verso | setBackIndicatorTextsetBackIndicatorColorsetBackIndicatorFocusedStateImagesetBackIndicatorFocusedStateTextColorsetBackIndicatorFocusedStateTextFontsetBackIndicatorUnfocusedStateImagesetBackIndicatorUnfocusedStateTextColorsetBackIndicatorUnfocusedStateTextFont |
| Texto guia | setInstructionGuideFrontTextsetInstructionGuideBackTextsetInstructionConfirmationTextsetInstructionTextColor setInstructionTextFont |
| Área de preview | setPreviewCapturedBorderColorsetPreviewUncapturedBorderColor |
| Fundo | setBackgroundColor |
| Botão captura (normal) | setCaptureButtonIconsetCaptureButtonNormalIconColorsetCaptureButtonNormalBackgroundColorsetCaptureButtonNormalBorderColor |
| Botão captura (disabled) | setCaptureButtonDisabledIconColorsetCaptureButtonDisabledBackgroundColorsetCaptureButtonDisabledBorderColor |
| Bottom sheet | setBottomSheetColorsetBottomSheetCornerRadius |
| Mensagem de confirmação | setConfirmationMessageTextsetConfirmationMessageColorsetConfirmationMessageFont |
| Botão confirmar | setConfirmButtonTextsetConfirmButtonConfirmationTextsetConfirmButtonTextFontsetConfirmButtonTextColorsetConfirmButtonBackgroundColorsetConfirmButtonBorderColor |
| Botão refazer | setRetryButtonTextsetRetryButtonTextFontsetRetryButtonTextColorsetRetryButtonBackgroundColorsetRetryButtonBorderColor |
🔳 QR Code
setQrCodeCustomization { builder in ... }
| Grupo | Métodos |
|---|---|
| Botão voltar | setBackButtonIconsetBackButtonIconColorsetBackButtonBackgroundColorsetBackButtonBorderColor |
| Alvo QR | setSquareTargetColor |
| Bottom sheet | setBottomSheetColorsetBottomSheetCornerRadius |
| Título | setTitlesetTitleColorsetTitleFont |
| Legenda | setCaptionsetCaptionColorsetCaptionFont |
| Botão arquivo | setFileButtonTextsetFileButtonTextFontsetFileButtonTextColorsetFileButtonBackgroundColorsetFileButtonBorderColor |
📤 Upload
setUploadCustomization { builder in ... }
| Grupo | Métodos |
|---|---|
| Fundo | setBackgroundColor |
| Botão voltar | setBackButtonIconsetBackButtonIconColorsetBackButtonBackgroundColorsetBackButtonBorderColor |
| Botão fechar | setCloseButtonIconsetCloseButtonIconColorsetCloseButtonBackgroundColorsetCloseButtonBorderColor |
| Título / descrição | setFileTitlesetFileTitleFontsetFileTitleColorsetFileDescriptionsetFileDescriptionFontsetFileDescriptionColor |
| Área de upload | setUploadAreaIconsetUploadAreaIconUnselectedColorsetUploadAreaIconSelectedColorsetUploadAreaCalloutsetUploadAreaCalloutFontsetUploadAreaTitlesetUploadAreaTitleFontsetUploadAreaTextColorsetUploadAreaBackgroundUnselectedColorsetUploadAreaBackgroundSelectedColorsetUploadAreaBorderUnselectedColorsetUploadAreaBorderSelectedColorsetUploadAreaBorderWidthsetUploadAreaBorderRadius |
| Nome do arquivo | setFilenameColorsetFilenameFontsetFilenameBackgroundColor |
| Botão excluir | setDeleteButtonIconsetDeleteButtonIconColor |
| Feedback seleção | setFeedbackImagesetFeedbackTitlesetFeedbackTitleFontsetFeedbackTitleColor |
| Botão enviar (normal) | setSendButtonTextsetSendButtonTextFontsetSendButtonNormalTextColorsetSendButtonNormalBackgroundColorsetSendButtonNormalBorderColor |
| Botão enviar (disabled) | setSendButtonDisabledTextColorsetSendButtonDisabledBackgroundColorsetSendButtonDisabledBorderColor |
⏳ Loading
setLoadingCustomization { builder in ... }
| Grupo | Métodos |
|---|---|
| Fundo | setBackgroundColor |
| Spinner | setSpinnerColorsetSpinnerWidthsetSpinnerScaleFactor |
🧾 Resultado
setResultCustomization { builder in ... }
| Grupo | Métodos |
|---|---|
| Fundo | setSuccessBackgroundColorsetErrorBackgroundColorsetRetryBackgroundColor |
| Imagem | setSuccessImagesetErrorImagesetRetryImage |
| Mensagem | setMessageFontsetSuccessMessagesetSuccessMessageColorsetErrorMessagesetErrorMessageColorsetRetryMessagesetRetryMessageColor |
| Botão tentar novamente | setRetryButtonTextsetRetryButtonTextFontsetRetryButtonTextColorsetRetryButtonBackgroundColorsetRetryButtonBorderColor |
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
| Tela | Protocolo | Tipo base |
|---|---|---|
| Instruções | DocCoreCustomInstructionView | UIView |
| Permissão câmera | DocCoreCustomCameraPermissionView | UIView |
| Captura | DocCoreCustomCaptureView | UIView |
| QR Code | DocCoreCustomQrCodeView | UIView |
| Upload | DocCoreCustomUploadView | UIView |
| Loading | DocCoreCustomLoadingView | UIView |
| Resultado | DocCoreCustomResultView | UIView |
DocCoreCustomInstructionView
DocCoreCustomInstructionViewpublic 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
DocCoreCustomCameraPermissionViewpublic protocol DocCoreCustomCameraPermissionView: UIView {
var backButton: UIButton! { get }
var checkPermissionButton: UIButton! { get }
var openSettingsButton: UIButton! { get }
var closeButton: UIButton! { get }
func showBottomSheet(visibility: Visibility)
}DocCoreCustomCaptureView
DocCoreCustomCaptureViewpublic 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
DocCoreCustomQrCodeViewpublic 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
DocCoreCustomUploadViewpublic 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
DocCoreCustomLoadingViewpublic typealias DocCoreCustomLoadingView = UIViewDocCoreCustomResultView
DocCoreCustomResultViewpublic protocol DocCoreCustomResultView: UIView {
var resultButton: UIButton! { get }
func display(for resultType: DocCoreResultType)
}9. 🧪 Ambiente de testes
- Use
.HMLe AppKey de homologação. - Teste em dispositivo físico (a câmera não funciona no Simulator).
- Verifique que
NSCameraUsageDescriptionestá preenchido noInfo.plist.
10. 🛠️ Boas práticas
- Crie o
DocumentManagerem cada jornada — não o reutilize entre apresentações. - Trate sempre
.userCancelledseparadamente dos erros reais. - Prefira a customização granular (
DocCoreCustomization); useDocCoreCustomViewsapenas 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):
- GitHub: oititec/modules-certiface
Updated about 1 month ago
