Guia de uso SDK BioTrust - .NET MAUI

O pacote BioTrust.Maui disponibiliza prova de vida, validação com documento, FaceMatch e controle de acesso para aplicativos .NET MAUI, com uma API única para todas as plataformas.

Plataforma	Implementação
Android	SDK nativo Android
iOS	SDK nativo iOS
Windows e Mac Catalyst	SDK Web

Requisitos

• .NET 9 ou superior, com os workloads do .NET MAUI
• Android 7.0 (API 24) ou superior
• iOS 15.0 ou superior (somente dispositivos físicos)
• UUID do cliente, disponível no Dashboard

Instalação

dotnet add package BioTrust.Maui

Registre o SDK no MauiProgram. O registro é necessário para o uso do BioTrustCameraView no controle de acesso.

using BioTrust.Maui;

var builder = MauiApp.CreateBuilder();
builder
    .UseMauiApp<App>()
    .UseBioTrust();

Permissões

A permissão de câmera deve ser declarada pela aplicação.

Android (Platforms/Android/AndroidManifest.xml):

<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.INTERNET" />

iOS (Platforms/iOS/Info.plist):

<key>NSCameraUsageDescription</key>
<string>A câmera é utilizada para a validação da sua identidade.</string>

Validação

var config = new ValidationConfig
{
    Uuid = "seu-uuid",
    ApiUrl = "https://api.biotrust.io",
    Mode = ValidationMode.LivenessOnly
};

var resultado = await new BioTrustValidator().ValidateAsync(config);

if (resultado.Cancelled)
{
    // Validação cancelada pelo usuário
}
else if (resultado.IsSuccess)
{
    // resultado.VivacityConfidence, resultado.FaceImage
}
else
{
    // resultado.Message
}

ValidateAsync sempre retorna um ValidationResult. Reprovações, erros e cancelamentos não geram exceção. Configurações inválidas são retornadas como falha, com a descrição em Message, antes da abertura da câmera.

Modos de validação

ValidationMode	Descrição	Parâmetros obrigatórios
LivenessOnly	Prova de vida	—
LivenessWithDocument	Prova de vida com validação na base de documentos	DocumentCpf, DocumentBirthDate
FaceMatch	Identificação entre as pessoas cadastradas (1:N)	—
FaceMatchExact	Verificação contra uma pessoa específica (1:1)	DocumentNumber
FaceCapture	Captura do rosto com prova de vida, sem consulta a bases. A imagem é retornada em FaceImage	—

Parâmetros de configuração

Propriedade	Tipo	Descrição
Uuid	string	Identificador do cliente. Obrigatório.
ApiUrl	string	URL da API. Obrigatório.
Mode	ValidationMode	Modo de validação. Padrão: LivenessOnly.
ApiKey	string	Credencial do cliente. Necessária para consulta e exclusão de pessoas.
ApiSecret	string	Secret da credencial. Necessário para consulta e exclusão de pessoas.
ChallengeCount	int	Quantidade de desafios. 0 utiliza o padrão do servidor.
RequireAllChallenges	bool	Exige a conclusão de todos os desafios.
RequireChallenges	bool	Habilita desafios nos modos de FaceMatch.
RequireChallengesOnCapture	bool	Habilita desafios na captura do cadastro.
DocumentCpf	string	CPF. Utilizado em LivenessWithDocument.
DocumentBirthDate	DateTime?	Data de nascimento. Utilizada em LivenessWithDocument.
DocumentNumber	string	Documento da pessoa. Utilizado em FaceMatchExact.
TimeoutMillis	int	Tempo máximo da validação, em milissegundos. 0 utiliza o padrão.
Locale	string	Idioma da interface (ex.: pt-BR). Nulo utiliza o idioma do dispositivo.
ThemeMode	string	light, dark ou system.
EnableSoundFeedback	bool	Feedback sonoro. Padrão: true.
EnableHapticFeedback	bool	Feedback tátil. Padrão: true.
BrandImage	byte[]	Logotipo exibido sobre a câmera (JPEG ou PNG).
BrandImagePosition	BrandPosition	BottomLeft, BottomRight (padrão), TopLeft ou TopRight.

