Pular para o conteúdo principal

Captura de selfie

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 do motor biométrico.

Através deste guia, é possivel:

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

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 selfie contendo uma silhueta que ajuda o usuário a se posicionar de forma correta para a foto. A captura da selfie pode ser feita de cinco formas diferentes, cada forma com um modo de câmera diferente:

CÂMERA DE SELFIE COM CAPTURA MANUAL

Neste modo de câmera, existe uma silhueta de captura para auxiliar o usuário a posicionar o seu rosto corretamente. Após se posicionar corretamente, o usuário deve clicar no botão para realizar a captura da selfie.

Neste modo de câmera, a SDK não realiza nenhum tipo de validação do que está sendo capturado, se a imagem capturada não possuir um rosto biometricamente válido, o encrypted é recusado pelas APIs do backend do motor biométrico.

Camera de Selfie com Captura Manual

CÂMERA DE SELFIE COM CAPTURA INTELIGENTE

Neste modo de câmera, o rosto do usuário é identificado automaticamente através de algoritmos de visão computacional e ele recebe comandos para que se posicione de forma correta com o seu rosto centralizado na silhueta de captura. Após se posicionar corretamente, é realizada a captura da selfie automaticamente.

Por auxiliar o usuário a enquadrar seu rosto na silhueta de captura, essa opção pode diminuir problemas ao enviar o encrypted para as APIs do backend do motor biométrico.

Camera de Selfie com Captura Inteligente

CÂMERA DE SELFIE COM PROVA DE VIDA DA FACETEC

Neste modo de câmera, após centralizar o rosto na silhueta de captura, o usuário é instruído a realizar um simples movimento de aproximação do rosto para garantir que ele realmente está capturando a selfie naquele momento (Todo o processo é realizado com auxílio de algoritmos de visão computacional).

Por exigir a movimentação do usuário, este tipo de captura possui uma camada extra de segurança contra fraudes. Tal como na captura automática, a foto do rosto é capturada sem a necessidade do usuário pressionar um botão, desta forma existe uma tendência a diminuir problemas ao enviar o encrypted às APIs do backend do motor biométrico.

ATIVAÇÃO DA PROVA DE VIDA DA FACETEC

A ativação da funcionalidade pode ser verificada no portal do cliente, como explicado neste artigo.

RECURSO DE POUCA E MUITA ILUMINAÇÃO DA PROVA DE VIDA DA FACETEC

Este modo de câmera possui os recursos de pouca iluminação e muita iluminação, que são ativados automaticamente de acordo com o ambiente de captura.

Ambiente com pouca iluminação: O SDK detecta automaticamente que o usuário está em um ambiente com pouca luz e usa as APIs do dispositivo para iluminar a tela e fazer APENAS a transição das cores de fundo do frame de captura e silhueta de captura para branco. Este ajuste ilumina adequadamente o rosto do usuário e melhora a precisão e as taxas de sucesso.

Ambiente com muita iluminação: O SDK detecta automaticamente que o usuário está em um ambiente com muita luz e usa as APIs do dispositivo para escurecer a tela e fazer APENAS a transição das cores fundo do frame de captura e silhueta de captura para preto. Este ajuste escurece adequadamente o rosto do usuário e melhora a precisão e as taxas de sucesso.

Camera de Selfie com Prova de Vida da Facetec

PERSONALIZAR O IDIOMA

É possível configurar a experiência das mensagens informativas dos frames de captura alterando seu idioma. Utilize o enumerado LocaleTypes que contém os seguintes valores:

