Documentação
Clearsale a part of Serasa: você está na página certa.
Start typing to search…

Web

Passo a Passo

O SDK JavaScript do AllowMe permite:

  • Realizar capturas de fingerprint dos usuários para a validação de transações pelo seu backend.
  • Registrar eventos para acompanhamento do fluxo de navegação e ações.
  • Capturar e tipificar documentos para análise automatizada e/ou manual.

Este início rápido mostra como carregar o JavaScript do AllowMe e realizar estas ações.


❗️

Nota importante sobre a funcionalidade de Captura de Documentos

A Captura de Documentos ainda é uma versão beta e a integração da versão beta para a stable ainda poderá sofrer modificações (Breaking Change)

1. Carregar e Inicializar o SDK

O SDK do AllowMe não possui arquivos ou dependências que precisam ser baixadas e anexadas ao projeto. É necessário apenas incluir um pequeno trecho de código nos seus arquivos HTML (como index.html) que carrega o SDK de forma assíncrona.

O seguinte trecho de código, com as duas tags <script>, carrega e inicializa o SDK. Recomendamos que seja adicionado na tag <head> do seu HTML.

  • Básico
  • Completo
  • React
  • Vue

Configure as variáveis de ambiente VUE_APP_ALLOWME_API_KEY e VUE_APP_SDK_JS_URL de acordo com seu ambiente (stage ou prod). Referência

<html>
  <head>
    <script>
      window.alwmAsyncInit = () => Alwm.init({
        apiKey: '<%= VUE_APP_ALLOWME_API_KEY %>',
      });
    </script>
    <script async defer src="<%= VUE_APP_SDK_JS_URL %>" type="text/javascript">
    </script>
...

📘

TIP

A apikey-integração-web deve ser informada pelo AllowMe. Ela é exclusiva para o uso no SDK JavaScript e diferente para o ambiente de Homologação e para o ambiente de Produção.

❗️

Nota importante sobre a URL

Como o JavaScript de integração é gerado de forma dinâmica, não é possível hospedar no servidor do cliente. No exemplo acima estamos considerando o ambiente de Homologação. Para utilizar o ambiente de Produção é necessário alterar para a URL abaixo:

https://sdk-js.allowme.com.br/v2/allowme.min.js


Explicação

No exemplo de código acima, é definida a função window.alwmAsyncInit, que é chamada automaticamente ao fim do carregamento do arquivo .js.

Na implementação da função, para realizar a inicialização do SDK com sua API key, deve-se chamar o método:

Alwm.init({ apiKey: '<apikey-integração-web>' });

O método retorna uma Promise (opens new window)que pode ser verificada com:

  • .then() - inicializou com sucesso; e/ou
  • .catch(error) - ocorreu um erro ao inicializar o SDK. Verifique o valor de error para obter mais detalhes.
  • Consulte também o exemplo completo de inicialização.

2.Capturas de Fingerprint

O fingerprint do browser do usuário deve ser capturado com o método Alwm.collect() e enviado ao seu backend, junto com as informações necessárias para realizar sua transação, para validação de fluxos que você considera importante, tais como: login, troca de senha, atualização de dados pessoais etc.

Coletas precisam ser realizadas para que as transações possam ser validadas pelo seu backend e comprovarem ou não a autenticidade do usuário.

  • Básico
  • Completo
const fingerprint = await Alwm.collect()

Explicação

O método retorna uma Promise<String> (opens new window), com um valor do tipo String contendo o fingerprint criptografado, que pode ser obtido com:

  • await Alwm.collect() - em caso de sucesso, retorna a String do fingerprint; ou
  • .then(fp => fingerprint = fp) - captura com sucesso, com fp sendo a String e atribuindo o valor à variável fingerprint; e
  • .catch(error) - ocorreu um erro ao realizar a captura. Verifique o valor de error para obter mais detalhes.

O valor de fingerprint deve ser enviado ao seu backend na validação das transações.O exemplo no final desta página mostra o uso em uma tela de login

Exemplo - Tela de Login

O seguinte exemplo demonstra como a captura de fingerprint pode ser integrada à um formulário de login.

