SDK Captura de Documentos iOS

v2.1.2

Introdução

Os SDKs de Captura de Documentos permitem a realização de capturas pelo usuário dentro de sua aplicação. Essas capturas passam por validações que identificam o tipo de documento e que avaliam a qualidade da imagem capturada, instruindo o usuário através de feedbacks visuais.

Todas as informações coletadas são dados relacionados apenas ao dispositivo do usuário.

É necessário que o usuário conceda permissão de acesso à câmera do dispositivo para capturar e enviar seu documento.

iOS

Requisitos

  • Versão do sistema operacional iOS: 12.0 ou superior.
  • Versão do projeto Swift 4.2+: funciona com Xcode superior ao 14.
  • Espaço em disco: 18.5mb

Instalação do Pacote

  • CocoaPods

Para adicionar o SDK ao seu projeto utilizando Cocoapods basta adicionar o seguinte comando ao seu Podfile:

Instalação em ambiente de desenvolvimento e testes

platform :ios, '12.0'

use_frameworks!

target 'NOME_DO_SEU_PROJETO' do
pod 'CSDocumentoscopySDK', :git => 'URL DO REPOSITÓRIO ENVIADO PELA CLEARSALE', :tag => '2.1.2-hml'
end

Instalação em ambiente de produção

platform :ios, '12.0'

use_frameworks!

target 'NOME_DO_SEU_PROJETO' do
pod 'CSDocumentoscopySDK', :git => 'URL DO REPOSITÓRIO ENVIADO PELA CLEARSALE', :tag => '2.1.2'
end

Configuração

Instruções para configuração do framework no projeto:

  1. Adicionar as seguintes entradas ao arquivo Info.plist do projeto de destino:
<key>NSCameraUsageDescription</key>
<string>This app requires access to the camera.</string>

Classe CSDocumentoscopySDK

Descrição
CSDocumentoscopy classe responsável pela inicialização do SDK.

Atributo/FunçãoDescrição
delegateDelegate responsável por retornar os feedbacks do SDK para o usuário que o implementa.
initializeFunção que chama o SDK.
ParâmetrosDescrição
configuration: CSDocumentoscopySDKConfigparâmetro OPCIONAL de configurações personalizadas do SDK .

Classe CSDocumentoscopySDKConfig

Descrição
CSDocumentoscopyConfig classe responsável por receber as configurações personalizadas do SDK.

ParâmetrosDescrição
colors: CSDocumentoscopyColorsConfigparâmetro de configuração de cores do projeto de SDK

Classe CSDocumentoscopyColorsConfig

Descrição
CSDocumentoscopyColorsConfig classe responsável por receber as configurações personalizadas de cores SDK.

ParâmetrosDescrição
primaryColor: UIColors?Parâmetro responsável por alterar a cor de fundo dos botões de ações principais e dos botões sem preenchimento.
secondaryColor: UIColors?Parâmetro responsável por alterar a cor de ícones, loader e cor de fundo de barras de informação da tela de captura.
tertiaryColor: UIColors?Parâmetro responsável por alterar a cor do background de ícones maiores.
titleColor: UIColors?Parâmetro responsável por alterar a cor do texto. Exemplo: Título.
paragraphColor: UIColors?Parâmetro responsável por alterar a cor do texto. Exemplo: parágrafo e o botão de fechar "X".

Método initialize

Descrição
initialize é responsável pela inicialização do SDK e necessita de certos parâmetros para que consiga realizar sua tarefa.

ParâmetrosDescrição
clientId: StringId que identifica o cliente junto à ClearSale (valor fornecido pela ClearSale).
clientSecret: StringToken que funciona como autenticação para identificação do cliente a utilizar o serviço (valor fornecido pela ClearSale).
identifierId: StringIdentifier ID é uma string de até 100 caracteres OBRIGATÓRIA que identifica todo o fluxo do usuário de forma única e é gerada pela entidade. Serve para agilizar consultas e chamados feitos pela entidade (e pode ser utilizada como identificador interno entre produtos aqui da ClearSale).
cpf: StringÉ uma string de 11 caracteres (no formato CPF) OBRIGATÓRIA do usuário que irá realizar o fluxo, devendo seguir as regras de validade estipuladas pelo Governo.
viewControllerContexto que o SDK será aberto.

