Vai al contenuto

Per iniziare

GitHub

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:

Finestra del terminale
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:

Finestra del terminale
bun add @capgo/capacitor-native-biometric
bunx cap sync
import { NativeBiometric } from '@capgo/capacitor-native-biometric';
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.

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();
}
await NativeBiometric.deleteCredentials({ server: 'https://api.example.com' });

Esempio: reagisci quando cambia l'enrollment biometrico

Sezione intitolata “Esempio: reagisci quando cambia l'enrollment biometrico”
await NativeBiometric.addListener('biometryChange', async () => {
const { isAvailable } = await NativeBiometric.isAvailable();
if (!isAvailable) showPasscodeUi();
});
  • getSecureCredentials richiede prima accessControl: usa i flag di accesso biometrico al salvataggio, oppure usa getCredentials senza un prompt aggiuntivo.
  • Blocco utente: gestisci BiometricAuthError.USER_LOCKOUT e BiometricAuthError.USER_TEMPORARY_LOCKOUT da verifyIdentity con un'interfaccia di cooldown.
  • Simulatore: registra un'impronta digitale o il volto nel simulatore prima di testare.

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

import { NativeBiometric } from '@capgo/capacitor-native-biometric';
const result = await NativeBiometric.isAvailable();
console.log(result);

Chiede all'utente di autenticarsi con la biometria.

import { NativeBiometric } from '@capgo/capacitor-native-biometric';
await NativeBiometric.verifyIdentity();

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.

Salva le credenziali fornite per un determinato server.

import { NativeBiometric } from '@capgo/capacitor-native-biometric';
await NativeBiometric.setCredentials({
username: 'username',
password: 'password',
server: 'example.com',
});

Elimina le credenziali salvate per un determinato server.

import { NativeBiometric } from '@capgo/capacitor-native-biometric';
await NativeBiometric.deleteCredentials({ server: 'example.com' });

Recupera le credenziali salvate per un server specifico, 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 all'elemento protetto del Keychain. Su Android, viene mostrato BiometricPrompt con un CryptoObject legato 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.

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);
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;
}

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;
}

Tipo di callback per il listener di modifiche biometriche.

export type BiometryChangeListener = (result: AvailableResult) => void;
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[];
}
export interface GetCredentialOptions {
server: string;
}
export interface Credentials {
username: string;
password: string;
}
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;
}
export interface DeleteCredentialOptions {
server: string;
}
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;
}
export interface IsCredentialsSavedOptions {
server: string;
}
export interface IsCredentialsSavedResult {
isSaved: boolean;
}
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,
}

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

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 in Utilizzo di @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.