...
 <body>

  <!-- Exemplo de uma tela de login com o envio do formulário via função "enviarFormularioLogin()" -->
  <form id="my_form_id" onsubmit="return enviarFormularioLogin()">
    <input type="text" id="login" />
    <input type="password" id="password" />
  </form>

  <script type="text/javascript">

    // O fingerprint deve ser enviado para o backend do cliente, no momento em que o formulário for submetido.
    function enviarFormularioLogin() {
      Alwm.collect('login').then(function (fingerprint) {
        // O fingerprint é retornado pela Promise.

        // Enviar os dados de login para o seu backend, junto com o Fingerprint do AllowMe.
        // Exemplo:
        // $.ajax({
        //   method: "POST",
        //   url: "login",
        //   data: { 
        //     login: $('#login').val(), 
        //     password: $('#password').val(),
        //     fingerprint: fingerprint,
        //   },
        // });
      });
    }
  </script>
 </body>
...

📘

TIP

Agora que você já inicializou o SDK e realizou uma captura, o próximo passo é validar a transação no seu backend.

SDK Js Biometria Facial


Agora que você já está com o setup inicial pronto, vamos aprender como usar o AllowMeSDK Biometria Facial! 😉

Utilizar as URLs da FaceTec

❗️

Nota importante sobre a URL

URL de Homologação: https://stage-sdk-js.allowme.com.br/v3/facetec/allowme.min.js URL de Produção: https://sdk-js.allowme.com.br/v3/facetec/allowme.min.js

Versionamento, o SDK pode ser versionado em com MAJOR, MINOR ou PATCH.

📘

TIP

Nós recomendamos que você utilize o MINOR version, para que não seja necessário atualizar a URL a cada nova versão do SDK. MAJOR: https://sdk-js.allowme.com.br/v3/facetec/allowme.min.js MINOR: https://sdk-js.allowme.com.br/v3.0/facetec/allowme.min.js PATCH: https://sdk-js.allowme.com.br/v3.0.1/facetec/allowme.min.js

📘

TIP

O SDK JS Biometria Facial é o nosso produto responsável por validar a identidade do usuário, aumentando a segurança do seu negócio ao mesmo tempo em que diminui a fricção. Verificamos se a foto é válida e se trata de uma pessoa real ou se é uma tentativa de falsificação, checando se o usuário corresponde ao CPF informado durante o cadastro.


Para realizar a integração da Biometria Facial do SDK no seu projeto, é só seguir os passos abaixo! 😄

1. Inicializando a biometria facial

Para inicializar a Biometria facial é necessário já ter carregado e inicializado o SDK, como demonstrado aqui Carregar e Inicializar o SDK, fornecendo a sua chave de API.

📘

TIP

Caso ainda não possua uma chave de API do allowMe, entre em contato com nosso suporte via [email protected]

1.1 Processo de Configuração da Biometria

A configuração da Biometria Facial é realizada através do método Alwm.setup() que tem como parâmetros:

Elemento html onde será carregado o objeto AllowMe de Biometria Facial (ex.: div, span, etc). Este objeto é responsável por carregar e mostrar a câmera que captura as imagens do usuário.

Opções de customização da biometria. É possível customizar o layout do objeto AllowMe de Biometria Facial de forma que a tipografia e as cores sigam a mesma identidade visual do seu aplicativo. Esta customização é opcional, tendo em vista que caso não seja passado nenhuma customização a biometria trabalhará com valores padrões. Os recursos de áudio, imagem e etc podem ser baixados diretamente no repositório sdk-facetec-browser

Segue abaixo as possíveis customizações da Biometria Facial:

📘

TIP

Por padrão, a versão do SDK da FaceTec carregada será a disponível em https://facetec.allowme.com.br/v9.7. No entanto, se necessário, você pode especificar uma versão diferente utilizando os atributos de CDN ou resources, images e audios.

