Pular para o conteúdo principal

Captura de documento

Este guia foi elaborado para ajudá-lo a implementar o SDK Android de forma rápida e fácil. São disponibilizados conceitos básicos, exemplos de implementação dos SDKs e maneiras de como interagir com as APIs REST dos motores.

Através deste guia, é possivel:

  • Implementar a abertura da câmera e a captura de imagens;
  • Manipular os dados de retorno;
  • Utilizar o retorno do SDK com as APIs do motor.

Antes de começar, certifique-se que seguiu o passo-a-passo para instalação e importação do SDK neste guia.

RECURSOS DISPONÍVEIS​

O SDK Android oferece um componente para captura de documento contendo um frame de captura que auxilia o usuário a posicionar o documento de forma correta para a foto. A captura do documento pode ser feita pelo modo:

CÂMERA DE DOCUMENTO COM CAPTURA MANUAL​

Neste modo de câmera, existe um frame de captura para auxiliar o usuário a posicionar o documento corretamente. Após posicionar o documento corretamente, o usuário deve clicar no botão para realizar a captura da foto do documento.

A SDK não realiza nenhum tipo de validação do que está sendo capturado.

Neste modo de câmera é possivel capturar os documentos:

  • CPF: Captura da frente do CPF;
  • CNH: Captura da CNH aberta;
  • CNH frente: Captura da frente da CNH;
  • CNH verso: Captura do verso da CNH;
  • RG frente: Captura da frente do RG;
  • RG verso: Captura do verso do RG;
  • Outros: Captura de qualquer outro documento.
Camera de Documento com Captura Manual

IMPLEMENTAÇÃO​

Seguindo este guia, você tem todo o potencial do SDK embarcado em sua aplicação Android.

INICIALIZAR O SDK​

Crie uma instância do builder (Gerado através da interface IAcessoBioBuilder), fornecendo como parâmetro o contexto em questão e a implementação da classe AcessoBioListener.

A implementação dessa classe é bem simples e pode ser feita com poucas linhas de código. Tudo que precisa fazer é instanciar o builder informando o contexto em questão e sobrescrever os métodos de callback com as lógicas de negócio de sua aplicação:

public class MainActivity extends AppCompatActivity {

    private AcessoBioListener callback = new AcessoBioListener() {
        @Override
        public void onErrorAcessoBio(ErrorBio errorBio) { }

        @Override
        public void onUserClosedCameraManually() { }

        @Override
        public void onSystemClosedCameraTimeoutSession() { }

        @Override
        public void onSystemChangedTypeCameraTimeoutFaceInference() { }
    };

    private IAcessoBioBuilder acessoBioBuilder = new AcessoBio(this, callback);
}

IMPLEMENTAR AS FUNÇÕES DE CALLBACK​

Note que, o trabalho de implementação da classe AcessoBioListener é, em grande parte, a configuração dos métodos de callback. Cada método é chamado em uma situação específica de retorno do SDK.

Basta sobrescrever os métodos exemplificados no passo anterior com as lógicas de negócio de sua aplicação.

ATENÇÃO

Todos os métodos acima devem ser criados da forma indicada em seu projeto (mesmo que sem nenhuma lógica). Caso contrário, o projeto não compila com sucesso.

PERSONALIZAR O PROCESSO DE CAPTURA​

Esta é uma etapa opcional, porém muito recomendada para que o processo de captura tenha a identidade visual da sua empresa.

É possível customizar alguns objetos do frame de acordo com o modo de câmera utilizado, através do método setTheme().

ATENÇÃO

Os tipos suportados para representação de cor são Color Resource ou String contendo o código hexadecimal da cor. Ex: R.color.red ou #FF0000

Todos os métodos estão disponíveis abaixo:

