Introdução

Bem vindo à SDK iOS de OCR (Optical Character Recognition) para leitura de documentos da Zaig. Esta SDK realiza a captura de documentos e envio a API de OCR da ZAIG. Você pode utilizar esta SDK para capturar através do seu aplicativo uma imagem de um documento de seu cliente a ser reconhecido, como uma Carteira de Habilitação ou Cédula de identidade, e referenciá-lo através de uma chave nos demais produtos do sistema ZAIG.

Problemas?

Nós não somos uma companhia que se esconde atrás de uma API! Entre em contato com o nosso suporte e nós responderemos o mais rápido possível. Fique à vontade para nos ligar caso deseje uma resposta rápida!

Adoramos Feedback

Mesmo que você já tenha resolvido o seu problema ou que ele seja muito simples (Até mesmo um typo ou uma organização inadequada que você já entendeu), envie-nos um e-mail, assim nós tornamos a documentação cada vez mais prática e a próxima pessoa não vai precisar sofrer as dores que você sofreu!

Soluções híbridas

Além da integração nativa em Swift, nossos SDKs são compatíveis com: Flutter, Ionic Cordova, Capacitor, React Native entre outras. Atualmente nossos SDKs híbridos estão documentados em um repositório privado. Caso tenha interesse nestas integrações, entre em contato com nosso suporte para liberarmos acesso.

Importando a SDK

Remotamente

Iniciando a instalação

  pod init

Nosso SDK pode ser importado utilizando CocoaPods.

Para iniciar a instalação, execute o comando ao lado na pasta raiz do seu projeto.

Adicionando a source no podfile

   source 'https://github.com/ZaigCoding/iOS.git'

O próximo passo é adicionar no arquivo podfile o source da Zaig.

Adicionando o pod no podfile

  pod 'ZaigIosOCR', '~> <version>'

Por fim, basta adicionar o nome do pod de acordo com o formato ao lado.

Exemplo de podfile

  source 'https://github.com/ZaigCoding/iOS.git'
  source 'https://cdn.cocoapods.org/'
  target 'ExampleApp' do
    use_frameworks!
    pod 'ZaigIosOCR', '~> 1.5.1'
  end

  post_install do |installer|
  datadog_sdk = installer.pods_project.targets.detect {|e| e.name == 'DatadogSDK'}
  datadog_sdk.build_configurations.each do |config|
    config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES'
  end
  end

Ao lado temos um exemplo completo da instalação.

Instalando as dependências

  pod install

Por fim, execute o comando pod install para baixar e instalar as dependências.

Permissões Necessárias

Para que a SDK possa acessar os recursos do dispositivo para coletar a foto, é necessário que sejam solicitadas permissões ao usuário.

No arquivo info.plist, adicione as permissões abaixo:

Iniciando a SDK

import ZaigIosOcr

class ViewController: UIViewController, ZaigIosOcrControllerDelegate {

    var zaigOcrConfiguration : ZaigIosOcrConfiguration?

    override func viewDidLoad() {
        super.viewDidLoad()
        self.setupOcr()
    }

    func setupOcr() -> Void
    {
        // The environment can be 'Sandbox' ou 'Production'
        let environment = ZaigIosOcrEnvironment.Sandbox

        // MobileToken is the key sent to you by Zaig. Each environment requires a different MobileToken.
        let mobileToken = "YOUR_MOBILE_TOKEN_SENT_BY_ZAIG"

        // The documentFlow can be 'CnhFull' , 'CnhFrontAndBack' ou 'RgFrontAndBack'
        let documentFlow = ZaigIosOcrDocumentFlow.CnhFrontAndBack

        self.ocrConfig = ZaigIosOcrConfiguration(environment: environment,
                                            mobileToken: mobileToken,
                                            sessionId: "UNIQUE_SESSION_ID",
                                            documentFlow: documentFlow,
                                            backgroundColor: "#000000",
                                            fontColor: "#FFFFFF",
                                            fontFamily: .open_sans,
                                            showIntroductionScreens: true,
                                            logLevel: .debug
                                            )
    }

    // Event where you intend to call Zaig OCR View Controller - on this example, when the user press 'next' button

