Skip to main content

Guia de uso SDK BioTrust - Web

Este guia fornece instruções detalhadas para integrar o BioTrust SDK em aplicações Web.

:::tip Pré-requisitos

  • Navegador moderno com suporte a camera (Chrome 60+, Firefox 55+, Safari 11+)
  • HTTPS em producao (localhost funciona com HTTP)
  • Camera funcional
  • JavaScript habilitado :::

:::tip Exemplo

Instalação​

CDN​

Inclua o SDK diretamente via CDN:

<script src="https://s3.us-east-1.amazonaws.com/cdn.biotrust.io/1.0.4/biotrust-sdk.min.js"></script>

Download Local​

Baixe o arquivo biotrust-sdk.js e inclua localmente:

<script src="./js/biotrust-sdk.js"></script>

Configuracao Basica​

Inicializacao do SDK​

const sdk = new BioTrustSDK();

const initResult = await sdk.initialize();

if (initResult.success) {
    console.log("SDK inicializado com sucesso!");
} else {
    console.error("Erro ao inicializar SDK:", initResult.error);
}

Configuracao da Validacao​

const config = {
    uuid: "seu-uuid-aqui",
    apiUrl: "https://api.biotrust.io",
    locale: "pt-BR",
    challengeCount: 3,
    validationMode: "Liveness",
    timeoutMillis: 30000,
    faceDetectionTimeOutMS: 30000,
    maxIncorrectChallengeAttempts: 30,
    themeMode: "light",
    requireAllChallenges: true,
    displayMode: "fullscreen"
};

Parametros de Configuracao​

Parametros Obrigatorios​

ParametroTipoDescricao
uuidStringIdentificador unico do usuario
apiUrlStringURL da API de validacao

Parametros Opcionais​

ParametroTipoPadraoDescricao
localeString"pt-BR"Idioma ("en", "pt-BR", "es-ES")
challengeCountNumber3Numero de desafios (1-5)
validationModeString"Liveness"Modo de validacao ("Liveness", "LivenessWithDocument", "FaceMatch", "FaceMatchExact")
timeoutMillisNumber30000Timeout geral em milissegundos
faceDetectionTimeOutMSNumber30000Timeout para deteccao de rosto
maxIncorrectChallengeAttemptsNumber30Maximo de tentativas incorretas
themeModeString"light"Tema ("light", "dark")
requireAllChallengesBooleantrueSe todos os desafios sao obrigatorios
displayModeString"fullscreen"Modo de exibicao ("fullscreen", "container")
containerIdStringnullID do container (para modo "container")
containerElementHTMLElementnullElemento container (para modo "container")
documentInfoObjectnullInformacoes do documento (para modo "LivenessWithDocument")
faceMatchConfigObjectnullConfiguracoes especificas do FaceMatch

Modos de Validacao​

Liveness (Apenas Vivacidade)​

const config = {
    uuid: "seu-uuid-aqui",
    apiUrl: "https://api.biotrust.io",
    validationMode: "Liveness"
};

LivenessWithDocument (Vivacidade + Documento)​

const config = {
    uuid: "seu-uuid-aqui",
    apiUrl: "https://api.biotrust.io",
    validationMode: "LivenessWithDocument",
    documentInfo: {
        document: "12345678901", // CPF sem pontuacao
        birthDate: "1990-01-01T00:00:00.000Z" // Data de nascimento em ISO 8601
    }
};

FaceMatch (Busca 1:N)​

const config = {
    uuid: "seu-uuid-aqui",
    apiUrl: "https://api.biotrust.io",
    validationMode: "FaceMatch",
    faceMatchConfig: {
        RequireChallenges: true // Se deve solicitar desafios
    }
};

FaceMatchExact (Busca Exata por Documento)​

const config = {
    uuid: "seu-uuid-aqui",
    apiUrl: "https://api.biotrust.io",
    validationMode: "FaceMatchExact",
    faceMatchConfig: {
        RequireChallenges: false, // Se deve solicitar desafios
        Document: "12345678901" // Documento especifico para busca
    }
};

Parametros do documentInfo​

ParametroTipoDescricao
documentStringDocumento sem pontuacao
birthDateStringData de nascimento em formato ISO 8601

Parametros do faceMatchConfig​

ParametroTipoDescricao
RequireChallengesBooleanSe deve solicitar desafios de movimento
DocumentStringCPF especifico para busca (FaceMatchExact)

Modos de Exibicao​

Modo Fullscreen (Padrao)​