Classe CSDocumentoscopyDelegate

Descrição
Para acesso à resposta do processamento da ClearSale ou erros durante o processo é disponibilizado o delegate CSDocumentoscopyDelegate.

Construtores
Esta classe não possui um construtor público.

Eventos do Fluxo

Nome do EventoDescriçãoObrigatoriedade
didOpen()Este evento é acionado sempre que o SDK é iniciado.Opcional
didTapClose()Este evento é acionado sempre que o usuário sai de forma intencional do SDK.Opcional

Eventos de Sucesso

Nome do EventoDescriçãoObrigatoriedade
didFinishCapture(result: CSDocumentoscopyResult)Ao concluir todo o fluxo e enviar as imagens com sucesso para o servidor, o SDK se encerra automaticamente após 2 segundos, acionando este evento.Requerido

Eventos de Erro

Nome do EventoDescriçãoObrigatoriedade
didReceiveError(error: CSDocumentoscopyError)Ao ocorrerem erros mapeados, este evento será chamado logo após o fechamento automático do SDK.Requerido

Classe CSDocumentoscopyError

Parâmetros
Esta classe possui os seguintes parâmetros.

ParâmetroDescrição
case: CSDocumentoscopyErrorEnum interno de error.
text: StringTexto descritivo do error.
errorCode: IntCódigo interno do error.

Enum CSDocumentoscopyError

Descrição
Representa os possíveis erros que serão retornados pelo CSDocumentoscopyError

Cases
Este enum possui os seguintes cases:

Nome do CaseDescrição
noDataAcontecerá quando ao solicitar ao SDK as fotos armazenadas em memória, seja para enviar para o backend ou qualquer outro uso, ocorrer um erro por elas não estarem mais armazenadas.
errorParsableAcontecerá ao tentar converter o arquivo do tipo Imagem para Base64 e por qualquer motivo, o processo falhar.
noInternetConnectionAcontecerá quando qualquer chamada à API for solicitada e o usuário não estiver com internet ativa.
authenticationFailureAcontecerá se ao tentar autenticar o usuário a request falhar.
invalidCPFAcontecerá ao tentar iniciar o SDK passando um CPF inválido.
invalidIdentifierIdAcontecerá ao passar um identifierID fora do formato esperado.
internalErrorAcontecerá caso ocorra um erro interno.
switchContextAcontecerá quando a aplicação entrar em background durante o o fluxo do usuário.

Classe CSDocumentoscopySDKResult

Parâmetros
Esta classe possui os seguintes parâmetros.

ParâmetroDescrição
sessionId: StringID único da sessão, utilizado para a recuperação da imagem.
documentType: CSDocumentoscopyDocumentTypeResultado do tipo do documento sendo RG ou CNH.

Exemplos

Faça a importação da biblioteca em sua classe.

import CSDocumentoscopySDK

Instancie o SDK passando os parâmetros pedidos, conforme exemplo abaixo.

let sdk = CSDocumentoscopy()
sdk.delegate = self
sdk.initialize(
    clientId: "PARÂMETRO ENVIADO PELA CLEARSALE",
    clientSecret: "PARÂMETRO ENVIADO PELA CLEARSALE",
    identifierId: "PARÂMETRO GERADO PELO CLIENTE",
    cpf: "CPF DO USUÁRIO",
    viewController: "CONTEXTO QUE O SDK SERÁ ABERTO")

Implementação do Delegate
Estenda o protocolo CSDocumentoscopyDelegate e implemente seus métodos, para receber os retornos do SDK, como no exemplo abaixo.

extension Classe: CSDocumentoscopyDelegate {
    func didOpen() { }
    func didTapClose() { }
    func didFinishCapture(result: CSDocumentoscopyResult) { }
    func didReceiveError(error: CSDocumentoscopyError) { }
}

Samples

Visando facilitar a integração e homologação, disponibilizamos amostras dos SDK:

📘

Aplicativo de Exemplo em Objective-C: clique aqui

📘

Aplicativo de Exemplo em Swift: clique aqui