Prise en main

Installer

Vous pouvez utiliser notre configuration assistée par IA pour installer le plugin. Ajoutez les skills Capgo à votre outil d'IA avec la commande suivante :

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

Utilisez ensuite le prompt suivant :

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

Si vous préférez une installation manuelle, installez le plugin en exécutant les commandes suivantes et suivez les instructions spécifiques à chaque plateforme ci-dessous :

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

Importer

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

Démarrage rapide : sécuriser un login avec la biométrie

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

Stockez d'abord vos secrets avec setCredentials et accessControl when you need biometric protection on read.

Exemple : déverrouiller avec verifyIdentity

getSecureCredentials() already prompts when credentials use biometric accessControl. Utilisez verifyIdentity() pour d'autres actions sécurisées, et redirige l'annulation ou le verrouillage vers votre flux de code de déverrouillage.

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

Exemple : la déconnexion efface l'entrée du vault

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

Exemple : réagir aux changements d'enrôlement biométrique

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

Erreurs courantes

• getSecureCredentials nécessite au préalable accessControl: use biometric access flags when saving, or use getCredentials sans prompt supplémentaire.
• Verrouillage utilisateur: gérez BiometricAuthError.USER_LOCKOUT et BiometricAuthError.USER_TEMPORARY_LOCKOUT depuis verifyIdentity avec une interface de délai d'attente.
• Simulateur: enregistrez une empreinte ou un visage dans le simulateur avant de tester.

Aperçu de API

isAvailable

Vérifie si le matériel d'authentification biométrique est disponible.

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

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

verifyIdentity

Demande à l'utilisateur de s'authentifier par biométrie.

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

await NativeBiometric.verifyIdentity();

getCredentials

Récupère les identifiants stockés pour un serveur donné.

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

Stocke les identifiants fournis pour un serveur donné.

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

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

deleteCredentials

Supprime les identifiants stockés pour un serveur donné.

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

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

getSecureCredentials

Récupère les identifiants stockés pour un serveur donné, nécessitant une authentification biométrique. Les identifiants doivent avoir été stockés avec l'accessControl défini sur BIOMETRY_CURRENT_SET ou BIOMETRY_ANY.

Sur iOS, le système affiche automatiquement le prompt biométrique lors de l'accès à l'élément Keychain protégé. Sur Android, le BiometricPrompt est affiché avec un CryptoObject lié à la clé de déchiffrement des identifiants.

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

Vérifie si les identifiants sont déjà enregistrés pour un serveur donné.

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

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

Référence de type

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

Résultat de la méthode isAvailable() indiquant la disponibilité de l'authentification biométrique.

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

Type de callback pour l'écouteur de changement de biométrie.

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

Source de vérité

Cette page est générée à partir de src/definitions.ts. Relancez la synchronisation lorsque l’API public change en amont.

Continuer depuis Getting Started

Si vous utilisez Prise en main pour planifier les flux d'authentification et de compte, le connecter à Utiliser @capgo/capacitor-native-biometric pour la capacité native dans l'utilisation de @capgo/capacitor-native-biometric, @capgo/capacitor-social-login pour les détails d'implémentation dans @capgo/capacitor-social-login @capgo/capacitor-passkey pour les détails d'implémentation dans @capgo/capacitor-passkey @capgo/capacitor-native-biometric pour les détails d'implémentation dans @capgo/capacitor-native-biometric, et Authentification à deux facteurs pour les détails d'implémentation de l'authentification à deux facteurs.