    @IBAction func pressNext(_ sender: Any) {
        let zaigOcrController =  ZaigIosOcrController(ocrConfiguration: self.ocrConfig)
        zaigOcrViewController.delegate = self
        let zaigOcrViewController = zaigOcrController.getViewController()
        present(zaigOcrViewController, animated: true, completion: nil)
    }

    // Do something if Zaig OCR's SDK succesfully collected document picture
    func zaigIosOcrController(_ ocrViewController: ZaigIosOcrController, didFinishWithResults results: ZaigIosOcrControllerResponse) {

    }

    // Do something if Zaig OCR's SDK found any error when collecting document picture
    func zaigIosOcrController(_ ocrViewController: ZaigIosOcrController, didFailWithError error: ZaigIosOcrControllerError) {

    }

    // Do something if the user canceled the picture collection on any steps
    func zaigIosOcrControllerDidCancel(_ ocrViewController: ZaigIosOcrController) {

    }
}

Para incorporar a SDK ao seu aplicativo você deve iniciar realizar a configuração do seu aplicativo de captura personalizado através da classe ZaigIosOcrConfiguration e depois instanciar o ViewController ZaigIosOcrController passando como argumento as configurações personalizadas.

Para iniciar o processo de análise de documento, basta chamar a função present para chamar o ViewController da Zaig que realizará a coleta das imagens.

Importante implementar o Delegate responsável por receber os retornos em caso de sucesso, erro ou no caso de o usuário interromper a jornada em qualquer etapa da validação.

Ao lado temos um exemplo completo da implementação.

Mobile Token

Utilizamos um Mobile Token para permitir o acesso autenticado do seu aplicativo a nossa API. Ele provavelmente já foi enviada por e-mail para você. Caso ainda não tenha recebido o seu token, envie um e-mail para suporte.caas@qitech.com.br.

Nossa API espera receber o Mobile Token em todas as requisições ao nosso servidor vindas da SDK, portanto, este deve ser obrigatoriamente incluido como parâmetro de configuração através do método mencionado anteriormente.

ZaigIosOcrConfiguration

let visualConfiguration = VisualConfiguration()
        visualConfiguration.setOnboarding(onboardingFilePath: Bundle.main.path(forResource: "onboarding", ofType: "png")!, onboardingWidth: 200)

let textConfiguration = TextConfiguration()
        textConfiguration.setCustomText(on: .onboardingTitle, text: "Vamos começar!")
        textConfiguration.setCustomText(on: .onboardingFirstLabel, text: "- Vá para um local com boa luminosidade")
        textConfiguration.setCustomText(on: .onboardingSecondLabel, text: "- Retire o documento do plástico")

let ocrConfig = ZaigIosOcrConfiguration(environment: ZaigIosOcrEnvironment.Sandbox,
                                            mobileToken: "41fb4755-9bcf-4ae3-b981-b6009e51ce4a",
                                            sessionId: "288eb399-4936-4133-ab2c-5611d6e5bb7a",
                                            documentSteps: documentSteps,
                                            backgroundColor: "#C9CCD3",
                                            fontColor: "#337DFF",
                                            fontFamily: .open_sans,
                                            showIntroductionScreens: true,
                                            showSuccessScreen: false,
                                            logLevel: .debug
                                            )

ocrConfig.setVisualConfiguration(visualConfiguration: visualConfiguration)
ocrConfig.setTextConfiguration(textConfiguration: textConfiguration)

A classe ZaigIosOcrConfiguration é utilizada para que você possa configurar ambiente, credenciais, aspectos visuais e textuais, e o fluxo de coleta de imagens dos documentos, ou seja, todas as configurações necessárias para personalização e funcionamento da SDK.

Na tabela abaixo você encontra o detalhe de todos os argumentos que devem ser utilizados na sua instanciação:

Na tabela abaixo você encontra todos os métodos aceitos pela instância para configuração:

VisualConfiguration

A classe VisualConfiguration é utilizada para configurar os ícones e imagens que aparecem para o usuário durante a execução da SDK.

Esta classe apresenta os seguintes métodos de configuração da instância:

