React Native Android端Face ID认证实现问题咨询

一、问题根源 #

react-native-keychain 旧版本在Android端默认仅检测指纹传感器，未适配Google官方的BiometricPrompt框架——该框架支持自动识别设备上已启用的所有合规生物识别方式（包括面部、指纹），因此即使设备录入了面部解锁，也只会被判定为支持指纹。

二、解决方案 #

1. 升级react-native-keychain至最新版本 #

新版本已完全适配BiometricPrompt，可自动检测设备支持的生物识别类型：

# npm 安装
npm install react-native-keychain@latest
# yarn 安装
yarn add react-native-keychain@latest

2. 配置Android权限 #

在AndroidManifest.xml中添加生物识别相关权限：

<!-- 适配Android 9及以上的生物识别权限 -->
<uses-permission android:name="android.permission.USE_BIOMETRIC" />
<!-- 兼容旧版本指纹权限（可选） -->
<uses-permission android:name="android.permission.USE_FINGERPRINT" />

3. 修改认证调用逻辑 #

使用BIOMETRIC_STRONG类型触发系统级强生物识别，框架会自动调用设备上已启用的面部/指纹认证：

import * as Keychain from 'react-native-keychain';

// 检查当前支持的生物识别类型
const checkBiometricSupport = async () => {
  const supportType = await Keychain.getSupportedBiometryType();
  // 返回值：'TouchID'（指纹）、'FaceID'（面部）或 undefined（无可用方式）
  console.log('支持的生物识别类型:', supportType);
};

// 发起生物识别认证
const authenticate = async () => {
  try {
    const credentials = await Keychain.getGenericPassword({
      authenticationType: Keychain.AUTHENTICATION_TYPE.BIOMETRIC_STRONG,
      promptMessage: '请完成生物识别认证',
    });
    // 认证成功逻辑
    console.log('认证成功:', credentials);
  } catch (error) {
    console.log('认证失败/取消:', error);
  }
};

4. 替代方案（若升级后仍有兼容问题） #

若新版本react-native-keychain仍无法识别面部，可替换为react-native-biometrics库，它对Android生物识别的适配更细致：

npm install react-native-biometrics

基础调用示例：

import ReactNativeBiometrics from 'react-native-biometrics';

const rnBiometrics = new ReactNativeBiometrics();

// 检测可用生物识别类型
const checkBiometrics = async () => {
  const { available, biometryType } = await rnBiometrics.isSensorAvailable();
  if (available) {
    switch (biometryType) {
      case ReactNativeBiometrics.BiometryTypes.FaceID:
        console.log('支持面部解锁');
        break;
      case ReactNativeBiometrics.BiometryTypes.TouchID:
        console.log('支持指纹');
        break;
      case ReactNativeBiometrics.BiometryTypes.Biometrics:
        console.log('支持通用生物识别（Android系统兼容）');
        break;
    }
  } else {
    console.log('无可用生物识别方式');
  }
};

// 发起认证
const authenticateUser = async () => {
  const { success } = await rnBiometrics.simplePrompt({
    promptMessage: '请进行生物识别',
  });
  success ? console.log('认证成功') : console.log('认证失败');
};

三、Android面部解锁支持条件 #

• 系统版本：Android 10（API 29）及以上，原生支持面部解锁框架；部分Android 9设备通过厂商定制支持，但兼容性较差。
• 硬件要求：设备配备合规的前置面部识别传感器，且已在系统设置中录入面部信息。
• 权限配置：需在系统设置中开启「面部解锁」功能，并授予应用生物识别权限。

四、附：react-native-keychain文档截图翻译内容 #

生物识别认证类型说明：

• AUTHENTICATION_TYPE.DEVICE_PASSCODE：使用设备密码（PIN/图案/密码）完成认证
• AUTHENTICATION_TYPE.BIOMETRIC_WEAK：弱生物识别（如部分厂商的低安全级面部解锁）
• AUTHENTICATION_TYPE.BIOMETRIC_STRONG：强生物识别（符合Android安全标准的指纹、面部识别，适用于敏感操作）

注意：Android端BiometricPrompt会自动选择设备上可用的最强生物识别方式，无需手动指定指纹或面部。

内容的提问来源于stack exchange，提问作者Nazim Musa