SDK JavaScript Liveness

v1.2.5

Introdução

O objetivo deste manual é fornecer todas as informações necessárias para instalação e uso da ferramenta nos aplicativos desenvolvidos para plataforma JavaScript.

Este SDK realiza a captura de faces para processamento de Liveness pela ClearSale. Todas as informações coletadas são dados relacionados apenas ao dispositivo, sem relação ao aplicativo integrado.

As informações de captura de imagem dependem da permissão concedida pelo usuário no momento de captura para dar prosseguimento à coleta de prova de vida.

JavaScript

Requisitos

  • Espaço de armazenamento: ~9mb
  • Dependências:
    • Node
    • .npmrc (com chaves do repositório privado)

Compatibilidades

Mobile Browser - Versões mínimas dos navegadores:

  • Android Chrome 90
  • iOS Safari 14
  • iOS 14.4+ Chrome 90

Desktop Browser - Versões mínimas dos navegadores:

  • Chrome 85
  • Firefox 94
  • Safari 11
  • Edge 95

Instalação do Pacote

Npm

O pacote está disponível em um repositório privado, e para sua utilização você deve adicionar um arquivo com o nome \***\*.npmrc na raiz do projeto (no mesmo nível do seu arquivo package.json) com o seguinte conteúdo:

@studio:registry=https://pkgs.dev.azure.com/CS-Package/ID-Lab-PackagesSDK/_packaging/packages/npm/registry/
registry=https://registry.npmjs.org 
always-auth=true

; begin auth token
//pkgs.dev.azure.com/CS-Package/ID-Lab-PackagesSDK/_packaging/packages/npm/registry/:username=CS-Package
//pkgs.dev.azure.com/CS-Package/ID-Lab-PackagesSDK/_packaging/packages/npm/registry/:_password=base64PAT
//pkgs.dev.azure.com/CS-Package/ID-Lab-PackagesSDK/_packaging/packages/npm/registry/:email=emailExemplo
pkgs.dev.azure.com/CS-Package/ID-Lab-PackagesSDK/_packaging/packages/npm/:username=
pkgs.dev.azure.com/CS-Package/ID-Lab-PackagesSDK/_packaging/packages/npm/:_password=
pkgs.dev.azure.com/CS-Package/ID-Lab-PackagesSDK/_packaging/packages/npm/:email=
; end auth token

Os campos base64PAT devem ser substituídos pelo PAT disponibilizado pela ClearSale para baixar o repositório do SDK Liveness Javascript, já os campos emailExemplo podem ser o endereço de e-mail de sua preferência, desde que seja válido.

Após a configuração do arquivo execute o comando:

  • Homologação: deve ser usado em ambientes de testes e de desenvolvimento
npm install @studio/csliveness@VERSION-hml --save --save-exact
  • Produção: deve ser usado em ambientes produtivo
npm install @studio/csliveness@VERSION --save --save-exact

Configuração

Caso não tenha sido solicitado anteriormente, o SDK solicita a permissão para o uso da câmera que deve ser concedida pelo usuário. Caso o usuário não permita o uso, não é possível continuar com o fluxo de captura.

Classe CSLiveness

Descrição
CSLiveness é a classe responsável pela inicialização do SDK.

Construtores
Esta classe possui um construtor público que deverá receber três parâmetros necessários para a comunicação com os servidores da ClearSale, e mais dois parâmetros que são opcionais, porém altamente recomendados.

ParâmetrosDescrição
clientIdClientId identifica o cliente junto à ClearSale, este valor é fornecido pela ClearSale.
clientSecretClientSecret serve como token de autenticação do cliente.
pathPasta com configuração disponibilizada pela ClearSale. Por padrão ela também é incluida no pacote npm junto à pasta dist/core-skd.
identifierId (opcional)IdentifierId um id que representa a transação do lado do Cliente. Se usado, ele pode ser enviado para nós para melhorar nosso suporte.
cpf (opcional)cpf do usuário que está fazendo o Liveness. Pode ser enviado tanto no formato apenas números, nesse caso uma string com 11 caracteres apenas numéricos, ou no formato xxx.xxx.xxx-xx. Em ambos os casos é preciso que seja um cpf válido (ou seja, que esteja dentro das regras da Receita Federal).

Tipos de Erros
Valores das Strings que podem ser retornadas como mensagem de Exception.

tipoErroDescrição
Invalid clientIdO parâmetro clientId foi enviado como Null ou string vazia.
Invalid clientSecretO parâmetro clientSecret foi enviado como Null ou string vazia.
Invalid identifierIdO parâmetro identifierId, caso seja enviado, tem mais de 100 caracteres.
Invalid CPFO parâmetro cpf, caso seja enviado, não é um cpf válido pelas regras da Receita Federal.