TextConfiguration

A classe TextConfiguration é utilizada para configurar os textos das labels que aparecem para o usuário durante a execução da SDK.

Esta classe apresenta os seguintes métodos de configuração da instância:

Enumeradores

Os valores possíveis do enumerador ZaigIosOcrEnvironment podem ser:

• ZaigIosOcrEnvironment.Sandbox - Utilizado para uso da SDK no ambiente de sandbox da Zaig.
• ZaigIosOcrEnvironment.Production - Utilizado para uso da SDK no ambiente de produção da Zaig.

Os valores possíveis do enumerador ZaigIosOcrDocumentFlow podem ser:

• ZaigIosOcrDocumentFlow.CnhFull - Utilizado para realizar a coleta de uma só foto da CNH aberta.
• ZaigIosOcrDocumentFlow.CnhFrontAndBack - Utilizado para realizar a coleta da foto da CNH em duas etapas, a primeira da frente e na sequência, do verso.
• ZaigIosOcrDocumentFlow.CnhFront - Utilizado para realizar a coleta da foto apenas da frente da CNH.
• ZaigIosOcrDocumentFlow.CnhBack - Utilizado para realizar a coleta da foto apenas do verso da CNH.
• ZaigIosOcrDocumentFlow.CnhDigital - Utilizado para realizar a coleta do PDF de CNH Digital.
• ZaigIosOcrDocumentFlow.RgFrontAndBack - Utilizado para realizar a coleta da foto do RG em duas etapas, a primeira da frente e na sequência, do verso.
• ZaigIosOcrDocumentFlow.RgFront - Utilizado para realizar a coleta da foto apenas da frente do RG.
• ZaigIosOcrDocumentFlow.RgBack - Utilizado para realizar a coleta da foto apenas do verso do RG.
• ZaigIosOcrDocumentFlow.ProofOfAddress - Utilizado para realizar a coleta da foto do comprovante de endereço.

Coletando os Retornos

class ViewController: UIViewController, ZaigIosOcrControllerDelegate {

    // Do something if Zaig OCR's SDK succesfully collected document picture
    func zaigIosOcrController(_ ocrViewController: ZaigIosOcrController, didFinishWithResults response: ZaigIosOcrControllerResponse) {

    }

    // Do something if Zaig OCR's SDK found any error when collecting document picture
    func zaigIosOcrController(_ ocrViewController: ZaigIosOcrController, didFailWithError error: ZaigIosOcrControllerError) {

    }

    // Do something if the user canceled the picture collection on any steps
    func zaigIosOcrControllerDidCancel(_ ocrViewController: ZaigIosOcrController) {

    }
}

Para obter as respostas da SDK , você deve implementar o delegate ZaigIosOcrControllerDelegate em seu controller, conforme exemplo ao lado.

ZaigIosOcrControllerResponse

A classe ZaigIosOcrControllerResponse é utilizada para que você possa receber a resposta da SDK da Zaig.

Na tabela abaixo você encontra o detalhe de todas as propriedades desta classe:

Objeto OcrResponse

Os valores possíveis do enumerador ZaigIosOcrDocumentTemplate podem ser:

• ZaigIosOcrDocumentTemplate.CnhFull - Identifica o resultado da validação da CNH inteira.
• ZaigIosOcrDocumentTemplate.CnhFront - Identifica o resultado da validação da frente da CNH.
• ZaigIosOcrDocumentTemplate.CnhBack - Identifica o resultado da validação do verso da CNH.
• ZaigIosOcrDocumentTemplate.RgFront - Identifica o resultado da validação da frente do RG.
• ZaigIosOcrDocumentTemplate.RgBack - Identifica o resultado da validação do verso do RG.

ZaigIosOcrControllerError

A classe ZaigIosOcrControllerError é acionada no caso de algum erro que leve ao encerramento da SDK. Quando isso ocorrer, a Zaig retornará uma subclasse que terá um nome correspondente ao erro que levou ao encerramento da SDK, conforme tabela abaixo:

Para mapear qual a subclasse, e portanto, qual o motivo do erro, utilize o método isKindOfClass() do swift.