const config = {
    uuid: "seu-uuid-aqui",
    apiUrl: "https://api.biotrust.io",
    displayMode: "fullscreen"
};

Modo Container​

const config = {
    uuid: "seu-uuid-aqui",
    apiUrl: "https://api.biotrust.io",
    displayMode: "container",
    containerId: "validation-container"
};
<div id="validation-container" style="width: 800px; height: 600px;"></div>

FaceMatch (Reconhecimento 1:N)​

Além da prova de vida, o SDK identifica quem é a pessoa comparando o rosto com a sua própria base cadastrada. O fluxo tem dois passos: cadastrar pessoas e depois buscar/conferir.

Os dois modos​

  • FaceMatch — busca 1:N: procura o rosto entre todos os cadastros e retorna o mais parecido, com score de similaridade.
  • FaceMatchExact — conferência 1:1: verifica se o rosto bate com um documento específico (Document).

A configuração de cada um está na seção Modos de Validação acima.

Fluxo completo (cadastrar → buscar)​

// 1. Cadastre uma pessoa na base (captura + prova de vida)
const manager = sdk.createManager(config, callback);
await manager.addPerson({
    document: "12345678901",
    documentType: "CPF"
});

// 2. Depois, identifique pela busca 1:N
const busca = {
    uuid: "usuario-123",
    apiUrl: "https://api.biotrust.io",
    validationMode: "FaceMatch",
    faceMatchConfig: { RequireChallenges: true }
};

const launcher = sdk.createLauncher(busca, {
    onValidationComplete: (result) => {
        const match = result.faceMatchResult;
        if (result.success && match?.match) {
            console.log("Pessoa identificada:", match.fullName);
            console.log("Documento:", match.document);
            console.log("Similaridade:", match.similarity);
        }
    }
});

await launcher.launch();

O cadastro e a gestão completa (adicionar, editar e listar pessoas) estão logo abaixo, em Gerenciamento de Pessoas.

tip

Cadastre uma vez e reconheça sempre — ideal para controle de acesso, portaria/condomínio, check-in de eventos e deduplicação/antifraude.

Gerenciamento de Pessoas (FaceMatch)​

O SDK inclui um sistema completo de gerenciamento de pessoas para a funcionalidade de FaceMatch.

Criando um Manager​

const manager = sdk.createManager(config, callback);

Adicionando Pessoa​

await manager.addPerson({
    document: "12345678901",
    documentType: "CPF"
});

Editando Pessoa​

await manager.editPerson({
    id: "person-id",
    document: "12345678901",
    documentType: "CPF"
});

Listando Pessoas​

const result = await manager.listPersons();

if (result.success) {
    console.log("Pessoas cadastradas:", result.data);
    console.log("Total:", result.totalCount);
}

Resultados da Validacao​

Estrutura do Resultado - Lineness​

const result = {
    success: true,
    error: null,
    canceled: false,
    livenessConfidence: 0.95,
    sessionId: "session-123"
};

Estrutura do Resultado - LivenessWithDocument​

const result = {
    success: true,
    error: null,
    canceled: false,
    livenessConfidence: 0.95,
    sessionId: "session-123",
    documentResult: {
        fullName: "JOAO DA SILVA",
        document: "12345678901",
        dateOfBirth: "1991-01-01",
        isSuccess:true,
        facialBiometrics: {
            liveness: "live",
            available: true,
            similarity: 85.7,
            probability: "Alta probabilidade"
        }
    }
};

Estrutura do Resultado - FaceMatch​

const result = {
    success: true,
    error: null,
    canceled: false,
    livenessConfidence: 0.95,
    sessionId: "session-123",
    faceMatchResult: {
        match: true,
        uniqueID: "guid-da-pessoa",
        fullName: "JOAO DA SILVA",
        document: "12345678901",
        similarity: 0.95
    }
};

Estrutura do Resultado - FaceMatchExact​

const result = {
    success: true,
    error: null,
    canceled: false,
    livenessConfidence: 0.95,
    sessionId: "session-123",
    faceMatchResult: {
        match: true,
        uniqueID: "guid-da-pessoa",
        fullName: "JOAO DA SILVA",
        document: "12345678901",
        similarity: 0.95
    }
};

Classificação de Similaridade​

A similaridade entre a foto do documento e a foto da validacao e classificada de acordo com a tabela abaixo:

SimilaridadeClassificaçãoDescricao
> 100Altíssima probabilidadeCorrespondencia perfeita
93 - 100Altíssima probabilidadeCorrespondencia muito alta
65 - 92Alta probabilidadeCorrespondencia alta
32 - 64Baixa probabilidadeCorrespondencia baixa
0 - 31Baixíssima probabilidadeCorrespondencia muito baixa
< 0FalhaErro na comparacao

