# Biometrics

> Portable biometric authentication with Biometry.isAvailable() and authenticate(...).

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

# Biometrics

Fingerprint/face authentication in a portable way, with **`Biometry`**. The result arrives **asynchronously**
via callback — dispatch it to the UI with `onUI(...)`.

## Usage
```java
if (!Biometry.isAvailable()) {
   loginPorSenha();               // fallback when there is no biometrics
   return;
}
Biometry.authenticate(
   "Confirme sua identidade",     // reason (shown to the user)
   "Cancelar",                    // text of the cancel button
   false,                         // onlyBiometric: false = allows the system PIN as a fallback
   (resultado, mensagem) -> Component.onUI(() -> {
      switch (resultado) {
         case SUCCESS:   abrirAreaSegura(); break;
         case FAILURE:   Hint.show("Não reconhecido", 2000); break;
         case CANCELLED: /* user gave up */ break;
         case ERROR:     Hint.show("Erro: " + mensagem, 2000); loginPorSenha(); break;
      }
   })
);
```

## API
| Member | Signature |
|---|---|
| `Biometry.isAvailable()` | `static boolean` — is there hardware/enrolled biometrics? |
| `Biometry.authenticate(...)` | `static void (String reason, String cancel, boolean onlyBiometric, Callback)` |
| `Callback.onResult(...)` | `(AuthResult result, String message)` |
| `AuthResult` | `SUCCESS` · `FAILURE` · `CANCELLED` · `ERROR` |

- **`onlyBiometric = true`** requires biometrics (no falling back to the system PIN/password); `false` allows the
  OS fallback.

## Security
- **Biometric data never leaves the device** — the app only receives `SUCCESS`/`FAILURE`/etc.,
  never the fingerprint/face itself.
- **Always offer an application fallback** (login/password) for `ERROR` and for when
  `isAvailable()` is `false`.

## Common mistakes
- Handling only `SUCCESS` and ignoring `CANCELLED`/`ERROR` (the user gets stuck).
- Touching the UI directly in the callback — it comes **off** the paint thread; use `onUI(...)`.
- Not having an alternative path when there is no biometrics.

## See also
- [Device sound and utilities](/docs/data-and-services/device-sound-and-misc) · [Per-platform permissions](/docs/platforms)