Prova de Vida (Liveness)

A funcionalidade de Prova de Vida pode ser utilizada através do SDK Santo iD, atualmente disponível para JavaScript/Node.js.

Instalação

Para instalar o SDK usando NPM, utilize o seguinte comando:

npm install santoid-sdk

Para instalar usando Yarn, utilize este comando:

yarn add santoid-sdk

Autenticação do SDK

Atualmente, o SDK suporta autenticação via contas de serviço do Santo iD. Para autenticar, crie uma conta de serviço do Santo iD na página de Contas de Serviço da plataforma.

Com a conta criada, armazene as credenciais obtidas em um arquivo no seu projeto com o nome que desejar. Em seguida, será necessário passar as credenciais para o SDK usando a função de inicialização.

É recomendado inicializar o SDK no backend do seu projeto, pois colocar o arquivo de credenciais no frontend pode expô-las aos usuários.

No seu projeto, você pode colocar o arquivo de credenciais em um local específico e expor uma variável de ambiente SANTOID_SDK_CREDENTIALS indicando a localização do arquivo.

Após certificar-se de que o usuário está autorizado de acordo com as regras de negócio do seu aplicativo, inicialize o SDK como mostrado abaixo:

import { initialize } from 'santoid-sdk/node/auth'

async function startSDK () {
    const token = await initialize()
    // ...
}

// Certifique-se de que o usuário está autenticado primeiro
startSDK()

Você também pode passar as credenciais como um objeto ou codificadas em base64 através da propriedade credentials do objeto de opções de inicialização.

import { initialize } from 'santoid-sdk/node/auth'

async function startSDK () {
    const token = await initialize({
        credentials: '...', // Conta de serviço em base64 ou o objeto da conta de serviço
    })

    // ...
}

// Certifique-se de que o usuário está autenticado primeiro
startSDK()

Descrição da Funcionalidade

A funcionalidade Prova de Vida permite verificar o usuário atual, avaliando se uma pessoa real está realizando atividades online através de uma rápida análise facial.

Exemplos

JavaScript

Para usar a funcionalidade de Prova de Vida, é necessário importar a função para iniciar a verificação e passar alguns valores no objeto de opções, como mostrado abaixo:

import { livenessDetection } from 'santoid-sdk/liveness'

const livenessDetectionResponse = livenessDetection({
    token: 'string',
    track: 'string',
    customId: 'string',

    getNextFrame: () => {
        // ...
    },

    // ...
})

const { getVideoStream, stopLivenessDetection, resumeGettingFrames, pauseGettingFrames } = livenessDetectionResponse

Opções para a função livenessDetection (JavaScript)

As propriedades disponíveis para o objeto de opções da função livenessDetection estão listadas na tabela abaixo.

Nome da Propriedade	Função	Obrigatório?
token	Token de acesso obtido através da autenticação.	Sim
track	Identificador do processo a ser usado.	Sim
customId	Identificador personalizado para auditoria.	Não
startGettingFrames	Função executada quando a captura de frames é iniciada. Se retornar um valor MediaStream, ele será salvo e fornecido através da função getVideoStream.	Não
getNextFrame	Função que deve retornar frames no formato File ou Blob. Será executada várias vezes e deve sempre retornar o próximo frame.	Não
stopGettingFrames	Função executada quando a captura de frames é finalizada.	Não
onStart	Função executada quando a verificação é iniciada. Fornece parâmetros com um objeto contendo o stream de transmissão (videoStream), se disponível.	Não
onNextStep	Função executada sempre que a validação avança para a próxima etapa. Fornece parâmetros com a etapa atual ('front', 'left', 'right', 'up' ou 'bottom').	Não
onFrontStep	Função executada quando a etapa 'front' é iniciada.	Não
onLeftStep	Função executada quando a etapa 'left' é iniciada.	Não
onRightStep	Função executada quando a etapa 'right' é iniciada.	Não
onUpStep	Função executada quando a etapa 'up' é iniciada.	Não
onBottomStep	Função executada quando a etapa 'bottom' é iniciada.	Não
onError	Função executada quando ocorre um erro. Fornece parâmetros com a instância do erro, que contém um identificador (code).	Não
onSuccess	Função executada quando a verificação é concluída com sucesso. Fornece parâmetros com um objeto contendo os resultados, composto pelo ID da solicitação (livenessId) e frames de sucesso (successFrames).	Não
onEnd	Função executada quando a verificação é finalizada, seja com erro ou sucesso.	Não