const customOptions = {
    // Diretório dos recursos do SDK da FaceTec (resources, FaceTec_images e VocalGuidance_Audio_files)
    faceTecSdkCdnUrl: "https://stage-facetec.allowme.com.br/v9.7.44",
    
    // Diretório dos recursos utilizados na customização
    resourcesDirectory: "facetec-sdk/FaceTecSDK.js/resources",

    // Diretório root com as imagens que podem ser utilizadas na customização
    imagesDirectory: "facetec-sdk/FaceTec_images",

    // Diretório root com as áudios que podem ser utilizadas na customização
    audiosDirectory: "facetec-sdk/Vocal_Guidance_Audio_Files",

    wizard: {
        // Boleano que controla se a tela de wizard será apresentada
        enabled: true,
        
        // Cor do Título da tela Wizard
        titleColor: '#2a5595',
        
        // Alinhamento do Título da tela Wizard
        titleAlign: 'left',

        // Boleano que controla se o botão de sair será apresentado
        buttonCloseEnabled: true,

        // Cor do Texto do botão
        buttonTextColor: '#ffffff',
        
        // Cor do Background do botão
        buttonBackgroundNormalColor: '#2a5595',
        
        // Cor do Botão no momento em que estiver em Highlight (com o mouse sobre o botão)
        buttonBackgroundHighlightColor: '#77127b',
        
        // Cor do Botão desativado
        buttonBackgroundDisabledColor: '#5e6976',
        
        instructionsScreen: {
            // Cor de Backgrounda da logo
            logoBackgroundColor: '#e1e4ef',
            
            // Cor dos Ícones das instruções
            iconBackgroundColor: '#2a5595',
            
            // Cor do Texto das instruções
            itemColor: '#4b5563'
        },
    },

    faceTecCustomization: {
        // Imagem Customizada que irá ser mostrada no momento de iniciar a captura
        appLogo: undefined, 

        // Cor de Background no momento que a Biometria Facial estiver sendo carregada
        loadingBackgroundColor: "#0000ff",

        // Cor de Foreground na tela de Orientação
        guidanceForegroundColor: "#1d4f91",

        // Cor da Borda da imagem na tela de retry
        guidanceRetryScreenImageBorderColor: "#1d4f91",

        // Cor do Traço oval da tela de retry
        guidanceRetryScreenOvalStrokeColor: "#1d4f91",

        // Cor de Foreground na tela de seleção
        idScanSelectionScreenForegroundColor: "#1d4f91",

        // Cor do Botão na tela de scan
        idScanButtonBackgroundNormalColor: "#1d4f91",

        // Cor do Botão na tela de scan no momento em que estiver em Highlight (com o mouse sobre o botão)
        idScanButtonBackgroundHighlightColor: "#1d4f91",
        
        // Cor do Texto na tela de Review
        idScanReviewScreenTextBackgroundColor: "#1d4f91",
        
        // Cor do Traço na tela de Captura
        idScanCaptureFrameStrokeColor: "#1d4f91",
        
        // Cor do Borda do Frame
        frameBorderColor: "#1d4f91",

        // Cor de texto no momento do carregamento da Biometria Facial
        loadingTextColor: "#585858",

        // Fonte do texto no momento do carregamento da Biometria Facial
        initialLoadingFont: "Roboto, sans-serif",

        // Boleano que controla se o botão de Cancelar deve aparecer
        cancelButton: true,

        // Fonte do botão Inicial
        initialButtonFont: "Roboto, sans-serif",

        // Cor do Botão
        buttonNormalColor: "#002DD1",

        // Cor do Botão no momento em que estiver em Highlight (com o mouse sobre o botão)
        buttonHighlightColor: "#1d4f91",

        // Cor do Botão desabilitado
        buttonDisabledColor: "#cccccc",

        // Cor do Texto do Botão
        buttonTextNormalColor: '#ffffff',

        // Cor do Texto do Botão no momento em que estiver em Highlight (com o mouse sobre o botão)
        buttonTextHighlightColor: '#ffffff',

        // Cor do Texto do Botão desabilitado
        buttonTextDisabledColor: '#ffffff',

        // Cor da borda do Botão
        buttonBorderColor: "transparent",

        // Tamanho da borda do Botão
        buttonBorderWidth: "0px",

        // Tamanho das bordas arredondadas do Botão
        buttonBorderRadius: "20px",

        // Tamanho das bordas arredondadas do Botão de tentar novamente (Retry)
        retryScreenImageBorderWidth: "2px",

        // Cor de fundo em caso de sucesso
        successBackgroundColor: "#09DEA1",

        // Cor de fundo da animação em caso de sucesso
        resultAnimationSuccessBackgroundImage: "",

        // Cor da barra de progresso no momento do envio das imagens
        uploadProgressFillColor: "#375AD0",

        // Cor da fundo no momento do feedback
        feedbackBackgroundColor: "rgba(45, 53, 73, 0.9)",

        // Cor do texto no momento do feedback
        feedbackTextColor: "#fff",

        // Fonte do texto no momento do feedback
        feedbackTextFont: "Roboto, sans-serif",

        // Tamanho das bordas no momento do feedback
        feedbackCornerRadius: "8px",

        // Tamanho das sombras no momento do feedback
        feedbackShadow: "0px 6px 12px black",

        // Cor do contorno onde a imagem da Biometria Facial será mostrada ao usuário
        ovalStrokeColor: "transparent",

        // Cor do contorno do progresso onde a imagem da Biometria Facial será mostrada ao usuário
        ovalProgressColor1: "#1d4f91",

        // Cor do contorno secundária do progresso onde a imagem da Biometria Facial será mostrada ao usuário
        ovalProgressColor2: "#1d4f91",

        // Fonte do título da tela quando a Biometria Facial tiver finalizado o processo
        readyScreenHeaderFont: "Roboto, sans-serif",

        // Cor do título da tela quando a Biometria Facial tiver finalizado o processo
        readyScreenHeaderTextColor: "#585858",

        // Fonte do subtítulo da tela quando a Biometria Facial tiver finalizado o processo
        readyScreenSubtextFont: "Roboto, sans-serif",

        // Cor do subtítulo da tela quando a Biometria Facial tiver finalizado o processo
        readyScreenSubtextColor: "#585858",

        // Fonte do título que é mostrado ao usuário quando a tela de Retentativa for mostrada na Biometria Facial
        retryScreenHeaderFont: "Roboto, sans-serif",

        // Cor do título que é mostrado ao usuário quando a tela de Retentativa for mostrada na Biometria Facial
        retryScreenHeaderTextColor: "#585858",

        // Fonte do subtítulo que é mostrado ao usuário quando a tela de Retentativa for mostrada na Biometria Facial
        retryScreenSubtextFont: "Roboto, sans-serif",

        // Cor do subtítulo que é mostrado ao usuário quando a tela de Retentativa for mostrada na Biometria Facial
        retryScreenSubtextTextColor: "#585858",

        // Boleano que controla se o assistente por voz deve ser ativado na Biometria Facial
        vocalGuidanceEnabled: true,

        // Cor do título que é mostrado ao usuário quando a tela de Permissão da Camera for mostrada
        cameraPermissionHeaderColor: "#52605A",
        
        // Cor do subtítulo da tela de Permissão da Camera
        cameraPermissionSubtextColor: "#52605A",
        
        // Cor do texto do botão de OK da tela de Permissão da Camera
        cameraPermissionActionButtonColor: "#ffffff"
    }
  }

