biotrust_flutter 1.1.0

Validação biométrica facial, prova de vida, FaceMatch e controle de acesso com os SDKs nativos BioTrust para Android e iOS.

biotrust_flutter

Validação biométrica facial para Flutter: prova de vida, validação com documento, FaceMatch e controle de acesso. O pacote usa os SDKs nativos BioTrust de Android e iOS.

Requisitos

Item	Valor
Flutter	3.24 ou superior (Dart 3)
Android	minSdk 24
iOS	15.0, somente aparelho físico (arm64)
SDK Android	io.biotrust:biotrust:1.1.0
SDK iOS	BioTrust 1.1.0, incluído no pacote

Instalação

dependencies:
  biotrust_flutter: ^1.1.0

Android

O pacote declara os repositórios de que o SDK precisa. Em projetos que usam dependencyResolutionManagement com FAIL_ON_PROJECT_REPOS, adicione o repositório manualmente em settings.gradle:

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

O manifesto do app declara a permissão de internet:

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

As permissões de câmera vêm do SDK.

iOS

Declare o uso da câmera no Info.plist:

<key>NSCameraUsageDescription</key>
<string>A câmera é usada para validar o seu rosto.</string>

Defina a plataforma mínima no Podfile:

platform :ios, '15.0'

O SDK iOS não tem versão para simulador. O app compila e roda apenas em aparelho físico.

Validação

final config = ValidationConfig(
  uuid: 'SEU-UUID',
  apiUrl: 'https://api.biotrust.io',
  mode: ValidationMode.livenessOnly,
  locale: 'pt-BR',
);

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

if (resultado.cancelled) {
  // A pessoa fechou a tela.
} else if (resultado.isSuccess) {
  // Aprovado.
} else {
  print(resultado.message);
}

Modos

Modo	Campos exigidos	isSuccess verdadeiro quando
livenessOnly		Prova de vida aprovada
livenessWithDocument	documentCpf, documentBirthDate	Identidade confirmada na base de documentos
faceMatch		Prova de vida aprovada e busca concluída. O resultado da busca está em match
faceMatchExact	documentNumber	Idem, contra a pessoa do documento informado
faceCapture		Prova de vida aprovada. faceImage sempre preenchido

ValidationConfig

Campo	Tipo	Padrão
uuid	String	obrigatório
apiUrl	String	obrigatório
mode	ValidationMode	livenessOnly
apiKey, apiSecret	String?	usados só por BioTrustFaceMatchDirectory
challengeCount	int	0 (padrão do servidor)
requireAllChallenges	bool	false
requireChallenges	bool	false
requireChallengesOnCapture	bool	false (somente iOS)
documentCpf	String?
documentBirthDate	DateTime?	só o dia do calendário é usado
documentNumber	String?
timeoutMillis	int	0 (padrão do SDK)
locale	String?	idioma do aparelho
themeMode	String?	light, dark ou system
enableSoundFeedback	bool	true
enableHapticFeedback	bool	true
brandImage	Uint8List?	JPEG ou PNG
brandImagePosition	BrandPosition	bottomRight

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

ValidationResult

Campo	Tipo	Descrição
isSuccess	bool	Ver a tabela de modos
message	String	Descrição do resultado. Vazia no cancelamento
cancelled	bool	A pessoa fechou a tela
vivacityConfidence	double	0 a 100
faceImage	Uint8List?	JPEG do rosto, 720 x 960
mode	ValidationMode	Modo executado
hasDocumentValidation	bool	Houve consulta à base de documentos
documentSimilarity	double	0 a 100
documentFullName, documentNumber, documentBirthDate, documentProbability	String?	Dados da base de documentos
hasFaceMatchValidation	bool	Houve busca no FaceMatch
match	bool?	null quando não houve busca
matchedPersonId, personName, personDocument	String?	Pessoa encontrada
matchConfidence	double?	0 a 100

Cadastro no FaceMatch

final manager = BioTrustFaceMatchManager(config);

await manager.addPerson('Maria Souza', '12345678900', DocumentType.cpf);
await manager.editPerson(personId, 'Maria Souza', '12345678900', DocumentType.cpf);
await manager.addPersonFromImage(bytes, 'Maria Souza', '12345678900', DocumentType.cpf);

addPerson e editPerson abrem a captura do SDK. addPersonFromImage aceita JPEG ou PNG. A edição altera nome e foto; documento e tipo não mudam.

O retorno é um FaceMatchManagerResult com isSuccess, message, uniqueId (nulo na edição) e cancelled.

Consulta e exclusão

Exige apiKey e apiSecret na configuração. Use apenas em aparelhos controlados, como terminais fixos; em apps distribuídos em loja, faça a consulta pelo seu backend.

final diretorio = BioTrustFaceMatchDirectory(config);

final lista = await diretorio.listPersons(skip: 0, take: 50);
for (final pessoa in lista.persons) {
  print('${pessoa.name} ${pessoa.document}');
}

await diretorio.deletePerson(uniqueId);

FaceMatchPerson traz uniqueId, name, document, documentType, avatarUrl e createdAt. O avatarUrl é temporário.

Controle de acesso

BioTrustCameraController? camera;

// No layout:
BioTrustCameraView(onCreated: (c) => camera = c);

// Depois de a view ser criada e com a permissão de câmera concedida:
final sessao = BioTrustAccessControl(
  AccessControlConfig(uuid: 'SEU-UUID', apiUrl: 'https://api.biotrust.io', terminalLabel: 'Portaria'),
  onAuthorized: (autorizacao) => liberar(autorizacao.name),
  onRevoked: () => fechar(),
  onFaceTracked: (caixa) => desenharQuadro(caixa),
);

await sessao.start(camera);
sessao.personPassed();
sessao.stop();

O app pede a permissão de câmera antes de start.

AccessControlConfig

Campo	Padrão
uuid, apiUrl	obrigatórios
useFrontCamera	true
revokeOnMismatch	true
releaseWindowSeconds	8
unknownCooldownSeconds	2
idleSeconds	30
watchForFace	true
terminalLabel
useServerPolicy	true

Eventos

Todos opcionais, entregues na thread principal.

Evento	Argumento
onAuthorized	AccessAuthorization (personId, name, document, confidence)
onRevoked
onUnknown
onDenied	String
onPermissionDenied	String. Sem tratador, o motivo vai para onDenied
onIdle
onPresence	bool
onStateChanged	AccessState
onDiagnostics	String
onFaceTracked	Rect

A caixa de onFaceTracked é normalizada pela área visível da BioTrustCameraView (0 a 1, origem no canto superior esquerdo), com o espelhamento da câmera frontal aplicado. Para desenhar: left * largura, top * altura, width * largura, height * altura.

Propriedades da sessão: state e accessPointName.

Erros

validate, addPerson, editPerson, addPersonFromImage, listPersons e deletePerson não lançam exceção. Configuração inválida, falha de rede e erro do SDK voltam com isSuccess = false e a descrição em message. Cancelamento volta com cancelled = true e message vazio.

Uma operação com tela por vez. Uma segunda chamada com a tela do SDK aberta devolve Já existe uma validação em andamento.

Licença

Software proprietário, licenciado para uso com os serviços BioTrust mediante contrato comercial. O texto completo está em docs.biotrust.io/licenca.txt e no arquivo LICENSE deste pacote.

Suporte: [e-mail]