Iniziare

Installa

Puoi utilizzare la nostra configurazione assistita dall'AI per installare il plugin. Aggiungi le Capgo abilità al tuo strumento AI utilizzando il seguente comando:

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

Poi utilizza 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 l'installazione manuale, installa il plugin eseguendo i seguenti comandi e segui le istruzioni specifiche per la piattaforma riportate di seguito:

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

Importa

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

Richiede all'utente di 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.

Sullo iOS, il sistema mostra automaticamente la richiesta di autenticazione biometrica quando si accede all'elemento Keychain protetto. Sull'Android, viene mostrato il prompt 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

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

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

await NativeBiometric.isCredentialsSaved({} as IsCredentialsSavedOptions);

Riferimento di 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 di biometria.

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’s 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 le flussi di account, connettilo con Utilizzando @capgo/capacitor-native-biometric per la capacità nativa in Utilizzando @capgo/capacitor-native-biometric, @capgo/capacitor-social-login per il dettaglio di implementazione in @capgo/capacitor-social-login per la chiave di accesso @capgo/capacitor per i dettagli di implementazione in @capgo/capacitor-passkey per la biometria nativa @capgo/capacitor per i dettagli di implementazione in @capgo/capacitor-native-biometric, e Autenticazione a due fattori per i dettagli di implementazione in Autenticazione a due fattori.