原生生物识别 Capacitor 插件

使用 @capgo/capacitor-native-biometric

该插件可调用 Android 和 iOS 的原生生物识别 API。

安装

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

bunx cap sync 将插件的原生 code 复制到你的原生项目中。每次升级插件后都要重新运行。

导入

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

API 概览

方法	描述
isAvailable	检查生物识别认证硬件是否可用。
verifyIdentity	提示用户使用生物识别认证。
getCredentials	获取指定服务器已存储的凭据。
setCredentials	为指定服务器存储给定的凭据。
deleteCredentials	删除指定服务器已存储的凭据。
getSecureCredentials	获取指定服务器已存储的凭据，此操作需要生物识别认证。凭据必须是在 accessControl 设置为 BIOMETRY_CURRENT_SET 或 BIOMETRY_ANY 时存储的。
isCredentialsSaved	检查指定服务器是否已保存凭据。
setData	在指定键下存储任意字符串值。值会通过平台安全存储后端（Android Keystore + SharedPreferences，iOS Keychain）进行静态加密。
getData	获取指定键此前存储的值。仅返回未使用生物识别保护存储的值。 accessControl.
getSecureData	获取指定键受生物识别保护的值。该值必须是在 accessControl 设置为 BIOMETRY_CURRENT_SET 或 BIOMETRY_ANY 时存储的。
deleteData	删除指定键（包括受保护和未受保护的键）的存储值。
isDataSaved	检查指定键是否已保存值。

示例

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 时存储的。

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.

上表列出了 12 个核心方法。监听器、版本辅助方法以及每个方法的完整接口约定，详见 GitHub 仓库.

监听事件

addListener 会返回一个句柄。调用 handle.remove() 当屏幕卸载时。

完整参考文档

• GitHub 仓库
• 文档
• API 参考文档

从“使用 @capgo/capacitor-native-biometric”继续

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