Android应用基于BiometricPrompt集成人脸识别的问题排查

1. 人脸识别专属的额外配置遗漏检查 #

• 权限声明：在AndroidManifest.xml中必须声明android.permission.USE_BIOMETRIC（API 28+），API 23-27需补充android.permission.USE_FINGERPRINT（人脸识别优先依赖USE_BIOMETRIC）。无需动态申请该权限，但要确保系统设置中已允许当前应用使用人脸识别权限（部分设备需手动开启应用的生物识别权限）。
• 验证生物类型范围：初始化BiometricPrompt.PromptInfo时，必须通过setAllowedAuthenticators()指定包含人脸识别的验证类型，例如：

  val promptInfo = BiometricPrompt.PromptInfo.Builder()
      .setTitle("身份验证")
      .setAllowedAuthenticators(BIOMETRIC_STRONG or DEVICE_CREDENTIAL)
      // 若设备人脸识别为弱验证级别，改用BIOMETRIC_WEAK or DEVICE_CREDENTIAL
      .build()
  

  若仅指定FINGERPRINT，则只会触发指纹识别，不会调用人脸识别。
• 设备支持性检查：调用BiometricManager.from(context).canAuthenticate(BIOMETRIC_STRONG)（或BIOMETRIC_WEAK）确认设备是否支持对应级别的人脸识别，避免因验证级别不匹配导致功能失效。

2. BiometricPrompt 或 CryptoObject 初始化的影响 #

• BiometricPrompt 初始化上下文：必须使用Activity 上下文而非 Application 上下文创建BiometricPrompt，否则可能无法正确唤起系统人脸识别界面。
• CryptoObject 的使用场景：
  • 若仅需身份验证（无需加密操作），调用authenticate()时无需传入CryptoObject，这样可兼容更多生物识别类型（包括弱级人脸识别）。
  • 若必须使用CryptoObject，需检查密钥生成参数：创建密钥时需设置setUserAuthenticationRequired(true)，且不要限制仅指纹验证（部分密钥配置会绑定指纹，导致人脸识别无法触发）。示例：

    val keyGenParameterSpec = KeyGenParameterSpec.Builder(
        KEY_NAME,
        KeyProperties.PURPOSE_ENCRYPT or KeyProperties.PURPOSE_DECRYPT
    )
        .setBlockModes(KeyProperties.BLOCK_MODE_GCM)
        .setEncryptionPaddings(KeyProperties.ENCRYPTION_PADDING_NONE)
        .setUserAuthenticationRequired(true)
        // 若支持弱生物识别，添加以下配置（API 29+）
        .setUserAuthenticationValidityDurationSeconds(-1)
        .build()
    

• 回调逻辑排查：检查BiometricPrompt.AuthenticationCallback的onAuthenticationError()方法，查看错误码（如ERROR_BIOMETRIC_NOT_ENROLLED表示未录入人脸，ERROR_INVALID_AUTHENTICATOR表示验证类型不匹配），定位具体问题。

3. 版本与设备兼容性问题 #

• 最低版本要求：官方BiometricPrompt从API 28（Android 9.0）开始支持人脸识别，API 28以下需依赖厂商自定义实现（兼容性差，不推荐）。
• 生物识别级别区分：API 29（Android 10.0）引入BIOMETRIC_STRONG（强验证，如指纹、3D人脸）和BIOMETRIC_WEAK（弱验证，如2D人脸）的区分，需根据设备的人脸识别级别调整setAllowedAuthenticators()的参数。
• 厂商适配差异：部分厂商（如小米、华为）对BiometricPrompt有定制化实现，但同一设备其他应用可正常使用人脸识别，说明厂商适配无问题，需重点排查自身代码配置。

内容的提问来源于stack exchange，提问作者Hugo Oliveira