Tratamento de Resultados​

const callback = {
    onValidationComplete: function(result) {
        if (result.success) {
            console.log("Sucesso! Confianca:", result.livenessConfidence);
            
            // Verificar se tem resultado de documento
            if (result.documentResult) {
                const doc = result.documentResult;
                console.log("Nome:", doc.nome);
                console.log("Data de nascimento:", doc.dateOfBirth);
                console.log("Documento:", doc.document);
                
                if (doc.facialBiometrics) {
                    const liveness = doc.facialBiometrics.liveness;
                    const available = doc.facialBiometrics.available;
                    const similarity = doc.facialBiometrics.similarity;
                    const probability = doc.facialBiometrics.probability;
                    
                    console.log("Vivacidade:", liveness);
                    console.log("Disponivel:", available);
                    console.log("Similaridade:", similarity);
                    console.log("Probabilidade:", probability);
                    
                    // Verificar se a similaridade e aceitavel
                    if (similarity >= 65) {
                        console.log("Similaridade aceitavel!");
                    } else {
                        console.log("Similaridade baixa.");
                    }
                }
            }
            
            // Verificar se tem resultado de FaceMatch
            if (result.faceMatchResult) {
                const faceMatch = result.faceMatchResult;
                console.log("Match:", faceMatch.match);
                console.log("ID da Pessoa:", faceMatch.uniqueID);
                console.log("Nome:", faceMatch.fullName);
                console.log("Documento:", faceMatch.document);
                console.log("Similaridade:", faceMatch.similarity);
            }
            
            window.location.href = "/success";
            
        } else if (result.canceled) {
            console.log("Validacao cancelada pelo usuario");
            
        } else {
            console.error("Validacao falhou:", result.error);
            showErrorMessage(result.error);
        }
    }
};

Exemplos de Implementacao​

Exemplo 1 - Validacao de Vivacidade​

async function startLivenessValidation() {
    try {
        const sdk = new BioTrustSDK();
        const initResult = await sdk.initialize();
        
        if (!initResult.success) {
            throw new Error(initResult.error);
        }
        
        const config = {
            uuid: "usuario-123",
            apiUrl: "https://api.biotrust.io",
            locale: "pt-BR",
            challengeCount: 3,
            validationMode: "Liveness"
        };
        
        const callback = {
            onValidationComplete: function(result) {
                if (result.success) {
                    console.log("Validacao bem-sucedida!", result);
                    alert("Validacao concluida com sucesso!");
                } else {
                    console.error("Validacao falhou:", result.error);
                    alert("Validacao falhou: " + result.error);
                }
            }
        };
        
        const launcher = sdk.createLauncher(config, callback);
        await launcher.launch();
        
    } catch (error) {
        console.error("Erro ao iniciar validacao:", error);
        alert("Erro ao iniciar validacao: " + error.message);
    }
}

Exemplo 2 - Validacao com Documento​

async function startDocumentValidation() {
    try {
        const sdk = new BioTrustSDK();
        await sdk.initialize();
        
        const config = {
            uuid: "usuario-123",
            apiUrl: "https://api.biotrust.io",
            validationMode: "LivenessWithDocument",
            locale: "pt-BR",
            challengeCount: 3,
            documentInfo: {
                document: "12345678901",
                birthDate: "1990-01-01T00:00:00.000Z"
            }
        };
        
        const callback = {
            onValidationComplete: function(result) {
                if (result.success) {
                    console.log("Validacao bem-sucedida!");
                    console.log("Vivacidade:", result.livenessConfidence);
                    
                    if (result.documentResult) {
                        const doc = result.documentResult;
                        console.log("Nome:", doc.fullName);
                        console.log("Documento:", doc.document);
                        console.log("Data de nascimento:", doc.dateOfBirth);
                        
                        if (doc.facialBiometrics) {
                            const similaridade = doc.facialBiometrics.similarity;
                            const disponivel = doc.facialBiometrics.available;
                            const probabilidade = doc.facialBiometrics.probability;
                            
                            console.log(`Similaridade: ${similarity} - ${probabilidade}`);
                            
                            if (similarity >= 65) {
                                alert("Validacao com documento bem-sucedida!");
                            } else {
                                alert("Similaridade baixa com o documento.");
                            }
                        }
                    }
                } else {
                    console.error("Validacao falhou:", result.error);
                    alert("Validacao falhou: " + result.error);
                }
            }
        };
        
        const launcher = sdk.createLauncher(config, callback);
        await launcher.launch();
        
    } catch (error) {
        console.error("Erro:", error);
    }
}