Exemplo

// objeto para que serve para customizar como será apresentada a Biometria Facial
// este objeto pode ser vazio caso não queira nenhuma customização.
// const customOptions = {}
const customOptions = {
    wizard: {
      enabled: true,
      titleColor: 'green',
      titleAlign: 'center',
      instructionsScreen: {
        logoBackgroundColor: '#e1e4ef',
        iconBackgroundColor: '#2a5595',
        itemColor: '#4b5563'
      },
    },
    faceTecCustomization: {
      loadingBackgroundColor: "#0000ff",
      guidanceForegroundColor: "#1d4f91",
      guidanceRetryScreenImageBorderColor: "#1d4f91",
      guidanceRetryScreenOvalStrokeColor: "#1d4f91",
      idScanSelectionScreenForegroundColor: "#1d4f91",
      idScanButtonBackgroundNormalColor: "#1d4f91",
      idScanButtonBackgroundHighlightColor: "#1d4f91",
      idScanReviewScreenTextBackgroundColor: "#1d4f91",
      idScanCaptureFrameStrokeColor: "#1d4f91",
      vocalGuidanceEnabled: true
    }
  }

// Chamada ao método setup para configurar a Biometria Facial
function setup() {
    Alwm.setupLiveness({
      options: customOptions,
      callback: (callback) => {
        console.log('Alwm.setupLiveness - callback:', callback)
      }
    }).then(() => {
      console.log('SDK Inicializado!');
    }).catch(error => {
      console.log('Erro ao inicializar o SDK!');
    });
}
<div>
    <h1 className="title">Liveness Facetec</h1>
    <button onClick="setup()">Configurar AllowMe Biometria Facial</button>
