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

SMARTLIVE COM INTERAÇÃO FACETEC​

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 Smartlive com interação FaceTec

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

    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​

    Configuração padrão

    Caso não seja configurado, por padrão o SDK Web utiliza o ambiente de produção.

    É 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 Smartlive com interação FaceTec

    Este passo só é necessário caso você não esteja utilizando o Smartlive com interação FaceTec, 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 Smartlive com interação FaceTec, É 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. 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 da sua logo 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 sua logomarca 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.

    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 Smartlive com interação FaceTec, neste passo você pode escolher entre o modo de captura Manual ou Automático.

    Dica

    Caso você esteja utilizando o modo Smartlive com interação FaceTec, 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 FaceTec 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.