Controle de acesso

O controle de acesso é um modo de operação para dispositivos fixos, como catracas, portões e portas. A câmera permanece ativa e cada pessoa detectada é validada com prova de vida e FaceMatch contra as pessoas cadastradas.

O SDK informa o resultado de cada leitura. O acionamento do equipamento (catraca, relé ou fechadura) é responsabilidade da aplicação.

Plataforma	Classe
Android	`AccessControlSession`
iOS	`BTAccessSession`
.NET MAUI (Android e iOS)	`BioTrustAccessControl`
Flutter (Android e iOS)	`BioTrustAccessControl`
React Native (Android e iOS)	`BioTrustAccessControl`
Web	`createAccessControl`

Estados da sessão

Estado	Android	iOS	.NET MAUI	Flutter	React Native	Web	Descrição
Parada	`PARADA`	`.parada`	`Stopped`	`AccessState.stopped`	`'stopped'`	`"parada"`	Câmera desligada.
Vigília	`VIGILIA`	`.vigilia`	`Watching`	`AccessState.watching`	`'watching'`	—	Câmera ativa, aguardando presença.
Procurando	`PROCURANDO`	`.procurando`	`Searching`	`AccessState.searching`	`'searching'`	`"procurando"`	Prova de vida e identificação em andamento.
Liberada	`LIBERADA`	`.liberada`	`Released`	`AccessState.released`	`'released'`	`"liberada"`	Acesso autorizado.
Bloqueada	`BLOQUEADA`	`.bloqueada`	`Revoked`	`AccessState.revoked`	`'revoked'`	`"bloqueada"`	Autorização revogada.

Comportamento

Situação	Comportamento	Parâmetro
Pessoa reconhecida	Emite a autorização. Novas autorizações são suspensas até a chamada de `personPassed()` ou o fim da janela de liberação.	`releaseWindowSeconds`
Rosto não reconhecido durante a liberação	Revoga a autorização.	`revokeOnMismatch`
Pessoa não cadastrada	Emite o evento de pessoa desconhecida e aguarda o intervalo configurado antes de uma nova leitura.	`unknownCooldownSeconds`
Pessoa sem permissão no ponto de acesso	Emite o evento de permissão negada.	—
Falha na prova de vida ou na leitura	Emite o evento de negação, com a descrição.	—
Nenhum rosto detectado	Emite o evento de ociosidade após o tempo configurado.	`idleSeconds`

Configuração no Dashboard

Na seção Controle de acesso do Dashboard:

Item	Descrição
Pontos de acesso	Locais controlados, como garagem e portaria. Cada ponto pode permitir qualquer pessoa cadastrada ou somente pessoas autorizadas, e possui parâmetros próprios de operação.
Terminais	Dispositivos instalados, identificados pelo `terminalLabel` e associados a um ponto de acesso.
Grupos de pessoas	Agrupamento de pessoas cadastradas, como moradores e funcionários.
Grupos de pontos	Agrupamento de pontos de acesso, como áreas comuns e garagens.
Concessões	Permissão de acesso de um grupo de pessoas a um ponto ou grupo de pontos.

O terminal é registrado automaticamente na primeira execução da sessão. Com useServerPolicy ativado (padrão), os parâmetros definidos no ponto de acesso prevalecem sobre os valores configurados na aplicação.

Implementação

Android

import io.biotrust.sdk.acesso.AccessControlConfig;
import io.biotrust.sdk.acesso.AccessControlSession;
import io.biotrust.sdk.acesso.AccessControlState;

AccessControlConfig config = new AccessControlConfig.Builder()
    .setUuid("seu-uuid")
    .setApiUrl("https://api.biotrust.io")
    .setTerminalLabel("Portaria")
    .build();

AccessControlSession sessao = new AccessControlSession(this, config, new AccessControlSession.Callback() {
    @Override
    public void onStateChanged(AccessControlState state) { }

    @Override
    public void onAuthorize(String personId, String name, String document, Double confidence) {
        // Liberar o acesso
    }

    @Override
    public void onRevoke() {
        // Bloquear o acesso
    }
});

sessao.start(previewView, this);   // PreviewView (CameraX)
sessao.personPassed();             // Pessoa passou pelo acesso
sessao.stop();                     // Encerrar a sessão

Callbacks opcionais: onPresence, onUnknown, onDeny, onDenyPermission, onIdle e onFaceBox. A permissão de câmera deve ser concedida antes de start.

iOS

import BioTrust

final class AcessoViewController: UIViewController, BTAccessDelegate {

    @IBOutlet private var previewView: UIView!
    private var sessao: BTAccessSession!

    override func viewDidLoad() {
        super.viewDidLoad()

        let config = BTAccessConfig()
        config.uuid = "seu-uuid"
        config.apiUrl = "https://api.biotrust.io"
        config.terminalLabel = "Portaria"

        sessao = BTAccessSession(config: config)
        sessao.delegate = self
        sessao.start(in: previewView)
    }

    func accessSession(_ session: BTAccessSession, didChangeState state: BTAccessState) { }

    func accessSession(_ session: BTAccessSession,
                       didAuthorize personId: String,
                       name: String,
                       document: String,
                       confidence: Double) {
        // Liberar o acesso
    }

    func accessSessionDidRevoke(_ session: BTAccessSession) {
        // Bloquear o acesso
    }
}

Métodos personPassed() e stop() disponíveis em BTAccessSession. Métodos opcionais do delegate: didDetectPresence, accessSessionDidFindUnknown, didDeny, accessSessionDidDenyPermission, accessSessionDidBecomeIdle e didTrackFace. Requer NSCameraUsageDescription no Info.plist.

.NET MAUI

Adicione o BioTrustCameraView à página. Requer UseBioTrust() no MauiProgram.