Métodos

Nome do métodoDescrição
initialize() :voidMétodo necessário a ser chamado antes de realizar a abertura da biblioteca.
open() :voidMétodo responsável por iniciar a captura da imagem e envio para validação.
on(eventName: String, callback: function) :voidMétodo usado para gerenciar os callbacks dos listeners.

Eventos
Os eventos que poderão ser mapeados são:

Nome do eventoDescriçãoParâmetros de Resultado
onReadyEsse evento é disparado no momento em que o SDK fica disponível para realizar o método open.-
onCompletedEsse evento é disparado quando a captura é finalizada e a imagem foi validada.{image: string, sessionId: string}
onErrorEvento disparado quando por algum motivo o SDK foi fechado.tipoErro: string

Tipos de Erros
Valores das Strings que podem ser retornadas no campo tipoErro para o callback do evento onError.

Nome do eventoDescrição
CameraNotEnabledSessão cancelada pois a câmera não está habilitada.
CameraNotRunningSessão cancelada pois não foi encontrada nenhuma câmera ativa.
ContextSwitchSessão cancelada porque o app foi colocado em segundo plano ou o browser saiu do foco do usuário.
DocumentNotReadySDK não pode ser renderizado pois o DOM não está pronto.
IFrameNotAllowedWithoutPermissionSDK aberto em um iframe sem permissão.
InitializationNotCompletedSessão cancelada pois inicialização não foi completada.
LandscapeModeNotAllowedSessão não iniciada pois o usuário está com a orientação do aparelho no modo landscape.
LockedOutSessão foi cancelada porque a câmera não estava habilitada.
OrientationChangeDuringSessionSessão cancelada pois o usuário mudou de orientação o celular durante o fluxo.
ResourcesCouldNotBeLoadedOnLastInitSDK não conseguiu carregar os recursos.
SessionInProgressSessão cancelada pois existe outra em aberto.
StillLoadingResourcesFaceTec SDK está carregando os recursos.
TimeoutSessão cancelada porque durou um tempo mais do que o necessário.
UnknownInternalErrorErros internos não planejados.
UserCancelledSessão cancelada pelo usuário que clicou no botão de fechar.
UserCancelledFromNewUserGuidanceUsuário pressionou o botão cancelar durante a orientação ao usuário.
UserCancelledFromRetryGuidanceUsuário pressionou o botão cancelar durante uma nova tentativa de orientação ao usuário.
UserCancelledFullScreenModeA sessão foi cancelada pois o modo tela cheia no iframe foi detectado.
UserCancelledWhenAttemptingToGetCameraPermissionsUsuário pressionou o botão cancelar no navegador ao tentar obter a permissão da câmera durante a orientação para novos usuários.

Exemplos

Para inicializar o SDK, crie uma instância da classe CSLiveness na tela que você deseja que seja iniciado a captura do Liveness passando as credenciais de acesso que foram recebidos pela ClearSale.

import * as CSLiveness from '@studio/csliveness';
sdk = new CSLiveness.Instance('seuClientId', 'seuClientSecret', '/dist/core-sdk',
                                'identifierId', 'cpf do usuário')
sdk.on('onReady', () => {
   //Apenas após o processo de loading do sdk estiver finalizado que se pode iniciar a captura,
   //caso tenha iniciado alguma tela de loading ela pode ser finalizada aqui dentro.
})
sdk.on('onCompleted', (successResult) => {
    //Neste callback será enviado a imagem capturada e o sessionId 
    //que deverá ser armazenado para futura consulta da imagem capturada.
})
sdk.on('onError', (tipo) => {
    //Caso aconteça algum erro será chamado esse callback informando o erro que ocorreu.
})
sdk.initialize()

Apenas após o carregamento do SDK e dele ter emitido o evento de onReady, você de fato pode chamar o método open para iniciar o processo de captura.

 sdk.open()

Detalhes de privacidade

Uso de dados

Todas as informações coletadas pelo SDK da ClearSale são com exclusiva finalidade de prevenção à fraude e proteção ao próprio usuário, aderente à política de segurança e privacidade das plataformas Google e Apple e à LGPD. Por isso, estas informações devem constar na política de privacidade do aplicativo.

Tipo de dados coletados

O SDK da ClearSale coleta as seguintes informações do dispositivo :

  • Características físicas do dispositivo/ hardware (Como tela, modelo, nome do dispositivo);
  • Características de software (Como versão, idioma, build, controle parental);
  • Informações da câmera;