</div>

No exemplo acima, o Alwm.setup é chamado no momento em que o botão é clicado. É importante ressaltar que o método de setup pode fazer requisições e outros processamentos mais pesados, e assim, sugerimos que este método seja chamado o mais breve possível, visto que é necessário carregar todas as dependências para que a Biometria Facial possa funcionar.

1.2 Chamada a Biometria Facial

Após o processo de configuração (chamada ao método Alwm.setup) podemos carregar a biometria facial através do método Alwm.startLiveness(). Este método retorna uma Promise que pode ser verificada com:

  • .then() - fez o processo de captura com sucesso e retorna um objeto do tipo BiometricsResult; e/ou
  • .catch(error) - ocorreu um erro na Biometria Facial. Verifique o valor de error para obter mais detalhes.

Abaixo temos um exemplo de como o método startLiveness pode ser chamado para capturar as informações de Biometria Facial.

// Chamada ao método startLiveness para inicializar a Biometria Facial
function start() {
    Alwm.startLiveness().then(biometricsResult => {
      console.log(`biometricsResult: `, biometricsResult);
    }).catch(error => {
      console.error(error);
    });
}
<div className="container">
    <h1 className="title">Liveness Facetec</h1>
    <button onClick="setup()">Configurar AllowMe Biometria Facial</button>
    <button onClick="start()">Inicializar o processo de Biometria</button>
</div>

Caso a Biometria Facial tenha sido feita com sucesso, a chamada a Promise resultará no método then que retorna um objeto do tipo BiometricsResult. Este objeto é composto dos seguintes atributos:

BiometricsResult {
    images: string[];
    event: string;
    error?: {
         code: number;
         status: number;
         detail: string;
    };
}

O array de imagens vem codificado em base64 e o atributo event é o fingerprint que é necessário para fazer uma validação de transação. (Vale ressaltar que as imagens tem que ser decodificas antes de enviar as imagens ao Backend AllowMe).

Os atributos event e images serão repassados ao seu Backend e posteriormente para o Backend do AllowMe para validar a sua transação. Para mais informações Validação de uma transação

O atributo error é preenchido caso algum erro aconteça na Biometria Facial. Abaixo seguem os possíveis erros que podem ocorrer:


Código de Erro(error.code)Origem do Erro
100Serasa SDK
200FaceTec SDK
300FaceTec Session

Código de Erro(error.code)Tipo do Erro(error.statusDescriçao
1000Erro desconhecido
1001Erro interno no SDK
2000Nunca inicializado
2001Inicializado
2002Problemas de rede
2003Chave inválida do dispositivo
2004Versão obsoleta
2005Dispositivo não suportado
2006Dispositivo em modo paisagem
2007Dispositivo bloqueado
2008Chave expirada ou inválida
2009IFrame não permitido sem permissão
20010Ainda carregando recursos
20011Recursos não carregados na última inicialização
20012GetUserMedia remoto HTTP não suportado
3000Sessão concluída com sucesso
3001Imagens de orientação faltando
3002Tempo esgotado
3003Mudança de contexto
3004Cancelado programaticamente
3005Mudança de orientação durante sessão
3006Modo paisagem não permitido
3007Usuário cancelado
3008Usuário cancelado da nova orientação
3009Usuário cancelado da orientação de repetição
30010Usuário cancelado ao tentar obter permissões de câmera
30011Bloqueado
30012Câmera não habilitada
30013Chave inválida do dispositivo em modo não produção
30014Documento não pronto
30015Sessão em andamento
30016Câmera não executando
30017Inicialização não concluída
30018Erro interno desconhecido
30019Usuário cancelado via texto clicável da tela pronta
30020Não permitido usar construtor IFrame
30021Não permitido usar construtor não IFrame
30022IFrame não permitido sem permissão
30023Ainda carregando recursos
30024Recursos não carregados na última inicialização
30025Usuário cancelado modo tela cheia

Updated 1 day ago