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.

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.

CÂMERA DE SELFIE COM LIVENESS

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 DO LIVENESS

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

RECURSO DE POUCA E MUITA ILUMINAÇÃO DE LIVENESS

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.

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 com Liveness

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:

Java

unicoCheck.setLocale(LocaleTypes.EN_US);

Kotlin

unicoCheck.setLocale(LocaleTypes.EN_US)

COMO PERSONALIZAR O LIVENESS INTERATIVO COM SEU LOGOTIPO

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 seu logotipo no frame de captura do Liveness interativo.

Seu logotipo deve aparecer no rodapé da tela como mostrado a seguir:

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.

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.

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 e ambiente 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:

Java

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);
}

Kotlin

internal class MainActivity : AppCompatActivity() {

    private val callback = object : AcessoBioListener {
        override fun onErrorAcessoBio(errorBio: ErrorBio?) { }
    
        override fun onUserClosedCameraManually() { }
    
        override fun onSystemClosedCameraTimeoutSession() { }
    
        override fun onSystemChangedTypeCameraTimeoutFaceInference() { }
    }

    private val acessoBioBuilder: IAcessoBioBuilder = AcessoBio(this, callback)
}

CONFIGURAÇÃO DE AMBIENTES

Configure o ambiente que será utilizado na execução da SDK. Utilize o enumerado Environment que contém os seguintes enumerados:

Environment.PROD: para ambiente de Produção

Environment.UAT: para ambiente de Homologação

Veja como implementar no exemplo abaixo:

Java

    acessoBioBuilder.setEnvironment(Environment.UAT);

Kotlin

    acessoBioBuilder.setEnvironment(Environment.UAT);

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 Liveness, 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:

Java

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

Kotlin

val 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:

Java

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

Kotlin

val 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 LIVENESS

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:

Java

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); 

Kotlin

val unicoTheme = object: IAcessoBioTheme {

    override fun getColorBackground() = R.color.your_color
    override fun getColorBoxMessage() = R.color.your_color
    override fun getColorTextMessage() = R.color.your_color
    override fun getColorBackgroundPopupError() = R.color.your_color
    override fun getColorTextPopupError() = R.color.your_color
    override fun getColorBackgroundButtonPopupError() = R.color.your_color
    override fun getColorTextButtonPopupError() = R.color.your_color
    override fun getColorBackgroundTakePictureButton() = R.color.your_color
    override fun getColorIconTakePictureButton() = R.color.your_color
    override fun getColorBackgroundBottomDocument() = R.color.your_color
    override fun getColorTextBottomDocument() = R.color.your_color
    override fun getColorSilhouetteSuccess() = R.color.your_color
    override fun getColorSilhouetteError() = R.color.your_color 
    override fun getColorSilhouetteNeutral() = R.color.your_color
    override fun getColorProgressBar() = 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:

CÂMERA DE SELFIE COM CAPTURA INTELIGENTE

Neste modo de câmera é possivel personalizar:

CÂMERA DE SELFIE COM LIVENESS

Neste modo de câmera é possivel personalizar:

CÂMERA TRASEIRA COM CAPTURA MANUAL

Neste modo de câmera é possivel personalizar:

CÂMERA TRASEIRA COM CAPTURA INTELIGENTE

Neste modo de câmera é possivel personalizar:

CONFIGURAR CREDENCIAIS

É necessário informar a SDK Key conforme descrito em EMBARCANDO AS CREDENCIAIS EM SEU PROJETO.

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:

Java

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);
    }
});

Kotlin

val cameraListener: iAcessoBioSelfie = object : iAcessoBioSelfie {
    override fun onSuccessSelfie(result: ResultCamera?) {}

    override fun onErrorSelfie(errorBio: ErrorBio?) {}
}

unicoCheckCamera.prepareCamera(unicoConfig, object : CameraListener {
    override fun onCameraReady(cameraOpener: UnicoCheckCameraOpener.Camera?) {
        cameraOpener?.open(cameraListener)
    }

    override fun onCameraFailed(message: String?) {
        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.

Alerta

O base64 pode sofrer variações de tamanho de acordo com diversas variáveis, dentre elas, a qualidade dos aparelhos e das fotos geradas pelos mesmos e regras de negócio da Unico. Para não encontrar problemas em sua aplicação, não limite em sua lógica de programação ou sua infraestrutura o tamanho da string gerada pela SDK para o base64.

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.