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.

Requisitos​

Instalação​

Android​

iOS​

Validação​

Modos de validação​

Parâmetros de configuração​

Resultado​

FaceMatch​

Cadastro​

Identificação​

Consulta e exclusão​

Controle de acesso​

Particularidades​

Próximos Passos​