Resultado

Propriedade	Tipo	Descrição
IsSuccess	bool	Resultado da validação. Em LivenessWithDocument, indica a identidade confirmada.
Message	string	Descrição do resultado.
Cancelled	bool	Validação cancelada pelo usuário.
VivacityConfidence	float	Confiança da prova de vida (0 a 100).
FaceImage	byte[]	Imagem do rosto em JPEG, com 720 × 960 pixels.
Mode	ValidationMode	Modo executado.
HasDocumentValidation	bool	Indica se houve validação na base de documentos.
DocumentSimilarity	float	Similaridade com a base de documentos (0 a 100).
DocumentFullName	string	Nome retornado pela base.
DocumentNumber	string	Documento retornado pela base.
DocumentBirthDate	string	Data de nascimento retornada pela base.
DocumentProbability	string	Classificação da similaridade.
HasFaceMatchValidation	bool	Indica se houve busca no FaceMatch.
Match	bool?	true quando a pessoa foi encontrada, false quando não foi, null quando não houve busca.
MatchedPersonId	string	Identificador da pessoa encontrada.
MatchConfidence	double?	Similaridade com a pessoa encontrada (0 a 100).
PersonName	string	Nome da pessoa encontrada.
PersonDocument	string	Documento da pessoa encontrada.

Validação com documento

No modo LivenessWithDocument, IsSuccess indica que a identidade foi confirmada: biometria disponível na base de documentos e similaridade igual ou superior ao limite mínimo da plataforma. Os campos Document* são preenchidos também quando a identidade não é confirmada.

FaceMatch

Cadastro

var manager = new BioTrustFaceMatchManager(config);

var resultado = await manager.AddPersonAsync("Maria Silva", "12345678901", DocumentType.Cpf);

if (resultado.IsSuccess)
{
    // resultado.UniqueId
}

Método	Descrição
AddPersonAsync(name, document, documentType)	Cadastra uma pessoa com captura facial e prova de vida.
AddPersonFromImageAsync(image, name, document, documentType)	Cadastra uma pessoa a partir de uma imagem JPEG ou PNG. A imagem é submetida à verificação de vivacidade.
EditPersonAsync(personId, name, document, documentType)	Atualiza o nome e a foto de uma pessoa cadastrada.

DocumentType: Cpf, Rg ou Cnh.

FaceMatchManagerResult:

Propriedade	Descrição
IsSuccess	Resultado da operação.
Message	Descrição do resultado.
UniqueId	Identificador da pessoa.
Cancelled	Operação cancelada pelo usuário.

Identificação

Utilize FaceMatch para identificação (1:N) ou FaceMatchExact, com DocumentNumber, para verificação (1:1).

var resultado = await new BioTrustValidator().ValidateAsync(new ValidationConfig
{
    Uuid = "seu-uuid",
    ApiUrl = "https://api.biotrust.io",
    Mode = ValidationMode.FaceMatch
});

if (resultado.Match == true)
{
    // resultado.PersonName, resultado.MatchConfidence
}

Consulta e exclusão

Requer ApiKey e ApiSecret na configuração.

var diretorio = new BioTrustFaceMatchDirectory(config);

var lista = await diretorio.ListPersonsAsync(skip: 0, take: 50);

foreach (var pessoa in lista.Persons)
{
    // pessoa.UniqueId, pessoa.Name, pessoa.Document
}

await diretorio.DeletePersonAsync(uniqueId);

A listagem é ordenada da pessoa cadastrada mais recentemente para a mais antiga. AvatarUrl é uma URL temporária para a foto cadastrada. A exclusão remove também a foto.

As mesmas operações estão disponíveis na API REST.

Controle de acesso

O modo terminal, para catracas, portões e portas, é implementado pela classe BioTrustAccessControl. Consulte o guia de controle de acesso.

Disponível para Android e iOS. Em Windows e Mac Catalyst, utilize o createAccessControl do SDK Web.

Particularidades por plataforma

• No iOS, a validação é suportada somente em dispositivos físicos.
• Em Windows e Mac Catalyst, a validação é executada pelo SDK Web.

Próximos Passos

• Controle de acesso
• Webhooks
• Novidades