Pular para o conteúdo principal

Captura de Selfie

Este guia foi elaborado para ajudá-lo a implementar o SDK Web de forma rápida e fácil. São disponibilizados conceitos básicos, exemplos de implementação dos SDKs e também 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 Web 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 três formas, sendo elas:

CAPTURA MANUAL​

Neste tipo de experiência existe um frame de captura para auxiliar o usuário a posicionar sua face corretamente. Após se posicionar corretamente, o usuário deve clicar em um botão para capturar a imagem.

O SDK não efetua nenhum tipo de validação do que está sendo capturado. Caso a imagem capturada não possua uma face biométricamente válida, o o encrypted é recusado pelas APIs do motor de biometria.

Captura Manual

CAPTURA AUTOMÁTICA​

Neste tipo de experiência, a face do usuário é identificada automaticamente através de algoritmos de visão computacional e ele é auxiliado para que se posicione de forma correta dentro da área de captura. Após se posicionar corretamente, a imagem é capturada de forma automática.

Por ajudar o usuário a enquadrar sua face na área de captura, esta opção pode diminuir problemas ao enviar o encrypted às APIs do motor biométrico.

Captura Manual

LIVENESS COM INTERAÇÃO​

Neste tipo de experiência o usuário é instruído a realizar alguns movimentos simples durante a captura, que são acompanhados por algoritmos de visão computacional com o intuito de garantir que ele está tirando foto naquele momento.

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 imagem é 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 com interação

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

IMPLEMENTAÇÃO​

