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: cloud@biotrust.io