Exemplo 3 - FaceMatch​

async function startFaceMatchValidation() {
    try {
        const sdk = new BioTrustSDK();
        await sdk.initialize();
        
        const config = {
            uuid: "usuario-123",
            apiUrl: "https://api.biotrust.io",
            validationMode: "FaceMatch",
            locale: "pt-BR",
            faceMatchConfig: {
                RequireChallenges: true
            }
        };
        
        const callback = {
            onValidationComplete: function(result) {
                if (result.success) {
                    console.log("FaceMatch bem-sucedido!");
                    
                    if (result.faceMatchResult) {
                        const faceMatch = result.faceMatchResult;
                        
                        if (faceMatch.match) {
                            console.log("Pessoa encontrada:", faceMatch.fullName);
                            console.log("Documento:", faceMatch.document);
                            console.log("Similaridade:", faceMatch.similarity);
                            alert("Pessoa identificada: " + faceMatch.fullName);
                        } else {
                            alert("Nenhuma pessoa encontrada na base de dados.");
                        }
                    }
                } else {
                    console.error("FaceMatch falhou:", result.error);
                    alert("FaceMatch falhou: " + result.error);
                }
            }
        };
        
        const launcher = sdk.createLauncher(config, callback);
        await launcher.launch();
        
    } catch (error) {
        console.error("Erro:", error);
    }
}

Exemplo 4 - Gerenciamento de Pessoas​

async function managePersons() {
    try {
        const sdk = new BioTrustSDK();
        await sdk.initialize();
        
        const config = {
            uuid: "usuario-123",
            apiUrl: "https://api.biotrust.io",
            displayMode: "fullscreen"
        };
        
        const callback = {
            onComplete: function(result) {
                if (result.success) {
                    console.log("Operação concluída com sucesso!");
                    // Atualizar lista de pessoas
                    loadPersons();
                } else {
                    console.error("Erro na operação:", result.error);
                }
            }
        };
        
        const manager = sdk.createManager(config, callback);
        
        // Adicionar nova pessoa
        await manager.addPerson({
            document: "12345678901",
            documentType: "CPF"
        });
        
    } catch (error) {
        console.error("Erro:", error);
    }
}

async function loadPersons() {
    try {
        const sdk = new BioTrustSDK();
        await sdk.initialize();
        
        const config = {
            uuid: "usuario-123",
            apiUrl: "https://api.biotrust.io"
        };
        
        const callback = { onComplete: () => {} };
        const manager = sdk.createManager(config, callback);
        
        const result = await manager.listPersons();
        
        if (result.success) {
            console.log("Pessoas cadastradas:", result.data);
            console.log("Total:", result.totalCount);
            
            // Atualizar UI
            displayPersons(result.data);
        } else {
            console.error("Erro ao carregar pessoas:", result.error);
        }
        
    } catch (error) {
        console.error("Erro:", error);
    }
}

function displayPersons(persons) {
    const container = document.getElementById('persons-list');
    container.innerHTML = '';
    
    persons.forEach(person => {
        const personElement = document.createElement('div');
        personElement.innerHTML = `
            <div class="person-card">
                <h3>${person.fullName}</h3>
                <p>Documento: ${person.document}</p>
                <p>Cadastrado em: ${new Date(person.createdAt).toLocaleDateString()}</p>
                <button onclick="editPerson('${person.id}')">Editar</button>
            </div>
        `;
        container.appendChild(personElement);
    });
}

Exemplo 5 - Validacao em Container​

async function startContainerValidation() {
    try {
        const sdk = new BioTrustSDK();
        await sdk.initialize();
        
        const config = {
            uuid: "usuario-123",
            apiUrl: "https://api.biotrust.io",
            validationMode: "Liveness",
            displayMode: "container",
            containerId: "validation-container",
            locale: "pt-BR"
        };
        
        const callback = {
            onValidationComplete: function(result) {
                document.getElementById('validation-container').innerHTML = '';
                
                if (result.success) {
                    document.getElementById('result').innerHTML = 
                        '<div class="success">Validacao bem-sucedida!</div>';
                } else {
                    document.getElementById('result').innerHTML = 
                        '<div class="error">Validacao falhou: ' + result.error + '</div>';
                }
            }
        };
        
        const launcher = sdk.createLauncher(config, callback);
        await launcher.launch();
        
    } catch (error) {
        console.error("Erro:", error);
    }
}

