SDK Browser

Última atualização: 24 de Outubro de 2023

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

Este SDK é escrito em Javascript e 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.

Browser

Requisitos

  • ~9,2MB de espaço em disco
  • Node
  • Npm
  • clientID (chave fornecida pela Clear Sale)
  • clientSecret (chave fornecida pela Clear Sale)
  • .npmrc (com chaves do repositório privado)

Compatibilidades

Mobile Browser - Versões mínimas dos navegadores:
  • Android Chrome 90
  • iOS Safari 11
  • 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=CS-Package
pkgs.dev.azure.com/CS-Package/ID-Lab-PackagesSDK/_packaging/packages/npm/:_password=base64PAT
pkgs.dev.azure.com/CS-Package/ID-Lab-PackagesSDK/_packaging/packages/npm/:email=emailExemplo
; 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 email de sua preferência, desde que seja válido.

Transformar o PAT em base64

Em geral já enviamos o PAT no formato Base64. Mas caso tenha recebido apenas o PAT é possivel converte-lo para base64 da seguinte executando o seguinte comando em um terminal, ele vai mostrar um prompt PAT> você deve colar o valor do PAT da ClearSale e pressionar 'enter', com isso vai ser gerado o Base64. (Para executá-lo é necessário ter o Node.js instalado na máquina.) 

node -e "require('readline') .createInterface({input:process.stdin,output:process.stdout,historySize:0}) .question('PAT> ',p => { b64=Buffer.from(p.trim()).toString('base64');console.log(b64);process.exit(); })"

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@1.2.1-hml --save --save-exact
  • Produção: deve ser usado em ambientes produtivo 
    npm install @studio/csliveness@1.2.1 --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 é possivel 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 parametros que são opcionais, porém altamente recomendados.


Parâmetros Descrição
clientId ClientId identifica o cliente junto à ClearSale, este valor é fornecido pela ClearSale.
clientSecret ClientSecret serve como token de autenticação do cliente.
path Pasta 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 numericos, 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.

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

Métodos

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

Eventos

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

Nome do evento Descrição Parâmetros de Resultado
onReady Esse evento é disparado no momento em que o SDK fica disponível para realizar o método open.
onCompleted Esse evento é disparado quando a captura é finalizada e a imagem foi validada. {image: string, sessionId: string}
onError Evento 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.

tipoErro Descrição
CameraNotEnabled Sessão cancelada pois a câmera não está habilitada.
CameraNotRunning Sessão cancelada pois não foi encontrada nenhuma câmera ativa.
ContextSwitch Sessão cancelada porque o app foi colocado em segundo plano ou o browser saiu do foco do usuário.
DocumentNotReady SDK não pode ser renderizado pois o DOM não está pronto.
IFrameNotAllowedWithoutPermission SDK aberto em um iframe sem permissão.
InitializationNotCompleted Sessão cancelada pois inicialização não foi completada.
LandscapeModeNotAllowed Sessão não iniciada pois o usuário está com a orientação do aparelho no modo landscape.
LockedOut Sessão foi cancelada porque a câmera não estava habilitada.
OrientationChangeDuringSession Sessão cancelada pois o usuário mudou de orientação o celular durante o fluxo.
ResourcesCouldNotBeLoadedOnLastInit SDK não conseguiu carregar os recursos.
SessionInProgress Sessão cancelada pois existe outra em aberto.
StillLoadingResources FaceTec SDK está carregando os recursos.
Timeout Sessão cancelada porque durou um tempo mais do que o necessário.
UnknownInternalError Erros internos não planejados.
UserCancelled Sessão cancelada pelo usuário que clicou no botão de fechar.
UserCancelledFromNewUserGuidance Usuário pressionou o botão cancelar durante a orientação ao usuário.
UserCancelledFromRetryGuidance Usuário pressionou o botão cancelar durante uma nova tentativa de orientação ao usuário.
UserCancelledFullScreenMode A sessão foi cancelada pois o modo tela cheia no iframe foi detectado.
UserCancelledWhenAttemptingToGetCameraPermissions Usuá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 metódo 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;

Algumas dessas informações podem vir a serem compartilhadas com nossas ferramentas de monitoria e error tracking.

Licença de Uso

Ao realizar o download e utilizar nosso SDK você estará concordando com a seguinte licença:

Copyright © 2024 ClearSale

Todos os direitos são reservados, sendo concedida a permissão para usar o software da maneira como está, não sendo permitido qualquer modificação ou cópia para qualquer fim. O Software é licenciado com suas atuais configurações “tal como está” e sem garantia de qualquer espécie, nem expressa e nem implícita, incluindo mas não se limitando, garantias de comercialização, adequação para fins particulares e não violação de direitos patenteados. Em nenhuma hipótese os titulares dos Direitos Autorais podem ser responsabilizados por danos, perdas, causas de ação, quer seja por contrato ou ato ilícito, ou outra ação tortuosa advinda do uso do Software ou outras ações relacionadas com este Software sem prévia autorização escrita do detentor dos direitos autorais.