IAcessoBioTheme unicoTheme = new IAcessoBioTheme() {
    @Override
    public Object getColorBackground() { 
        return R.color.your_color;
    }
    @Override
    public Object getColorBoxMessage() { 
        return R.color.your_color;
    }
    @Override
    public Object getColorTextMessage() { 
        return R.color.your_color;
    }
    @Override
    public Object getColorBackgroundPopupError() { 
        return R.color.your_color;
    }
    @Override
    public Object getColorTextPopupError() { 
        return R.color.your_color;
    }
    @Override
    public Object getColorBackgroundButtonPopupError() { 
        return R.color.your_color;
    }
    @Override
    public Object getColorTextButtonPopupError() { 
        return R.color.your_color;
    }
    @Override
    public Object getColorBackgroundTakePictureButton() { 
        return R.color.your_color;
    }
    @Override
    public Object getColorIconTakePictureButton() { 
        return R.color.your_color;
    }
    @Override
    public Object getColorBackgroundBottomDocument() { 
        return R.color.your_color;
    }
    @Override
    public Object getColorTextBottomDocument() { 
        return R.color.your_color;
    }
    @Override
    public Object getColorSilhouetteSuccess() { 
        return R.color.your_color;
    }
    @Override
    public Object getColorSilhouetteError() { 
        return R.color.your_color;
    }

    @Override
    public Object getColorProgressBar() { 
        return R.color.your_color;
    }
};
    
acessoBioBuilder.setTheme(unicoTheme);

Também é possível realizar personalizações de forma estática, no seu arquivo colors.xml adicione o seguinte código:

<color name="unico_color_background"> #YourColor </color> 
<color name="unico_color_silhouette_success"> #YourColor </color> 
<color name="unico_color_silhouette_error"> #YourColor </color> 
<color name="unico_color_silhouette_neutral"> #YourColor </color> 
<color name="unico_color_box_message"> #YourColor </color> 
<color name="unico_color_text_message"> #YourColor </color> 
<color name="unico_color_background_popup_error"> #YourColor 
<color name="unico_color_text_popup_error"> #YourColor </color> 
<color name="unico_color_background_button_popup_error"> #YourColor 
<color name="unico_color_text_button_popup_error"> #YourColor </color> 
<color name="unico_color_background_take_picture_button"> #YourColor </color> 
<color name="unico_color_icon_take_picture_button"> #YourColor </color> 
<color name="unico_color_background_bottom_document"> #YourColor </color> 
<color name="unico_color_text_bottom_document"> #YourColor </color> 
<color name="unico_color_button_cancel"> #YourColor </color> 
<color name="unico_color_progress_bar_capture"> #YourColor </color>
ATENÇÃO

Consulte os métodos de personalização disponíveis por modo de câmera.

CÂMERA DE DOCUMENTO COM CAPTURA MANUAL​

Neste modo de câmera é possivel personalizar:

Customização da Câmera de Documento com Captura Manual

CONFIGURAR CREDENCIAIS​

É necessário informar as credenciais geradas na API Key para que o SDK funcione, para isso utilize uma classe de configuração AcessoBioConfigDataSource:

AcessoBioConfigDataSource unicoConfig = new AcessoBioConfigDataSource() {

    @Override
    public String getHostKey() {
        return HOST_KEY;
    }

    @Override
    public String getHostInfo() {
        return HOST_INFO;
    }

    @Override
    public String getBundleIdentifier() {
        return BUNDLE_IDENTIFIER;
    }

    @Override
    public String getMobileSdkAppId() {
        return MOBILE_SDK_APP_ID;
    }

    @Override
    public String getProjectId() {
        return PROJECT_ID;
    }

    @Override
    public String getProjectNumber() {
        return PROJECT_NUMBER;
    }
};

IMPLEMENTAR LISTENERS PARA EVENTOS DA CÂMERA​

O método de abertura da câmera, que é chamado na próxima etapa, precisa saber o que fazer ao conseguir capturar uma imagem com sucesso ou ao ocorrer algum erro no processo. É necessário informar "o que fazer" ao método de abertura da câmera através da implantação de listeners que são chamados em situações de sucesso ou erro.

Através da configuração dos listeners, você pode especificar o que acontece em seu App em situações de erro (Método onErrorDocument) ou sucesso (Método onSuccessDocument) na captura de imagens.

O exemplo abaixo ilustra a configuração dos listeners, build e abertura da câmera:

iAcessoBioDocument cameraListener = new iAcessoBioDocument() {
    @Override
    public void onSuccessDocument(ResultCamera result) { }

    @Override
    public void onErrorDocument(ErrorBio errorBio) { }
};

