Guia de uso SDK BioTrust - Flutter

O pacote biotrust_flutter disponibiliza prova de vida, validação com documento, FaceMatch e controle de acesso para aplicativos Flutter. A captura e a análise são executadas pelos SDKs nativos BioTrust de Android e iOS.

Plataforma	Implementação
Android	SDK nativo Android
iOS	SDK nativo iOS

Requisitos

• Flutter 3.24 ou superior (Dart 3)
• 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

flutter pub add biotrust_flutter

Android

O pacote declara os repositórios necessários ao SDK. Em projetos que utilizam dependencyResolutionManagement com FAIL_ON_PROJECT_REPOS, adicione o repositório no settings.gradle:

settings.gradle.kts

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven { url = uri("https://maven.fpregistry.io/releases") }
    }
}

A permissão de internet deve ser declarada pela aplicação. A permissão de câmera é declarada pelo SDK.

android/app/src/main/AndroidManifest.xml

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

iOS

ios/Runner/Info.plist

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

ios/Podfile

platform :ios, '15.0'

O SDK iOS não possui versão para simulador. O aplicativo é executado somente em dispositivos físicos.

Validação

import 'package:biotrust_flutter/biotrust_flutter.dart';

final config = ValidationConfig(
  uuid: 'seu-uuid',
  apiUrl: 'https://api.biotrust.io',
  mode: ValidationMode.livenessOnly,
);

final resultado = await const BioTrustValidator().validate(config);

if (resultado.cancelled) {
  // Validação cancelada pelo usuário
} else if (resultado.isSuccess) {
  // resultado.vivacityConfidence, resultado.faceImage
} else {
  // resultado.message
}

validate 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

Campo	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 (iOS).
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	Uint8List?	Logotipo exibido sobre a câmera (JPEG ou PNG). Somente iOS.
brandImagePosition	BrandPosition	bottomLeft, bottomRight (padrão), topLeft ou topRight.

config.validate() retorna a primeira pendência da configuração, ou null.

Resultado

Campo	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	double	Confiança da prova de vida (0 a 100).
faceImage	Uint8List?	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	double	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

final manager = BioTrustFaceMatchManager(config);

final resultado = await manager.addPerson('Maria Silva', '12345678901', DocumentType.cpf);

if (resultado.isSuccess) {
  // resultado.uniqueId
}

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

DocumentType: cpf, rg ou cnh.

FaceMatchManagerResult: isSuccess, message, uniqueId (nulo na atualização) e cancelled.

Identificação

Utilize faceMatch para identificação (1:N) ou faceMatchExact, com documentNumber, para verificação (1:1).

final resultado = await const BioTrustValidator().validate(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.

final diretorio = BioTrustFaceMatchDirectory(config);

final lista = await diretorio.listPersons(skip: 0, take: 50);

for (final pessoa in lista.persons) {
  // pessoa.uniqueId, pessoa.name, pessoa.document
}

await diretorio.deletePerson(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, com a câmera exibida pelo widget BioTrustCameraView. Consulte o guia de controle de acesso.

Particularidades

• No iOS, a validação é suportada somente em dispositivos físicos.
• Uma validação por vez: uma nova chamada com a tela do SDK aberta retorna falha.
• No Android, brandImage, enableSoundFeedback e enableHapticFeedback não são aplicados.

Próximos Passos

• Controle de acesso
• Webhooks
• Novidades