Per iniziare

Installa

Puoi usare il nostro setup assistito dall'IA per installare il plugin. Aggiungi le skill Capgo al tuo strumento di IA usando il seguente comando:

npx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

Poi usa il seguente prompt:

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/capacitor-native-biometric` plugin in my project.

Se preferisci la configurazione manuale, installa il plugin eseguendo questi comandi e segui le istruzioni specifiche per piattaforma qui sotto:

bun add @capgo/capacitor-native-biometric
bunx cap sync

Importa

import { NativeBiometric } from '@capgo/capacitor-native-biometric';

Quick start: proteggi il login con la biometria

import { NativeBiometric } from '@capgo/capacitor-native-biometric';

async function biometricLogin() {
  const { isAvailable } = await NativeBiometric.isAvailable();
  if (!isAvailable) {
    return fallbackToPasscode();
  }

  try {
    const { username, password } = await NativeBiometric.getSecureCredentials({
      server: 'https://api.example.com',
    });
    await signIn(username, password);
  } catch {
    return fallbackToPasscode();
  }
}

Per prima cosa salva i segreti con setCredentials e accessControl quando serve la protezione biometrica in fase di lettura.

Esempio: sblocca con verifyIdentity

getSecureCredentials() mostra già il prompt se le credenziali usano la biometria accessControl. Usa verifyIdentity() per altre azioni protette, e indirizza annullamento o lockout al tuo flusso passcode.

try {
  await NativeBiometric.verifyIdentity({
    reason: 'Unlock your account',
    title: 'Biometric login',
  });
} catch {
  return fallbackToPasscode();
}

Esempio: il logout cancella la voce nel vault

await NativeBiometric.deleteCredentials({ server: 'https://api.example.com' });

Esempio: reagisci quando cambia l'enrollment biometrico

await NativeBiometric.addListener('biometryChange', async () => {
  const { isAvailable } = await NativeBiometric.isAvailable();
  if (!isAvailable) showPasscodeUi();
});

Errori comuni

• getSecureCredentials richiede preventivamente accessControl: usa i flag di accesso biometrico al salvataggio, o usa getCredentials senza un prompt aggiuntivo.
• Blocco utente: gestisci BiometricAuthError.USER_LOCKOUT e BiometricAuthError.USER_TEMPORARY_LOCKOUT da verifyIdentity con una UI di cooldown.
• Simulatore: registra un'impronta o un volto nel simulatore prima del test.

Panoramica API

isAvailable

Verifica se l'hardware per l'autenticazione biometrica è disponibile.

import { NativeBiometric } from '@capgo/capacitor-native-biometric';

const result = await NativeBiometric.isAvailable();
console.log(result);

verifyIdentity

Richiede all'utente l'autenticazione tramite biometria.

import { NativeBiometric } from '@capgo/capacitor-native-biometric';

await NativeBiometric.verifyIdentity();

getCredentials

Recupera le credenziali salvate per un determinato server.

import { NativeBiometric } from '@capgo/capacitor-native-biometric';

const result = await NativeBiometric.getCredentials({ server: 'example.com' });
// The result holds sensitive values: use it without logging it.

setCredentials

Memorizza le credenziali fornite per un determinato server.

import { NativeBiometric } from '@capgo/capacitor-native-biometric';

await NativeBiometric.setCredentials({
  username: 'username',
  password: 'password',
  server: 'example.com',
});

deleteCredentials

Elimina le credenziali salvate per un determinato server.

import { NativeBiometric } from '@capgo/capacitor-native-biometric';

await NativeBiometric.deleteCredentials({ server: 'example.com' });

getSecureCredentials

Recupera le credenziali salvate per un determinato server, richiedendo l'autenticazione biometrica. Le credenziali devono essere state salvate con accessControl impostato su BIOMETRY_CURRENT_SET o BIOMETRY_ANY.

Su iOS, il sistema mostra automaticamente il prompt biometrico quando si accede alla voce protetta del Keychain. Su Android, viene mostrato il BiometricPrompt con un CryptoObject associato alla chiave di decrittazione delle credenziali.

import { NativeBiometric } from '@capgo/capacitor-native-biometric';

const result = await NativeBiometric.getSecureCredentials({ server: 'example.com' });
// The result holds sensitive values: use it without logging it.

isCredentialsSaved

Verifica se le credenziali sono già salvate per un determinato server.

import { NativeBiometric } from '@capgo/capacitor-native-biometric';

const result = await NativeBiometric.isCredentialsSaved({ server: 'example.com' });
console.log(result);

Riferimento ai tipi

IsAvailableOptions

export interface IsAvailableOptions {
  /**
   * Only for iOS.
   * Specifies if should fallback to passcode authentication if biometric authentication is not available.
   * On Android, this parameter is ignored due to BiometricPrompt API constraints:
   * DEVICE_CREDENTIAL authenticator and negative button (cancel) are mutually exclusive.
   */
  useFallback: boolean;
}

AvailableResult

Risultato del metodo isAvailable() che indica la disponibilità dell'autenticazione biometrica.

export interface AvailableResult {
  /**
   * Whether authentication is available (biometric or fallback if useFallback is true)
   */
  isAvailable: boolean;
  /**
   * The strength of available authentication method (STRONG, WEAK, or NONE)
   */
  authenticationStrength: AuthenticationStrength;
  /**
   * The primary biometry type available on the device.
   * On Android devices with multiple biometry types, this returns MULTIPLE.
   * Use this for display purposes only - always use isAvailable for logic decisions.
   */
  biometryType: BiometryType;
  /**
   * Whether the device has a secure lock screen (PIN, pattern, or password).
   * This is independent of biometric enrollment.
   */
  deviceIsSecure: boolean;
  /**
   * Whether strong biometry (Face ID, Touch ID, or fingerprint on devices that consider it strong)
   * is specifically available, separate from weak biometry or device credentials.
   */
  strongBiometryIsAvailable: boolean;
  /**
   * Error code from BiometricAuthError enum. Only present when isAvailable is false.
   * Indicates why biometric authentication is not available.
   * @see BiometricAuthError
   */
  errorCode?: BiometricAuthError;
}

BiometryChangeListener

Tipo di callback per il listener dei cambiamenti biometrici.

export type BiometryChangeListener = (result: AvailableResult) => void;

BiometricOptions

export interface BiometricOptions {
  reason?: string;
  title?: string;
  subtitle?: string;
  description?: string;
  negativeButtonText?: string;
  /**
   * Only for iOS.
   * Specifies if should fallback to passcode authentication if biometric authentication fails.
   * On Android, this parameter is ignored due to BiometricPrompt API constraints:
   * DEVICE_CREDENTIAL authenticator and negative button (cancel) are mutually exclusive.
   */
  useFallback?: boolean;
  /**
   * Only for iOS.
   * Set the text for the fallback button in the authentication dialog.
   * If this property is not specified, the default text is set by the system.
   */
  fallbackTitle?: string;
  /**
   * Only for Android.
   * Set a maximum number of attempts for biometric authentication. The maximum allowed by android is 5.
   * @default 1
   */
  maxAttempts?: number;
  /**
   * Only for Android.
   * Specify which biometry types are allowed for authentication.
   * If not specified, all available types will be allowed.
   * @example [BiometryType.FINGERPRINT, BiometryType.FACE_AUTHENTICATION]
   */
  allowedBiometryTypes?: BiometryType[];
}

GetCredentialOptions

export interface GetCredentialOptions {
  server: string;
}

Credentials

export interface Credentials {
  username: string;
  password: string;
}

SetCredentialOptions

export interface SetCredentialOptions {
  username: string;
  password: string;
  server: string;
  /**
   * Access control level for the stored credentials.
   * When set to BIOMETRY_CURRENT_SET or BIOMETRY_ANY, the credentials are
   * hardware-protected and require biometric authentication to access.
   *
   * On iOS, this adds SecAccessControl to the Keychain item.
   * On Android, this creates a biometric-protected Keystore key and requires
   * BiometricPrompt authentication for both storing and retrieving credentials.
   *
   * @default AccessControl.NONE
   * @since 8.4.0
   */
  accessControl?: AccessControl;
}

DeleteCredentialOptions

export interface DeleteCredentialOptions {
  server: string;
}

GetSecureCredentialsOptions

export interface GetSecureCredentialsOptions {
  server: string;
  /**
   * Reason for requesting biometric authentication.
   * Displayed in the biometric prompt on both iOS and Android.
   */
  reason?: string;
  /**
   * Title for the biometric prompt.
   * Only for Android.
   */
  title?: string;
  /**
   * Subtitle for the biometric prompt.
   * Only for Android.
   */
  subtitle?: string;
  /**
   * Description for the biometric prompt.
   * Only for Android.
   */
  description?: string;
  /**
   * Text for the negative/cancel button.
   * Only for Android.
   */
  negativeButtonText?: string;
}

IsCredentialsSavedOptions

export interface IsCredentialsSavedOptions {
  server: string;
}

IsCredentialsSavedResult

export interface IsCredentialsSavedResult {
  isSaved: boolean;
}

AuthenticationStrength

export enum AuthenticationStrength {
  /**
   * No authentication available, even if PIN is available but useFallback = false
   */
  NONE = 0,
  /**
   * Strong authentication: Face ID on iOS, fingerprints on devices that consider fingerprints strong (Android).
   * Note: PIN/pattern/password is NEVER considered STRONG, even when useFallback = true.
   */
  STRONG = 1,
  /**
   * Weak authentication: Face authentication on Android devices that consider face weak,
   * or PIN/pattern/password if useFallback = true (PIN is always WEAK, never STRONG).
   */
  WEAK = 2,
}

Fonte di verità

Questa pagina è generata dal src/definitions.ts. Riesegui la sync quando il API pubblico cambia upstream.

Continua da Getting Started

Se stai usando Per iniziare per pianificare i flussi di autenticazione e account, collegandolo a Utilizzo di @capgo/capacitor-native-biometric per la funzionalità nativa usando @capgo/capacitor-native-biometric, @capgo/capacitor-social-login per i dettagli di implementazione in @capgo/capacitor-social-login, @capgo/capacitor-passkey per i dettagli di implementazione in @capgo/capacitor-passkey, @capgo/capacitor-native-biometric per i dettagli di implementazione in @capgo/capacitor-native-biometric, e Autenticazione a due fattori per i dettagli sull'implementazione dell'autenticazione a due fattori.