Observações:
  • 1- Este recurso só está disponível para câmera Smartlive com interação (Facetec)
  • 2- Pode ser necessário uma ativação remota para ser utilizado, caso deseje usar, por favor acionar o CSM da conta.
  • 3- Caso não seja configurado, por padrão o SDK utiliza o Português como idioma principal.
  • LocaleTypes.PT_BR: para Português(Brasil)
  • LocaleTypes.ES_MX: para Espanhol(México)
  • LocaleTypes.ES_ES: para Espanhol(Espanha)
  • LocaleTypes.EN_US: para Inglês(EUA)
  • Veja como implementar no exemplo abaixo:

    unicoCheck.setLocale(LocaleTypes.EN_US);

    Para uma experiência de autenticação mais associada a sua marca, você pode inserir e personalizar o logotipo em tempo real.

    • Adicione o arquivo de imagem na pasta drawable do seu app com o seguinte nome: unico_custom_footer_logo.

    Extensões permitidas: .jpg, .png e .svg.

    Observação

    Os nomes da pasta e do arquivo precisam estar corretos. Caso contrário a implementação não funciona.

    Após a conclusão dos passos, a personalização está pronta e você consegue visualizar sua logomarca no frame de captura do Liveness interativo.

    Sua logo deve aparecer no rodapé da tela como mostrado a seguir:

    Exemplo da Logo SDK Android

    CÂMERA TRASEIRA COM CAPTURA MANUAL

    Neste modo de câmera, existe uma silhueta de captura para auxiliar o colaborador a posicionar o dispositivo corretamente. Após posicionar corretamente, o colaborador deve clicar no botão para realizar a captura do rosto do usuário.

    Neste modo de câmera, a SDK não realiza nenhum tipo de validação do que está sendo capturado, se a imagem capturada não possuir um rosto biometricamente válido, o encrypted é recusado pelas APIs do backend do motor biométrico.

    LOJAS FÍSICAS

    Este modo de câmera deve ser utilizado EXCLUSIVAMENTE E APENAS em lojas físicas, ele necessita de um colaborador para realizar o processo de captura da foto do rosto do usuário.

    Camera Traseira com Captura Manual

    CÂMERA TRASEIRA COM CAPTURA INTELIGENTE

    Neste modo de câmera, o rosto do usuário é identificado automaticamente através de algoritmos de visão computacional e o colaborador recebe comandos para que posicione o dispositivo de forma correta com o rosto do usuário centralizado na silhueta de captura. Após posicionar corretamente, é realizada a captura da foto do rosto do usuário automaticamente.

    Por auxiliar o colaborador a enquadrar rosto do usuário na silhueta de captura, essa opção pode diminuir problemas ao enviar o encrypted para as APIs do backend do motor biométrico.

    LOJAS FÍSICAS

    Este modo de câmera deve ser utilizado EXCLUSIVAMENTE E APENAS em lojas físicas, ele necessita de um colaborador para realizar o processo de captura da foto do rosto do usuário.

    Camera Traseira com Captura Inteligente

    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.

    Este método é invocado sempre que qualquer erro de implementação ocorrer ao utilizar algum de nossos métodos:

    onErrorAcessoBio(ErrorBio errorBio)

    Ao ser invocado, o método recebe um parâmetro do tipo ErrorBio que contem detalhes do erro. Saiba mais sobre o tipo ErrorBio na seção de referências.

    Este método é invocado sempre quando o usuário fechar a câmera de forma manual, como por exemplo, ao clicar no botão "Voltar":

    onUserClosedCameraManually()

    Este método é invocado assim que o tempo máximo de sessão for atingido (Sem capturar nenhuma imagem):

    onSystemClosedCameraTimeoutSession()

    TEMPO MÁXIMO DA SESSÃO

    Pode ser configurado no builder através do método setTimeoutSession. Este método deve receber o tempo máximo da sessão em segundos. É possível alterar o tempo máximo de sessão do seu usuário ao utilizar a funcionalidade de detecção do rosto (Câmera de selfie com captura inteligente). Caso ele ultrapasse o tempo determinado em seu processo para capturar a foto, você pode apresentar alguma mensagem personalizável ou instrução ao usuário. O valor padrão é de 40 segundos e seu valor mínimo também é de 40 segundos.

    Este método é invocado assim que o tempo máximo para detecção do rosto de um usuário for atingido (Sem ter nada detectado). Neste caso, o modo de câmera é alterado automaticamente para o modo de captura manual (Sem a silhueta de captura inteligente):

    onSystemChangedTypeCameraTimeoutFaceInference()

    TEMPO MÁXIMO DE ESPERA DA CAPTURA INTELIGENTE

    O tempo máximo de captura ao utilizar a detecção do rosto (Câmera de selfie com captura inteligente) é de 13 segundos. Se o usuário encontra alguma dificuldade para captura da foto através da detecção do rosto e ultrapasse o tempo determinado em seu processo, a captura é alterada automaticamente para a manual, tendo como objetivo facilitar a ação para o usuário (TimeoutToFaceInference).

    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.

    CONFIGURAR O MODO DA CÂMERA

    Como explicado anteriormente, existem cinco modos de câmeras de captura disponíveis. Se não estiver utilizando o modo Câmera de selfie com prova de vida da FaceTec, nesta etapa você pode escolher entre os modos: Câmera de selfie com captura manual, Câmera de selfie com captura inteligente, Câmera traseira com captura manual ou Câmera traseira com captura inteligente.

    O SDK tem configurado e habilitado por padrão o enquadramento inteligente e a captura automática. Para utilizar a câmera de selfie com captura manual, desabilite ambas funcionalidades através dos métodos setAutoCapture e setSmartFrame.

    Os exemplos a seguir demonstram como você pode configurar cada um dos modos de câmera:

    CÂMERA DE SELFIE COM CAPTURA MANUAL (MODO MANUAL)

    Por padrão, o SDK possui o enquadramento inteligente e a captura automática habilitados. Neste caso, para utilizar o modo manual ambas configurações relacionadas a Smart Camera devem ser desligadas através dos métodos setAutoCapture e setSmartFrame:

    UnicoCheckCamera unicoCheckCamera = acessoBioBuilder
    .setAutoCapture(false)
    .setSmartFrame(false)
    .build();
    DICA SOBRE O SMARTFRAME

    Mesmo usando o modo de captura manual, é possível utilizar o Smart Frame. Neste caso, é exibida a sinalização colorida na silhueta, para identificar o enquadramento do rosto e para então habilitar o botão. Para isto, basta configurar setAutoCapture(false) e setSmartFrame(true).

    CÂMERA DE SELFIE COM CAPTURA INTELIGENTE (SMART CÂMERA)

    Por padrão, o SDK possui o enquadramento inteligente e a captura automática habilitados. Se utilizar este modo de câmera, não será necessário alterar nenhuma configuração.

    Se as configurações da câmera estiverem sido alteradas previamente em seu App, é possível restaurá-las através dos métodos setAutoCapture e setSmartFrame:


    UnicoCheckCamera unicoCheckCamera = acessoBioBuilder
    .setAutoCapture(true)
    .setSmartFrame(true)
    .build();

    ATENÇÃO

    Não é possível implementar o método setAutoCapture(true) com o método setSmartFrame(false), ou seja, não é possível manter a captura automática sem o Smart Frame, pois é ele quem realiza o enquadramento inteligênte.

    DICA SOBRE A CÂMERA DE SELFIE COM PROVA DE VIDA DA FACETEC

    Se estiver utilizando esse modo, a configuração do modo de câmera passa a ser irrelevante, pois este modo oferece uma experiência pré-definida que não pode ser alterada.

    No entanto, é sugerido que configure um tipo de câmera em seu builder (como descrito nesta etapa), pois se desabilitar o modo Liveness com interação na instância e gerar um novo JSON, não precisa alterar o seu código.

    DICA SOBRE O USO DA CÂMERA TRASEIRA

    Se desejar utilizar esse modo, é necessário que nas configurações da APIKey, o campo Tipo de câmera na SDK esteja selecionado com a opção Traseira.

    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>
    <color name="unico_color_text_popup_error"> #YourColor </color>
    <color name="unico_color_background_button_popup_error"> #YourColor </color>
    <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 SELFIE COM CAPTURA MANUAL

    Neste modo de câmera é possivel personalizar:

    Customização da Camera de Selfie com Captura Manual

    CÂMERA DE SELFIE COM CAPTURA INTELIGENTE

    Neste modo de câmera é possivel personalizar:

    Customização da Camera de Selfie com Captura Inteligente

    CÂMERA DE SELFIE COM PROVA DE VIDA DA FACETEC

    Neste modo de câmera é possivel personalizar:

    Customização da Camera de Selfie com Prova de Vida da Facetec 1Customização da Camera de Selfie com Prova de Vida da Facetec 2Customização da Camera de Selfie com Prova de Vida da Facetec 3Customização da Camera de Selfie com Prova de Vida da Facetec 4

    CÂMERA TRASEIRA COM CAPTURA MANUAL

    Neste modo de câmera é possivel personalizar:

    Customização da Camera Traseira com Captura Manual

    CÂMERA TRASEIRA COM CAPTURA INTELIGENTE

    Neste modo de câmera é possivel personalizar:

    Customização da Camera Traseira com Captura Inteligente

    CONFIGURAR CREDENCIAIS

    É necessário informar as credenciais geradas na API Key para que o SDK funcione, para isso utilize a 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 onErrorSelfie) ou sucesso (Método onSuccessSelfie) na captura de imagens.

    MUDANÇAS DA NOMENCLATURA PARA AS VERSÕES INFERIORES A 4.2.1

    Mudanças ocorridas:

    • Do método prepareCamera que antes era prepareSelfieCamera;
    • Da classe CameraListener que antes era SelfieCameraListener;
    • Do objeto UnicoCheckCameraOpener.Camera que antes era UnicoCheckCameraOpener.Selfie.

    Para a configuração dos listeners, é necessário implementar:

    iAcessoBioSelfie cameraListener = new iAcessoBioSelfie() {
    @Override
    public void onSuccessSelfie(ResultCamera result) { }

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

    unicoCheckCamera.prepareCamera(unicoConfig, new CameraListener() {
    @Override
    public void onCameraReady(UnicoCheckCameraOpener.Camera cameraOpener) {
    cameraOpener.open(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 iAcessoBioSelfie.

    PREPARAR E ABRIR A CÂMERA

    Para seguir com a abertura da câmera, primeiro é necessário prepará-la utilizando o método prepareCamera. Este método recebe como parâmetro a implementação da classe CameraListener, a classe ou o JSON com as credenciais, gerado nessa etapa.

    Quando a câmera estiver preparada, é disparado o evento onCameraReady, que recebe como parâmetro um objeto do tipo UnicoCheckCameraOpener.Camera.

    É necessário sobrescrever este método, efetuando a abertura da câmera com o objeto recebido através do método open(). O método open() deve receber como parâmetro os listeners configurados nos passos acima.

    MÉTODO ONSUCCESSSELFIE

    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 onSuccessSelfie(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.
    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 ONERRORSELFIE

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

    public void onErrorSelfie(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.