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â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 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
.
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
.
Nome do evento | 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 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;
Updated 2 months ago