Guia de uso SDK BioTrust - React Native

O pacote @biotrust-io/react-native disponibiliza prova de vida, validação com documento, FaceMatch e controle de acesso para aplicativos React Native. 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

• React Native 0.76 ou superior, com a nova arquitetura habilitada
• 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

npm install @biotrust-io/react-native
cd ios && pod install

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:

android/settings.gradle

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven { url "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/<App>/Info.plist

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

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

Validação

import { BioTrustValidator, ValidationMode } from '@biotrust-io/react-native';

const resultado = await new BioTrustValidator().validate({
  uuid: 'seu-uuid',
  apiUrl: 'https://api.biotrust.io',
  mode: ValidationMode.LivenessOnly,
});

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

validate sempre resolve com um ValidationResult. Reprovações, erros e cancelamentos não rejeitam a Promise. 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	Valor	Descrição	Parâmetros obrigatórios
LivenessOnly	'livenessOnly'	Prova de vida	—
LivenessWithDocument	'livenessWithDocument'	Prova de vida com validação na base de documentos	documentCpf, documentBirthDate
FaceMatch	'faceMatch'	Identificação entre as pessoas cadastradas (1:N)	—
FaceMatchExact	'faceMatchExact'	Verificação contra uma pessoa específica (1:1)	documentNumber
FaceCapture	'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	number	Quantidade de desafios. 0 utiliza o padrão do servidor.
requireAllChallenges	boolean	Exige a conclusão de todos os desafios.
requireChallenges	boolean	Habilita desafios nos modos de FaceMatch.
requireChallengesOnCapture	boolean	Habilita desafios na captura do cadastro (iOS).
documentCpf	string	CPF. Utilizado em LivenessWithDocument.
documentBirthDate	Date	Data de nascimento. Utilizada em LivenessWithDocument.
documentNumber	string	Documento da pessoa. Utilizado em FaceMatchExact.
timeoutMillis	number	Tempo máximo da validação, em milissegundos. 0 utiliza o padrão.
locale	string	Idioma da interface (ex.: pt-BR). Ausente utiliza o idioma do dispositivo.
themeMode	string	light, dark ou system.
enableSoundFeedback	boolean	Feedback sonoro. Padrão: true.
enableHapticFeedback	boolean	Feedback tátil. Padrão: true.
brandImage	string	Logotipo exibido sobre a câmera, em base64 (JPEG ou PNG). Somente iOS.
brandImagePosition	BrandPosition	BottomLeft, BottomRight (padrão), TopLeft ou TopRight.

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

Resultado

Campo	Tipo	Descrição
isSuccess	boolean	Resultado da validação. Em LivenessWithDocument, indica a identidade confirmada.
message	string	Descrição do resultado.
cancelled	boolean	Validação cancelada pelo usuário.
vivacityConfidence	number	Confiança da prova de vida (0 a 100).
faceImage	string | null	Imagem do rosto em JPEG, codificada em base64, com 720 × 960 pixels.
mode	ValidationMode	Modo executado.
hasDocumentValidation	boolean	Indica se houve validação na base de documentos.
documentSimilarity	number	Similaridade com a base de documentos (0 a 100).
documentFullName	string | null	Nome retornado pela base.
documentNumber	string | null	Documento retornado pela base.
documentBirthDate	string | null	Data de nascimento retornada pela base.
documentProbability	string | null	Classificação da similaridade.
hasFaceMatchValidation	boolean	Indica se houve busca no FaceMatch.
match	boolean | null	true quando a pessoa foi encontrada, false quando não foi, null quando não houve busca.
matchedPersonId	string | null	Identificador da pessoa encontrada.
matchConfidence	number | null	Similaridade com a pessoa encontrada (0 a 100).
personName	string | null	Nome da pessoa encontrada.
personDocument	string | null	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

import { BioTrustFaceMatchManager, DocumentType } from '@biotrust-io/react-native';

const manager = new BioTrustFaceMatchManager(config);

const 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, em base64. 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).

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

import { BioTrustFaceMatchDirectory } from '@biotrust-io/react-native';

const diretorio = new BioTrustFaceMatchDirectory(config);

const lista = await diretorio.listPersons({ skip: 0, take: 50 });

for (const pessoa of 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 componente 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