AndroidX Biometric 生物识别登录实现指南

AndroidX Biometric 是 Google 提供的生物识别认证库，支持指纹、面容等生物识别方式，兼容 Android 6.0 以上设备。本文从依赖配置到完整代码示例，详细介绍如何在项目中集成生物识别登录功能。

1、添加依赖

在 build.gradle 的 dependencies 节点下增加：

implementation "androidx.biometric:biometric:1.1.0"

建议使用最新版本，可在 Google Maven 仓库查看最新版本号。

2、权限配置

指纹相关权限在 AndroidManifest.xml 配置（部分机型可以不需要，建议添加）：

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

3、基本用法流程

生物识别认证分为四个步骤：
• 步骤一：创建 BiometricPrompt，需要传入一个 FragmentActivity 或 Fragment 作为生命周期管理者
• 步骤二：设置回调 BiometricPrompt.AuthenticationCallback
   - onAuthenticationSucceeded：认证成功
   - onAuthenticationFailed：认证失败（如手指没对准）
   - onAuthenticationError：系统错误、取消或设备不支持等其他问题
• 步骤三：构建 PromptInfo（对话框的标题、内容）
• 步骤四：调用 authenticate() 开始认证

4、完整示例代码（Kotlin）

import androidx.biometric.BiometricPrompt
import androidx.core.content.ContextCompat
import android.os.Bundle
import androidx.appcompat.app.AppCompatActivity

class BiometricActivity : AppCompatActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        val executor = ContextCompat.getMainExecutor(this)

        val callback = object : BiometricPrompt.AuthenticationCallback() {
            override fun onAuthenticationSucceeded(result: BiometricPrompt.AuthenticationResult) {
                super.onAuthenticationSucceeded(result)
                // 认证通过
            }

            override fun onAuthenticationFailed() {
                super.onAuthenticationFailed()
                // 未识别到，此时认证还在进行，用户可能还会继续尝试
            }

            override fun onAuthenticationError(errorCode: Int, errString: CharSequence) {
                super.onAuthenticationError(errorCode, errString)
                // 错误或取消、设备不支持等，认证弹框已经消失
            }
        }

        val biometricPrompt = BiometricPrompt(this, executor, callback)

        val promptInfo = BiometricPrompt.PromptInfo.Builder()
            .setTitle("指纹/面容认证")
            .setSubtitle("请验证您的身份")
            .setAllowedAuthenticators(BIOMETRIC_STRONG or DEVICE_CREDENTIAL)
            .setConfirmationRequired(false)
            .build()

        biometricPrompt.authenticate(promptInfo)
    }
}

5、检查设备支持与用户已录入生物信息

在开始认证前，建议做兼容性判断：

import androidx.biometric.BiometricManager

val manager = BiometricManager.from(context)
when (manager.canAuthenticate(BiometricManager.Authenticators.BIOMETRIC_WEAK)) {
    BiometricManager.BIOMETRIC_SUCCESS -> {
        // 支持并已录入（可以弹窗）
    }
    BiometricManager.BIOMETRIC_ERROR_NO_HARDWARE -> {
        // 没有硬件
    }
    BiometricManager.BIOMETRIC_ERROR_HW_UNAVAILABLE -> {
        // 硬件不可用
    }
    BiometricManager.BIOMETRIC_ERROR_NONE_ENROLLED -> {
        // 用户没录入生物信息
    }
}

6、常见注意事项

• Fragment 里同样使用，直接传入 fragment 实例即可
• BiometricPrompt 弹窗一定要在 UI 线程调用，不然回调不会返回到正确线程
• setDeviceCredentialAllowed(true) 可兼容系统锁屏密码（如PIN），androidx.biometric 1.1.0+ 才支持
• 认证成功后回调返回主线程，可安全进行UI操作

7、常见报错处理

报错信息：Negative text must not be set if device credential authentication is allowed.

原因分析：当调用 PromptInfo.Builder().setDeviceCredentialAllowed(true) 允许了设备凭证，弹窗会自动显示"使用设备密码/指纹/面容"等选项。此时不能再设置 setNegativeButtonText("取消")，否则会报该错误。

解决方案：
方案一：允许设备凭证时，不要设置 negative button

val promptInfo = BiometricPrompt.PromptInfo.Builder()
    .setTitle("生物认证")
    .setSubtitle("请验证")
    .setDeviceCredentialAllowed(true)
    .build()

方案二：不需要设备凭证，只用生物识别，则可以自由设置 negative button

val promptInfo = BiometricPrompt.PromptInfo.Builder()
    .setTitle("生物认证")
    .setSubtitle("请验证")
    .setDeviceCredentialAllowed(false)
    .setNegativeButtonText("取消")
    .build()

8、总结

setDeviceCredentialAllowed(true) 和 setNegativeButtonText() 只能二选一，不能共存。按需设计弹窗，业务上如需"取消"按钮，只用生物识别；如需兼容系统密码，则别自定义"取消"。

基本流程总结：
1. 依赖库、权限准备
2. 判断硬件和用户信息
3. 实例化 BiometricPrompt，设置回调
4. 构造 PromptInfo（自定义弹窗内容）
5. 调用 authenticate 启动认证流程

AndroidX Biometric 生物识别登录实现指南