Se a função for executada em um navegador (ou ambiente JavaScript similar como WebView), fornecer uma função para retornar frames para verificação (getNextFrame) não é obrigatório, pois o SDK iniciará automaticamente a câmera e lidará com todo o processo se a função não for fornecida.

Retorno da função livenessDetection (JavaScript)

A função livenessDetection retorna alguns métodos que permitem um melhor controle da verificação.

Nome da Propriedade	Função
getVideoStream	Retorna o stream de frames (MediaStream), se disponível.
stopLivenessDetection	Interrompe a verificação de prova de vida imediatamente e finaliza completamente.
pauseGettingFrames	Pausa a verificação temporariamente, podendo ser retomada posteriormente.
resumeGettingFrames	Retoma a verificação, se ela foi pausada com a função pauseGettingFrames.

import { livenessDetection } from 'santoid-sdk/liveness'

const livenessDetectionResponse = livenessDetection({
    token: 'string',
    track: 'string',

    onStart ({ videoStream }) {
        const video = document.querySelector('video')
        video.srcObject = videoStream    
    },

    onNextStep () {
        pauseGettingFrames()

        // Simulando intervalo de sucesso
        setTimeout(() => {
            resumeGettingFrames()
        }, 1000)
    },

    // ...
})

// Funções retornadas
const { getVideoStream, stopLivenessDetection, pauseGettingFrames, resumeGettingFrames } = livenessDetectionResponse

Node.js

Se desejar executar a função de prova de vida no servidor (Node.js), você deve fornecer ao SDK a função de captura de frames (getNextFrame), que deve retornar um valor no formato string, ArrayBuffer, Buffer ou Buffer[] contendo os dados do frame de imagem.

Observe que o caminho de importação da função muda para execução no servidor (Node.js), conforme mostrado no exemplo a seguir.

Opções para a função livenessDetection (Node.js)

Para Node.js, as opções são quase as mesmas usadas em JavaScript, mudando apenas a exigência de alguns valores. Abaixo estão as propriedades que mudaram. As outras permanecem as mesmas apresentadas anteriormente.

Nome da Propriedade	Função	Obrigatório?
startGettingFrames	Função executada quando a captura de frames é iniciada. Não precisa retornar nenhum valor.	Não
getNextFrame	Função que deve retornar frames no formato string, ArrayBuffer, Buffer ou Buffer[]. Será executada várias vezes e deve sempre retornar o próximo frame.	Sim

Retorno da função livenessDetection (Node.js)

Os itens retornados pela função livenessDetection para Node.js são semelhantes aos retornados pela versão JavaScript, exceto pela função getVideoStream, que não é retornada.

import { livenessDetection } from 'santoid-sdk/node/liveness'

const livenessDetectionResponse = livenessDetection({
    token: 'string',
    track: 'string',
    
    getNextFrame () {
      // ...
    },

    // ...
})

// Funções retornadas
const { stopLivenessDetection, pauseGettingFrames, resumeGettingFrames } = livenessDetectionResponse

CDN

Se desejar usar a biblioteca via CDN, importando-a diretamente em uma tag script, simplesmente use o caminho especificado no exemplo abaixo.

Ao importar a biblioteca via tag script, a função livenessDetection ficará disponível através da classe SantoiDSDK.

Substitua VERSION pela versão desejada.

Neste modo de uso, as opções de configuração disponíveis são as mesmas da versão JavaScript.

<body>
    <button onclick="startLiveness()">Iniciar</button>

    <script src="https://cdn.jsdelivr.net/npm/santoid-sdk@1.0.4/dist/browser/liveness/index.js"></script>

    <script>
        function startLiveness () {
            SantoiDSDK.livenessDetection({
                track: 'string',
                token: 'string',

                // ...
            })
        }
    </script>
</body>