<ContentPage xmlns:bt="clr-namespace:BioTrust.Maui;assembly=BioTrust.Maui">
    <bt:BioTrustCameraView x:Name="Camera" />
</ContentPage>

var sessao = new BioTrustAccessControl(new AccessControlConfig
{
    Uuid = "seu-uuid",
    ApiUrl = "https://api.biotrust.io",
    TerminalLabel = "Portaria"
});

sessao.Authorized += autorizacao => MainThread.BeginInvokeOnMainThread(() =>
{
    // autorizacao.PersonId, autorizacao.Name, autorizacao.Confidence
});

sessao.Revoked += () => MainThread.BeginInvokeOnMainThread(() =>
{
    // Bloquear o acesso
});

await sessao.StartAsync(Camera);

sessao.PersonPassed();   // Pessoa passou pelo acesso
sessao.Stop();           // Encerrar a sessão

Eventos disponíveis: Authorized, Revoked, Unknown, Denied, PermissionDenied, Idle, Presence, StateChanged e FaceTracked. Os eventos podem ser disparados fora da thread principal.

Flutter

import 'package:biotrust_flutter/biotrust_flutter.dart';

BioTrustCameraController? camera;

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

// Após a criação da view 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 o acesso: autorizacao.personId, autorizacao.name, autorizacao.confidence
  },
  onRevoked: () {
    // Bloquear o acesso
  },
);

await sessao.start(camera);
sessao.personPassed();   // Pessoa passou pelo acesso
sessao.stop();           // Encerrar a sessão

Eventos disponíveis: onAuthorized, onRevoked, onUnknown, onDenied, onPermissionDenied, onIdle, onPresence, onStateChanged, onDiagnostics e onFaceTracked. Os eventos são entregues na thread principal.

React Native

import { useRef } from 'react';
import {
  BioTrustAccessControl,
  BioTrustCameraView,
  type BioTrustCameraViewHandle,
} from '@biotrust-io/react-native';

const camera = useRef<BioTrustCameraViewHandle>(null);

// No layout
<BioTrustCameraView ref={camera} style={{ flex: 1 }} />

// Após a montagem da view e com a permissão de câmera concedida
const sessao = new BioTrustAccessControl(
  { uuid: 'seu-uuid', apiUrl: 'https://api.biotrust.io', terminalLabel: 'Portaria' },
  {
    onAuthorized: (autorizacao) => {
      // Liberar o acesso: autorizacao.personId, autorizacao.name, autorizacao.confidence
    },
    onRevoked: () => {
      // Bloquear o acesso
    },
  },
);

await sessao.start(camera.current);
sessao.personPassed();   // Pessoa passou pelo acesso
sessao.stop();           // Encerrar a sessão

Eventos disponíveis: onAuthorized, onRevoked, onUnknown, onDenied, onPermissionDenied, onIdle, onPresence, onStateChanged, onDiagnostics e onFaceTracked.

Web

const sdk = new BioTrustSDK();
await sdk.initialize();

const sessao = sdk.createAccessControl(
  {
    uuid: "seu-uuid",
    apiUrl: "https://api.biotrust.io",
  },
  {
    onAuthorize: (pessoa) => { /* pessoa.personId, pessoa.name, pessoa.confidence */ },
    onRevoke: () => { },
    onUnknown: () => { },
    onDeny: (mensagem) => { },
    onDenyPermission: (mensagem) => { },
    onIdle: () => { },
    onStateChanged: (estado) => { },
  }
);

await sessao.start(document.getElementById("camera"));
sessao.personPassed();
sessao.stop();

onAuthorize é obrigatório. O SDK Web não possui o estado de vigília.

Parâmetros

Parâmetro	Padrão	Descrição
`uuid`	—	Identificador do cliente. Obrigatório.
`apiUrl`	—	URL da API. Obrigatório.
`releaseWindowSeconds`	`8`	Duração da autorização, em segundos, caso `personPassed()` não seja chamado.
`revokeOnMismatch`	`true`	Revoga a autorização quando um rosto não reconhecido é detectado durante a liberação.
`unknownCooldownSeconds`	`2`	Intervalo, em segundos, após a detecção de uma pessoa não cadastrada.
`idleSeconds`	`30`	Tempo sem detecção de rosto, em segundos, para o evento de ociosidade. `0` desativa o evento.
`watchForFace`	`true`	Mantém a detecção de presença pela câmera. Não se aplica ao SDK Web.
`useFrontCamera`	`true`	Utiliza a câmera frontal. Não se aplica ao SDK Web.
`terminalLabel`	—	Identificação do terminal no Dashboard. Não se aplica ao SDK Web.
`useServerPolicy`	`true`	Aplica os parâmetros definidos no ponto de acesso. Não se aplica ao SDK Web.

Nomenclatura por plataforma: métodos set... do AccessControlConfig.Builder (Android), propriedades do BTAccessConfig (iOS) propriedades do AccessControlConfig em PascalCase (.NET MAUI) e campos do AccessControlConfig (Flutter e React Native).

Posição do rosto

Os eventos onFaceBox (Android), didTrackFace (iOS), FaceTracked (.NET MAUI) e onFaceTracked (Flutter e React Native) informam a posição do rosto em coordenadas normalizadas (0 a 1, origem no canto superior esquerdo) em relação à área visível da câmera. O recorte do preview e o espelhamento da câmera frontal já estão aplicados: para desenhar sobre o preview, multiplique as coordenadas pela largura e pela altura da view.

Estados da sessão​

Comportamento​

Configuração no Dashboard​

Implementação​

Android​

iOS​

.NET MAUI​

Flutter​

React Native​

Web​

Parâmetros​

Posição do rosto​