unicoCheckCamera.prepareDocumentCamera(unicoConfig, new DocumentCameraListener() {
    @Override
    public void onCameraReady(UnicoCheckCameraOpener.Document cameraOpener) {
        cameraOpener.open(DocumentType.CNH, cameraListener);
    }

    @Override
    public void onCameraFailed(String message) {
        Log.e(TAG, message);
    }
});
IMPLEMENTAÇÃO DOS LISTENERS

A implementação destes métodos listeners deve ser feita através de uma instância da classe iAcessoBioDocument.

PREPARAR E ABRIR A CÂMERA​

É necessário criar uma instância do builder através do método build(). Este método é disponibilizado através do objeto gerado com a interface IAcessoBioBuilder e classe AcessoBio:

UnicoCheckCamera unicoCheckCamera = acessoBioBuilder.build();

O próximo passo é preparar a câmera utilizando o método prepareDocumentCamera() com o objeto retornado pelo builder (Nomeado como UnicoCheckCamera no exemplo acima).

O método prepareDocumentCamera() gera um objeto do tipo UnicoCheckCameraOpener.Document, que é utilizado para abrir a câmera com seu método open(), recebendo os parâmetros tipo de documento a ser capturado, sendo eles:

  • DocumentCameraType.CPF: Frame para captura da frente do CPF;
  • DocumentCameraType.CNH: Frame para captura da CNH aberta;
  • DocumentCameraType.CNH_FRENTE: Frame para captura da frente da CNH;
  • DocumentCameraType.CNH_VERSO: Frame para captura do verso da CNH;
  • DocumentCameraType.RG_FRENTE: Frame para captura da frente do RG;
  • DocumentCameraType.RG_VERSO: Frame para captura do verso do RG;
  • DocumentCameraType.None: Frame para captura de qualquer outro documento.

MÉTODO ONSUCCESSDOCUMENT​

Ao efetuar uma captura de imagem com sucesso, este método é invocado e retorna um objeto do tipo ResultCamera que é utilizado posteriormente na chamada das APIs REST: 

public void onSuccessDocument(ResultCamera result) { }

O objeto ResultCamera retorna 2 atributos: Base64 e Encrypted:

  • O atributo Base64 pode ser utilizado se quiser exibir uma prévia da imagem em seu app;
  • O atributo Encrypted deve ser enviado na chamada das APIs REST do Unico Check (detalhado na proxima seção).
Alerta

O atributo Encrypted é destinado estritamente ao envio da imagem através das APIs da Unico. Não se deve abrir e serializar esse atributo, pois suas características podem ser alteradas sem aviso prévio. Seu uso deve ser exclusivo nas interações com as APIs para garantir a integridade e segurança dos dados. A Unico não se responsabiliza por quaisquer danos decorrentes dessa prática, uma vez que as modificações podem ocorrer de maneira imprevista.

MÉTODO ONERRORDOCUMENT​

Ao ocorrer algum erro na captura de imagem, este método é invocado e retorna um objeto do tipo ErrorBio:

public void onErrorDocument(ErrorBio errorBio) { }
SAIBA MAIS

Sobre os tipos de ErrorBio na seção de Referências deste SDK.

CONVERSÃO DO BASE64 PARA BITMAP

Se for necessário converter o base64 para bitmap, a maneira padrão não funciona para o Android. É necessário realizar o split a partir da vírgula(,) para que funcione. Se quiser saber mais, leia o artigo How to convert a Base64 string into a Bitmap image to show it in a ImageView?.

CHAMAR AS APIS​

A captura das imagens é apenas a primeira parte da jornada. Após capturar a imagem, é necessário enviar o Encrypted gerado, para as APIs, selecionando um dos fluxos disponíveis detalhados em Fluxos.

Atenção

Por motivos de segurança, o intervalo entre a geração do Encrypted e o envio via um dos fluxos disponíveis deve ser de até no máximo 10 minutos. Envios feitos além deste período serão rejeitados automaticamente pela API.

Dúvidas?​

Não encontrou algo ou ainda precisa de ajuda? Se já é um cliente ou parceiro, pode entrar em contato através da Central de Ajuda.