Seguindo este passo-a-passo, você tem todo o potencial do SDK embarcado em sua aplicação Web.

  1. INICIALIZAR O SDK​

    Como primeiro passo, você deve efetuar 3 passos simples em seu projeto:

    Instancie um novo Builder:

    const unicoCameraBuilder = new UnicoCheckBuilder();

    Especifique o caminho dos arquivos adicionais (caso adicionados em seu projeto):

    Não é mais obrigatório embarcar os recursos adicionais em sua aplicação caso use o SDK com Liveness Interativo

    A partir da versão 3.18.0, para que o SDK busque automaticamente os recursos adicionais basta que o método setResourceDirectory não seja implementado e as configurações de CSP para uso do SDK sejam aplicadas corretamente.

    unicoCameraBuilder.setResourceDirectory("/resources");

    Especifique o caminho dos arquivos dos modelos de IA, caso utilize a funcionalidade de Câmera Inteligente

    unicoCameraBuilder.setModelsPath("https://meusite.com.br/models");

  2. CONFIGURAÇÃO DE IDIOMAS DA EXPERIÊNCIA DE CAPTURA​

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

    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:

    import {
      ...
      UnicoCheckBuilder,
      LocaleTypes
      ...
    } from "unico-webframe"

    unicoCameraBuilder.setLocale(LocaleTypes.EN_US);
    Configuração padrão

    Caso não seja configurado, por padrão o SDK Web utiliza o Português como idioma principal

    Observação

    Caso queira customizar as strings remotamente entre em contato com o CSM da conta;

  3. CONFIGURAÇÃO DE AMBIENTES​

    É possível configurar o ambiente que será utilizado na execução da SDK. Utilize o enumerado SDKEnvironmentTypes que contém os seguintes enumerados:

    SDKEnvironmentTypes.PROD: para ambiente de Produção

    SDKEnvironmentTypes.UAT: para ambiente de Homologação

    Veja como implementar no exemplo abaixo:

    import {
      ...
      UnicoCheckBuilder,
      SDKEnvironmentTypes
      ...
    } from "unico-webframe"

    unicoCameraBuilder.setEnvironment(SDKEnvironmentTypes.UAT);

  4. CONFIGURAR O TAMANHO DO FRAME​

    Passo não requerido para modo Liveness com interação

    Este passo só é necessário caso você não esteja utilizando o Liveness com interação, pois neste modo o SDK renderiza um frame que ocupa todo o espaço da tela e se ajusta automaticamente.

    Caso não esteja utilizando Liveness com interação, É RECOMENDADO que você configure o tamanho do frame dentro de sua aplicação, a fim de otimizar a área de captura dentro de seu WebApp. Confira abaixo como fazer esta configuração para Web Desktop ou Mobile.

    Dica

    Muitas vezes o funcionamento do frame pode ser afetado por alguns design-systems que possuam algum tipo de grid-system como, por exemplo, bootstrap ou material-ui. Para minimizar este risco, certifique-se de posicionar o frame (id="box-camera") em algum lugar do código que não herde regras indesejadas de css.

    Nas versões Web Desktop, é possível restringir o tamanho do frame para que o mesmo não utilize toda a dimensão de seu WebApp. Para isto, basta envolver o frame (id="box-camera") em outra tag html, como no exemplo abaixo:

    <div class="container">
      <div id="box-camera"></div>
    </div>

    Idealmente, você deve tentar manter uma proporção adequada entre altura e largura, o que facilita o enquadramento da face do usuário. Abaixo um exemplo:

    .container {
      width: 800px;
      height: 600px;
      position: relative;
    }

    Seguindo o exemplo acima, o frame respeita o tamanho do elemento "pai", neste caso representado pelo container. Desta forma, você tem a flexibilidade para implementar o frame da forma mais conveniente para sua aplicação (Como em um modal, por exemplo).

    Testando diversos tamanhos de tela

    Testes alterando o tamanho da tela através do modo desenvolvedor de seu browser não funcionam. É recomendado que este tipo de teste seja feito alterando o tamanho da janela de seu browser.

  5. CONFIGURAR LAYOUT DO FRAME​

    Esta é uma etapa opcional, porém muito recomendada.

    Para efetuar a customização do frame de captura por meio do Theme Builder basta gerar uma instância da classe UnicoThemeBuilder e invocar os métodos que customizam cada uma das propriedades do frame de captura, como exemplificados a seguir:

    const unicoTheme = new UnicoThemeBuilder()
    .setColorSilhouetteSuccess("#0384fc")
    .setColorSilhouetteError("#D50000")
    .setColorSilhouetteNeutral("#fcfcfc")
    .setBackgroundColor("#dff1f5")
    .setColorText("#0384fc")
    .setBackgroundColorComponents("#0384fc")
    .setColorTextComponents("#dff1f5")
    .setBackgroundColorButtons("#0384fc")
    .setColorTextButtons("#dff1f5")
    .setBackgroundColorBoxMessage("#fff")
    .setColorTextBoxMessage("#000")
    .setColorCancelButton("#0384fc")
    .setColorProgressBar("#0384fc")
    .setHtmlPopupLoading(`<div style="position: absolute; top: 45%; right: 50%; transform:
    translate(50%, -50%); z-index: 10; text-align: center;">Carregando...</div>`)
    .build();

    Após a geração do objeto de tema, conforme exemplificado acima, ele dever ser passado como parâmetro para o método setTheme do builder unicoCameraBuilder

    unicoCameraBuilder.setTheme(unicoTheme);

  6. 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.

    Passo 1

    Em uma pasta pública (mesmo local onde são adicionadas as pastas models e resources) do projeto, adicione uma pasta com o nome unico_custom_footer_logo. Na pasta unico_custom_footer_logo adicione o arquivo do seu logotipo no formato .svg com o nome unico_custom_footer_logo.svg

    Observação

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

    Passo 2

    Referencie o nome da pasta criada no build do SDK através do método setCustomFooterLogoDirectory, por exemplo:

      unicoCameraBuilder.setCustomFooterLogoDirectory('/unico_custom_footer_logo')

    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.

  7. IMPLEMENTAR AS FUNÇÕES DE CALLBACK​

    Um dos objetos que deve ser passado como parâmetro ao método responsável por renderizar o frame de captura é o de callback. Este objeto deverá conter funções de callback para casos de sucesso e erro, como exemplificados abaixo.

      const callback = {
        on: {
          success: (obj) => {
            console.log(obj.base64);
            console.log(obj.encrypted);        
          },
          error: (error) => {
            console.error(error)
            //confira na aba "Referências" sobre os erros possíveis
          }
        }
      };

    Este objeto é obrigatório e caso não seja corretamente implementado (contemplando todos os eventos de success ou error) gera uma exceção, que caso não tratada, é exibida no console do usuário.

    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.

    Para mais detalhes sobre os códigos de erro retornados pelo SDK, consulte este guia.

  8. CONFIGURAR MODO DE CAPTURA E INICIAR A CÂMERA​

    Para iniciar a câmera com as configurações feitas até aqui, é preciso criar uma instância do builder através do método build().

    const unicoCamera = unicoCameraBuilder.build();

    Em seguida, com a câmera "montada", deve-se configurar o modo de captura da camera.

    Caso não esteja utilizando o modo Liveness com interação, neste passo você pode escolher entre o modo de captura Manual ou Automático.

    Dica

    Caso você esteja utilizando o modo Liveness com interação, a configuração do tipo de câmera passa a ser irrelevante, pois este modo oferece uma experiência pré-definida que não pode ser alterada.

    No entanto, é recomendado que você configure um tipo de câmera em seu builder (como descrito neste passo), pois caso você desabilite o modo Liveness com interação em seu portal do cliente (e gere um novo JSON), você não precisa alterar seu código.

    A preparação da câmera será efetuada a partir do método prepareSelfieCamera(), disponibilizado a partir do builder. Este método recebe 2 parâmetros:

    • O arquivo JSON com suas credenciais (gerado através deste guia);
    • Modo de câmera desejado, sendo eles:
      • SelfieCameraTypes.NORMAL para o modo de câmera normal;
      • SelfieCameraTypes.SMART para o modo de câmera inteligênte;

    Este método gera uma promise que ao ser resolvida, devolve um objeto que é utilizado para efetivamente abrir a câmera através do método open, que recebe como parâmetro as funções de callback configuradas neste passo.

    Vale lembrar

    Para otimizar a abertura da câmera é possível separar as chamadas dos métodos prepareSelfieCamera() e open(). Veja um exemplo nesta POC feita em React com TypeScript.

    Captura manual​

    Caso deseje utilizar a captura manual, passe o parâmetro Unico.SelfieCameraTypes.NORMAL para o método prepareSelfieCamera.

    Usando a classe UnicoConfig:

      const config = new UnicoConfig()
        .setProjectNumber("<YOUR_PROJECT_NUMBER>")
        .setProjectId("<YOUR_PROJECT_ID>")
        .setMobileSdkAppId("<YOUR_MOBILE_SDK_APP_ID>")
        .setHostname("<YOUR_HOSTNAME>")
        .setHostInfo("<YOUR_HOST_INFO>")
        .setHostKey("<YOUR_HOST_KEY>");
        
      unicoCamera.prepareSelfieCamera(
        config, 
        SelfieCameraTypes.NORMAL
      ).then(cameraOpener => {
        cameraOpener.open(callback);
      }).catch(error => {
        console.error(error);
        // confira na aba "Referências" sobre os erros possíveis
      });

    Usando o arquivo json:

      unicoCamera.prepareSelfieCamera(
        "/services.json", 
        SelfieCameraTypes.NORMAL
      ).then(cameraOpener => {
        cameraOpener.open(callback);
      }).catch(error => {
        console.error(error);
        // confira na aba "Referências" sobre os erros possíveis
      });

  9. CONFIGURAR MODO DE CAPTURA DO LIVENESS INTERATIVO EM IFRAME'S​

    É possível utilizar o SDK Web com Liveness Interativo embarcado em um iFrame, para isso é preciso realizar uma implementação semelhante a seção anterior na preparação da câmera.

    A preparação da câmera será efetuada através do método prepareSelfieCameraForIFrame(), também disponibilizado a partir do builder. Este método recebe os mesmos parâmetros do prepareSelfieCamera():

    const unicoCamera = unicoCameraBuilder.build();

    const config = new UnicoConfig()
      .setProjectNumber("<YOUR_PROJECT_NUMBER>")
      .setProjectId("<YOUR_PROJECT_ID>")
      .setMobileSdkAppId("<YOUR_MOBILE_SDK_APP_ID>")
      .setHostname("<YOUR_HOSTNAME>")
      .setHostInfo("<YOUR_HOST_INFO>")
      .setHostKey("<YOUR_HOST_KEY>");

      unicoCamera.prepareSelfieCameraForIFrame(
        config, 
        SelfieCameraTypes.SMART
      ).then(cameraOpener => {
        cameraOpener.open(callback);
      }).catch(error => {
        console.error(error);
        // confira na aba "Referências" sobre os erros possíveis
      });
    COMPORTAMENTO DO PREPARE CAMERA

    O método prepareSelfieCameraForIFrame() só funciona se a implementação estiver em um iFrame, o uso fora de um iFrame resulta no erro 73724. Assim como usar o método prepareSelfieCamera() dentro de um iFrame resulta no erro 73724.

    IMPLEMENTAÇÃO DO ELEMENTO IFRAME​

    Para que a captura funcione corretamente é necessário implementar o elemento <iframe> como no exemplo abaixo: 

    <iframe allow="fullscreen;camera;geolocation" allowFullScreen src="your_app_url"></iframe>
    COMPORTAMENTO EM TELA CHEIA​

    Para executar a captura é necessário estar no modo tela cheia do browser para que o SDK possa se redimensionar automaticamente. Sendo assim, ao executar a captura, o SDK apresenta uma tela solicitando a abertura do frame em modo tela cheia. Veja no exemplo a seguir:

    Solicitação do SDK para modo tela cheia

    Após permitir o uso de tela cheia, o frame de captura abrirá normalmente:

    Frame de captura
    COMPORTAMENTO EM IPHONES

    A Apple impede o uso de APIs de tela cheia especificamente em iPhones (iPads são aceitáveis). Sendo assim, para capturas em iPhones, é necessário configurar o posicionamento do iFrame por conta própria.

  10. 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.