跳转到内容
Capgo - Live Updates for Capacitor Apps Capgo

入门

  1. 安装软件包

    Terminal window
    npm i @capgo/capacitor-native-biometric

  2. 与原生项目同步

    Terminal window
    npx cap sync

  3. 配置权限

    iOS

    Section titled “iOS”

    将 Face ID 使用说明添加到您的 Info.plist 中：

    <key>NSFaceIDUsageDescription</key>
    <string>Authenticate securely to access your account</string>

    Android

    Section titled “Android”

    将生物识别权限添加到您的 AndroidManifest.xml：

    <uses-permission android:name="android.permission.USE_BIOMETRIC" />

  4. 在提示之前检查可用性 在显示身份验证 UI 之前，请务必检查完整的可用性详细信息。

用法

Section titled “用法”

导入插件并使用其方法进行生物识别身份验证：

import {
  NativeBiometric,
  BiometryType,
  AuthenticationStrength,
  AccessControl,
} from '@capgo/capacitor-native-biometric';


const checkBiometric = async () => {
  const result = await NativeBiometric.isAvailable({ useFallback: true });
  console.log('Biometric available:', result.isAvailable);
  console.log('Strength:', result.authenticationStrength); // STRONG | WEAK | NONE
  console.log('Primary type:', result.biometryType);
  console.log('Device is secure:', result.deviceIsSecure);
  console.log('Strong biometry:', result.strongBiometryIsAvailable);
};


const verify = async () => {
  await NativeBiometric.verifyIdentity({
    reason: 'Open secure section',
    title: 'Biometric Login',
    subtitle: 'Unlock with face, fingerprint, or credentials',
    description: 'Authenticate to continue',
    negativeButtonText: 'Cancel',
    maxAttempts: 5,
    allowedBiometryTypes: [BiometryType.FINGERPRINT, BiometryType.FACE_ID],
  });
};


const saveCredentials = async () => {
  await NativeBiometric.setCredentials({
    username: 'user@example.com',
    password: 'securepassword',
    server: 'https://api.example.com',
    accessControl: AccessControl.BIOMETRY_ANY,
  });
};


const getCredentials = async () => {
  const credentials = await NativeBiometric.getSecureCredentials({
    server: 'https://api.example.com',
    reason: 'Sign in again',
    title: 'Confirm identity',
  });
  console.log(credentials.username);
};


const alreadySaved = async () => {
  const { isSaved } = await NativeBiometric.isCredentialsSaved({
    server: 'https://api.example.com',
  });
  console.log('Credentials saved:', isSaved);
};


const cleanup = async () => {
  await NativeBiometric.deleteCredentials({
    server: 'https://api.example.com',
  });
};


const watchChanges = async () => {
  const handle = await NativeBiometric.addListener('biometryChange', (result) => {
    console.log('Biometry availability changed:', result.isAvailable);
    console.log('Type:', result.biometryType);
  });


  // Remove when no longer needed
  // await handle.remove();
};

API 参考

Section titled “API 参考”

可用（选项）

Section titled “可用（选项）”

检查设备上是否可以使用生物识别身份验证。

interface IsAvailableOptions {
  useFallback: boolean;
}


interface AvailableResult {
  isAvailable: boolean;
  authenticationStrength: AuthenticationStrength; // STRONG | WEAK | NONE
  biometryType: BiometryType;
  deviceIsSecure: boolean;
  strongBiometryIsAvailable: boolean;
  errorCode?: number;
}

验证身份（选项）

Section titled “验证身份（选项）”

提示进行生物识别身份验证。

interface BiometricOptions {
  reason?: string;
  title?: string;
  subtitle?: string;
  description?: string;
  negativeButtonText?: string;
  useFallback?: boolean;
  fallbackTitle?: string;
  maxAttempts?: number; // Android only
  allowedBiometryTypes?: BiometryType[];
}

setCredentials（选项）

Section titled “setCredentials（选项）”

存储凭据。使用 accessControl 在支持的平台上强制执行仅生物识别检索。

interface SetCredentialOptions {
  username: string;
  password: string;
  server: string;
  accessControl?: AccessControl;
}

getSecureCredentials（选项）

Section titled “getSecureCredentials（选项）”

仅当受保护条目的身份验证成功时才获取存储的凭据。

interface GetSecureCredentialsOptions {
  server: string;
  reason?: string;
  title?: string;
  subtitle?: string;
  description?: string;
  negativeButtonText?: string;
}

isCredentialsSaved（选项）

Section titled “isCredentialsSaved（选项）”

检查服务器条目的凭据是否存在。

interface IsCredentialsSavedOptions {
  server: string;
}


interface IsCredentialsSavedResult {
  isSaved: boolean;
}

删除凭证（选项）

Section titled “删除凭证（选项）”

删除服务器条目存储的凭据。

interface DeleteCredentialOptions {
  server: string;
}

addListener(‘biometryChange’, …)

Section titled “addListener(‘biometryChange’, …)”

监听生物识别变化并安全地恢复流程。

const handle = await NativeBiometric.addListener('biometryChange', (result) => {
  // result: AvailableResult
});

平台差异

Section titled “平台差异”

iOS

Section titled “iOS”
  • 支持面容 ID 和触摸 ID
  • useFallback 遵循配置的密码回退行为

Android

Section titled “Android”
  • 支持指纹、面部、虹膜和 PIN/图案/密码流
  • Android 约束适用于后备 UI 和生物识别类型限制

最佳实践

Section titled “最佳实践”
  1. 始终首先检查可用性
  2. 使用完整结果数据来选择安全路线
  3. 对于敏感数据首选安全凭证模式
  4. 优雅地处理取消和错误
  5. 当不再需要监听器时删除它们

相关文档

Section titled “相关文档”