Getting Started

Installazione

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

Importazione

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

API Panoramica

isAvailable

Verifica se il hardware di autenticazione biometrica è disponibile.

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

await NativeBiometric.isAvailable();

verifyIdentity

Sollecita l'utente ad autenticarsi con i dati biometrici.

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

await NativeBiometric.verifyIdentity();

getCredentials

Ottiene le credenziali memorizzate per un server specifico.

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

await NativeBiometric.getCredentials({} as GetCredentialOptions);

setCredentials

Memorizza le credenziali fornite per un server specifico.

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

await NativeBiometric.setCredentials({} as SetCredentialOptions);

deleteCredentials

Elimina le credenziali memorizzate per un server specifico.

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

await NativeBiometric.deleteCredentials({} as DeleteCredentialOptions);

getSecureCredentials

Ottiene le credenziali memorizzate per un server specifico, richiedendo l'autenticazione biometrica. Le credenziali devono essere state memorizzate con accessControl impostato su BIOMETRY_CURRENT_SET o BIOMETRY_ANY.

Sui dispositivi iOS, il sistema mostra automaticamente la finestra di dialogo per l'autenticazione biometrica quando si accede all'elemento Keychain protetto. Sui dispositivi Android, viene mostrata la finestra di dialogo BiometricPrompt con un oggetto CryptoObject legato alla chiave di decrittazione delle credenziali.

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

await NativeBiometric.getSecureCredentials({} as GetSecureCredentialsOptions);

isCredentialsSaved

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

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

await NativeBiometric.isCredentialsSaved({} as IsCredentialsSavedOptions);

Riferimento al tipo

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 l'ascoltatore di 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 plugin src/definitions.ts. Riavvia la sincronizzazione quando il pubblico API cambia in modo upstream.

Continua da Iniziare

Se stai utilizzando Iniziare per pianificare l'autenticazione e i flussi di account, connettilo con Utilizzando @capgo/capacitor-native-biometric per la capacità nativa in Utilizzare @capgo/capacitor-native-biometric, @capgo/capacitor-social-login per il dettaglio di implementazione in @capgo/capacitor-social-login, @capgo/capacitor-passkey per il dettaglio di implementazione in @capgo/capacitor-passkey, @capgo/capacitor-native-biometric per il dettaglio di implementazione in @capgo/capacitor-native-biometric, e Autenticazione a due fattori per il dettaglio di implementazione in Autenticazione a due fattori.