Guia de uso SDK BioTrust - Web

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

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

Exemplo

• Faça download da aplicação exemplo do SDK BioTrust
• https://github.com/biotrust-io/BioTrust-Example-Web

Instalação

CDN

Inclua o SDK diretamente via CDN:

<script src="https://s3.us-east-1.amazonaws.com/cdn.biotrust.io/1.1.0/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

Parametro	Tipo	Descricao
uuid	String	Identificador unico do usuario
apiUrl	String	URL da API de validacao

Parametros Opcionais

Parametro	Tipo	Padrao	Descricao
locale	String	"pt-BR"	Idioma ("en", "pt-BR", "es-ES")
challengeCount	Number	3	Numero de desafios (1-5)
validationMode	String	"Liveness"	Modo de validacao ("Liveness", "LivenessWithDocument", "FaceMatch", "FaceMatchExact", "FaceCapture")
timeoutMillis	Number	30000	Timeout geral em milissegundos
faceDetectionTimeOutMS	Number	30000	Timeout para deteccao de rosto
maxIncorrectChallengeAttempts	Number	30	Maximo de tentativas incorretas
themeMode	String	"light"	Tema ("light", "dark")
requireAllChallenges	Boolean	true	Se todos os desafios sao obrigatorios
displayMode	String	"fullscreen"	Modo de exibicao ("fullscreen", "container")
containerId	String	null	ID do container (para modo "container")
containerElement	HTMLElement	null	Elemento container (para modo "container")
documentInfo	Object	null	Informacoes do documento (para modo "LivenessWithDocument")
faceMatchConfig	Object	null	Configuracoes 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
    }
};

FaceCapture (Captura do Rosto)

Executa a prova de vida e retorna a imagem do rosto, sem consulta a bases.

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

O resultado inclui faceImage: imagem JPEG em base64, sem o prefixo data:, com 720 × 960 pixels (960 × 720 em câmeras na horizontal).

Parametros do documentInfo

Parametro	Tipo	Descricao
document	String	Documento sem pontuacao
birthDate	String	Data de nascimento em formato ISO 8601

Parametros do faceMatchConfig

Parametro	Tipo	Descricao
RequireChallenges	Boolean	Se deve solicitar desafios de movimento
Document	String	CPF 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)

O FaceMatch identifica pessoas por comparação facial com as pessoas cadastradas na conta. O fluxo é composto pelo cadastro das pessoas e pela identificação (1:N) ou verificação (1:1).

Os dois modos

• FaceMatch: identificação (1:N). Retorna a pessoa cadastrada de maior similaridade.
• FaceMatchExact: verificação (1:1) contra a pessoa do documento informado em Document.

A configuração de cada modo está descrita em Modos de Validação.

Exemplo: cadastro e identificação

// 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();

As operações de cadastro, edição e listagem estão descritas em Gerenciamento de Pessoas.

tip

Aplicações comuns: controle de acesso, portarias, check-in de eventos e prevenção a fraudes por duplicidade de cadastro. Para dispositivos fixos, consulte o guia de controle de acesso.

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",
            approved: true
        }
    }
};

success indica que a identidade foi confirmada: biometria disponível na base de documentos (available) e similaridade igual ou superior ao limite mínimo da plataforma (approved).

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:

Similaridade	Classificação	Descricao
> 100	Altíssima probabilidade	Correspondencia perfeita
93 - 100	Altíssima probabilidade	Correspondencia muito alta
65 - 92	Alta probabilidade	Correspondencia alta
32 - 64	Baixa probabilidade	Correspondencia baixa
0 - 31	Baixíssima probabilidade	Correspondencia muito baixa
< 0	Falha	Erro 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 Erro	Descricao	Solucao
CAMERA_NOT_FOUND	Camera nao encontrada	Verificar permissoes e disponibilidade da camera
CAMERA_PERMISSION_DENIED	Permissao de camera negada	Solicitar permissao do usuario para acessar a camera
NETWORK_ERROR	Erro de conexao	Verificar conexao com a internet
API_ERROR	Erro na API	Verificar configuracao da API e credenciais
TIMEOUT_ERROR	Timeout da validacao	Aumentar valor de timeout
FACE_NOT_DETECTED	Rosto nao detectado	Garantir boa iluminacao e posicionamento
INVALID_CONFIG	Configuracao invalida	Verificar parametros de configuracao
SDK_NOT_INITIALIZED	SDK nao inicializado	Chamar 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

Próximos Passos

• Controle de acesso — modo terminal com createAccessControl
• Webhooks — notificação de eventos para o seu servidor
• Guia .NET MAUI — integração em aplicativos .NET MAUI
• Playground — teste a validação no navegador

Suporte

Para suporte tecnico, entre em contato com:

• Email: suporte@biotrust.io
• Documentacao: https://docs.biotrust.io
• GitHub: https://github.com/biotrust-io