快速入门

安装

你可以使用我们的 AI 辅助设置来安装插件。使用以下命令将 Capgo skills 添加到你的 AI 工具中：

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

然后使用以下 prompt：

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

如果你更想手动设置，请运行以下命令安装插件，并按照下方各平台的说明操作：

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

请先通过以下方式存储密钥 setCredentials 以及 accessControl 当你需要在读取时启用生物识别保护。

示例：使用以下方式解锁 verifyIdentity

getSecureCredentials() 当凭据使用生物识别时，已经会弹出提示 accessControl. 用于 verifyIdentity() 用于其他受限操作，并将取消或锁定引导至密码流程。

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

示例：登出会清除 Vault 条目

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

示例：响应生物识别注册变化

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

常见坑点

• getSecureCredentials 需要先 accessControl：保存时使用生物识别访问标志，或使用 getCredentials 而无需额外提示。
• 用户锁定：处理 BiometricAuthError.USER_LOCKOUT 以及 BiometricAuthError.USER_TEMPORARY_LOCKOUT 来自 verifyIdentity 并配合冷却 UI。
• 模拟器：测试前请先在模拟器中录入指纹或面容。

API 概览

isAvailable

检查生物识别认证硬件是否可用。

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

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

verifyIdentity

提示用户使用生物识别认证。

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

await NativeBiometric.verifyIdentity();

getCredentials

获取指定服务器已存储的凭据。

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

为指定服务器存储给定的凭据。

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

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

deleteCredentials

删除指定服务器已存储的凭据。

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

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

getSecureCredentials

获取指定服务器的已存储凭据，需通过生物识别身份验证。 凭据在存储时，accessControl 必须设置为 BIOMETRY_CURRENT_SET 或 BIOMETRY_ANY。

在 iOS 上，访问受保护的 Keychain 项目时，系统会自动显示生物识别 prompt。 在 Android 上，会显示绑定了凭据解密密钥的 CryptoObject 的 BiometricPrompt。

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

检查指定服务器是否已保存凭据。

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

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

类型参考

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

isAvailable() 方法的结果，表示生物识别认证是否可用。

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

生物识别变更监听器的回调类型。

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

单一事实来源

本页面由插件的 src/definitions.ts生成。当上游的公共 API 发生变化时，请重新运行 sync。

从入门指南继续

如果你正在使用 快速入门 用来规划身份验证和账户流程，并将它与 使用 @capgo/capacitor-native-biometric 有关“使用 @capgo/capacitor-native-biometric”中的原生能力， @capgo/capacitor-social-login 在 @capgo/capacitor-social-login 中查看实现细节， @capgo/capacitor-passkey 有关 @capgo/capacitor-passkey 的实现细节， @capgo/capacitor-native-biometric 以及 @capgo/capacitor-native-biometric 中的实现细节， 双因素认证 有关双重身份验证的实现细节。