Tratamento de Erros​

Erros Comuns​

Codigo de ErroDescricaoSolucao
CAMERA_NOT_FOUNDCamera nao encontradaVerificar permissoes e disponibilidade da camera
CAMERA_PERMISSION_DENIEDPermissao de camera negadaSolicitar permissao do usuario para acessar a camera
NETWORK_ERRORErro de conexaoVerificar conexao com a internet
API_ERRORErro na APIVerificar configuracao da API e credenciais
TIMEOUT_ERRORTimeout da validacaoAumentar valor de timeout
FACE_NOT_DETECTEDRosto nao detectadoGarantir boa iluminacao e posicionamento
INVALID_CONFIGConfiguracao invalidaVerificar parametros de configuracao
SDK_NOT_INITIALIZEDSDK nao inicializadoChamar initialize() antes de usar o SDK

Tratamento de Erros​

const callback = {
    onValidationComplete: function(result) {
        if (result.success) {
            console.log("Validacao bem-sucedida!");
            
        } else if (result.canceled) {
            console.log("Validacao cancelada");
            
        } else {
            const errorCode = result.error;
            
            switch (errorCode) {
                case 'CAMERA_NOT_FOUND':
                    alert("Camera nao encontrada. Verifique se a camera e funcional.");
                    break;
                case 'CAMERA_PERMISSION_DENIED':
                    alert("Permissao de camera negada. Por favor, habilite a camera nas configuracoes do navegador.");
                    break;
                case 'NETWORK_ERROR':
                    alert("Erro de conexao. Verifique sua conexao com a internet.");
                    break;
                case 'API_ERROR':
                    alert("Erro na API. Verifique as configuracoes.");
                    break;
                case 'TIMEOUT_ERROR':
                    alert("Tempo esgotado. Tente novamente.");
                    break;
                case 'FACE_NOT_DETECTED':
                    alert("Rosto nao detectado. Verifique a iluminacao e posicionamento.");
                    break;
                default:
                    alert("Erro desconhecido: " + errorCode);
            }
        }
    }
};

Exemplo Completo​

<!DOCTYPE html>
<html lang="pt-BR">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>BioTrust SDK - Exemplo Completo</title>
</head>
<body>
    <div class="container">
        <h1>BioTrust SDK - Exemplo Completo</h1>
        
        <div style="text-align: center;">
            <button id="livenessBtn" class="button" onclick="startLivenessValidation()">
                Iniciar Validacao de Vivacidade
            </button>
            
            <button id="documentBtn" class="button" onclick="startDocumentValidation()">
                Iniciar Validacao com Documento
            </button>
            
            <button id="faceMatchBtn" class="button" onclick="startFaceMatchValidation()">
                Iniciar FaceMatch
            </button>
            
            <button id="managerBtn" class="button" onclick="managePersons()">
                Gerenciar Pessoas
            </button>
        </div>
        
        <div id="validation-container" class="validation-container">
            Validacao aparecera aqui (Modo Container)
        </div>
        
        <div id="persons-list"></div>
        
        <div id="result"></div>
    </div>
    
    <script src="./js/biotrust-sdk.js"></script>
    <script>
        let sdk = null;
        let isInitialized = false;
        
        // Inicializar SDK ao carregar a pagina
        window.addEventListener('load', async function() {
            try {
                sdk = new BioTrustSDK();
                const initResult = await sdk.initialize();
                
                if (initResult.success) {
                    isInitialized = true;
                    console.log("SDK inicializado com sucesso!");
                } else {
                    console.error("Erro ao inicializar SDK:", initResult.error);
                    disableAllButtons();
                }
            } catch (error) {
                console.error("Erro ao inicializar SDK:", error);
                disableAllButtons();
            }
        });
        
        function disableAllButtons() {
            document.getElementById('livenessBtn').disabled = true;
            document.getElementById('documentBtn').disabled = true;
            document.getElementById('faceMatchBtn').disabled = true;
            document.getElementById('managerBtn').disabled = true;
        }
        
        // Funcoes de validacao aqui...
        
    </script>
</body>
</html>

Consideracoes de Seguranca​

  1. HTTPS: Sempre use HTTPS em producao
  2. Validacao de Dados: Valide sempre os dados de entrada
  3. Logs: Mantenha logs detalhados das validacoes
  4. Rate Limiting: Implemente limites de taxa de requisicoes

Suporte​

Para suporte tecnico, entre em contato com: