# Biometria

> Autenticação biométrica portável com Biometry.isAvailable() e authenticate(...).

Source: https://crossfly.dev/pt/docs/data-and-services/device-biometry — CrossFly documentation. Full docs as one file: https://crossfly.dev/llms-full.txt

# Biometria

Autenticação por digital/face de forma portável, com **`Biometry`**. O resultado chega **assíncrono**
por callback — despache para a UI com `onUI(...)`.

## Uso
```java
if (!Biometry.isAvailable()) {
   loginPorSenha();               // fallback quando não há biometria
   return;
}
Biometry.authenticate(
   "Confirme sua identidade",     // reason (mostrado ao usuário)
   "Cancelar",                    // texto do botão cancelar
   false,                         // onlyBiometric: false = permite PIN do sistema como fallback
   (resultado, mensagem) -> Component.onUI(() -> {
      switch (resultado) {
         case SUCCESS:   abrirAreaSegura(); break;
         case FAILURE:   Hint.show("Não reconhecido", 2000); break;
         case CANCELLED: /* usuário desistiu */ break;
         case ERROR:     Hint.show("Erro: " + mensagem, 2000); loginPorSenha(); break;
      }
   })
);
```

## API
| Membro | Assinatura |
|---|---|
| `Biometry.isAvailable()` | `static boolean` — há hardware/biometria cadastrada? |
| `Biometry.authenticate(...)` | `static void (String reason, String cancel, boolean onlyBiometric, Callback)` |
| `Callback.onResult(...)` | `(AuthResult result, String message)` |
| `AuthResult` | `SUCCESS` · `FAILURE` · `CANCELLED` · `ERROR` |

- **`onlyBiometric = true`** exige biometria (sem cair para PIN/senha do sistema); `false` permite o
  fallback do SO.

## Segurança
- **Os dados biométricos nunca saem do dispositivo** — o app recebe apenas `SUCCESS`/`FAILURE`/etc.,
  jamais a digital/face em si.
- **Sempre ofereça um fallback de aplicação** (login/senha) para `ERROR` e para quando
  `isAvailable()` for `false`.

## Erros comuns
- Tratar só `SUCCESS` e ignorar `CANCELLED`/`ERROR` (usuário fica preso).
- Tocar na UI direto no callback — ele vem **fora** da paint thread; use `onUI(...)`.
- Não ter caminho alternativo quando não há biometria.

## Veja também
- [Som e utilidades de dispositivo](/docs/data-and-services/device-sound-and-misc) · [Permissões por plataforma](/docs/platforms)