如何在 Android 项目中使用 Android-Goldfinger 实现生物识别认证(附完整代码)

如何在 Android 项目中使用 Android-Goldfinger 实现生物识别认证(附完整代码)【免费下载链接】Android-GoldfingerAndroid library to simplify Biometric authentication implementation.项目地址: https://gitcode.com/gh_mirrors/an/Android-GoldfingerAndroid-Goldfinger是一款用于简化 Android 生物识别认证Biometric authentication实现的轻量级开源库。它基于官方的 BiometricPrompt 与 BiometricManager 深度封装把指纹、人脸等生物识别认证的接入流程压缩到几行代码同时提供加密解密、RxJava 响应式等进阶能力。本文将手把手带你完成从依赖引入、设备检测、弹窗配置到认证成功回调的完整接入流程并附上可直接运行的完整代码。 提示官方已将本库标记为 Deprecated不再维护但它依然是理解 Android 生物识别认证封装思路的优秀范例也适合仍在维护老项目的开发者参考。为什么选择 Android-Goldfinger 做生物识别认证直接用原生 BiometricPrompt 实现生物识别认证往往要处理大量样板代码例如检测设备硬件与已录入的生物信息手动构建 PromptInfo 弹窗参数在回调里区分成功、失败以及各种错误码加密/解密场景下还要自行管理 Cipher、IV 等底层细节Android-Goldfinger 把这些细节全部收敛到Goldfinger接口背后核心入口在core/src/main/java/co/infinum/goldfinger/Goldfinger.java对外提供四大核心能力方法作用典型场景authenticate()仅做生物识别认证支付确认、敏感操作放行encrypt()认证成功后加密并保存数据生物识别自动登录decrypt()认证成功后解密数据自动登录时还原登录凭据cancel()取消当前进行中的认证页面退出时清理资源库的最小支持版本是 Android API 14且 Android 6.0 以下的设备会自动回退到GoldfingerMock老机型兼容性处理也已替你做好。在 Android 项目中接入 Android-Goldfinger 的详细步骤第 1 步添加 mavenCentral 仓库与依赖先在项目级build.gradle中加入 mavenCentral 仓库buildscript { repositories { mavenCentral() } }再在模块级build.gradle中添加依赖implementation com.infinum:goldfinger:2.2.0第 2 步初始化 Goldfinger 实例初始化代码非常简洁一行即可完成Goldfinger goldfinger new Goldfinger.Builder(this) .logEnabled(true) // 开启调试日志便于排查问题 .build();第 3 步检查设备是否支持生物识别认证发起认证前务必先做前置检查避免弹窗调起后才发现无法认证的尴尬if (goldfinger.canAuthenticate(BiometricManager.Authenticators.BIOMETRIC_WEAK)) { // 设备可用可以开始认证 } else if (!goldfinger.hasBiometricHardware(BiometricManager.Authenticators.BIOMETRIC_WEAK)) { // 设备没有生物识别硬件 } else if (!goldfinger.hasEnrolledBiometrics(BiometricManager.Authenticators.BIOMETRIC_WEAK)) { // 用户尚未录入指纹或人脸可引导去系统设置 }这三个检查方法底层对应BiometricManager的能力查询完整定义见core/src/main/java/co/infinum/goldfinger/Goldfinger.java。第 4 步配置生物识别认证弹窗PromptParamsPromptParams 与官方 BiometricPrompt.PromptInfo 一一对应且支持以 Activity 或 Fragment 作为弹窗宿主Goldfinger.PromptParams params new Goldfinger.PromptParams.Builder(activity) .title(指纹验证) .subtitle(请验证指纹以继续) .description(用于确认本次支付操作) .negativeButtonText(取消) .allowedAuthenticators(BiometricManager.Authenticators.BIOMETRIC_WEAK) .build();第 5 步发起生物识别认证并处理回调goldfinger.authenticate(params, new Goldfinger.Callback() { Override public void onResult(NonNull Goldfinger.Result result) { switch (result.type()) { case SUCCESS: // 认证成功result.value() 在加密/解密模式下才有值 break; case INFO: // 认证仍在进行中如 AUTHENTICATION_START break; case ERROR: // 认证失败通过 result.reason() 获取具体原因 break; } } Override public void onError(NonNull Exception e) { // 发生了无法恢复的严重错误 } });注意onResult在一次认证过程中可能被多次调用请务必根据result.type()与result.reason()区分不同状态。第 6 步用加密/解密实现生物识别自动登录这是 Android-Goldfinger 最实用的场景用户首次用密码登录后把凭据加密保存下次启动时通过生物识别认证自动解密登录体验与主流 App 完全一致。加密保存登录成功后调用goldfinger.encrypt(params, login_key, password, new Goldfinger.Callback() { Override public void onResult(NonNull Goldfinger.Result result) { if (result.type() Goldfinger.Type.SUCCESS) { String encrypted result.value(); // 加密后的密文可存入 SharedPreferences } } // 别忘了实现 onError(...) });解密还原下次启动时调用goldfinger.decrypt(params, login_key, encryptedPin, new Goldfinger.Callback() { Override public void onResult(NonNull Goldfinger.Result result) { if (result.type() Goldfinger.Type.SUCCESS) { String pin result.value(); // 还原出原始密码用于自动登录 } } // 别忘了实现 onError(...) });完整参考实现可以看示例工程example/src/main/java/co/infinum/example/LoginActivity.java。这里的 key 参数用于内部存储 Cipher IV同一对加密/解密必须使用相同的 key否则无法正确还原。使用 RxGoldfinger 实现响应式生物识别认证如果你的项目已经引入 RxJava推荐接入独立的 rx 模块把认证流程变成可组合的 Observable再也不用写繁琐的回调implementation com.infinum:goldfinger:2.2.0 implementation com.infinum:goldfinger-rx:2.2.0RxGoldfinger goldfinger new RxGoldfinger.Builder(this).build(); goldfinger.authenticate(params) .subscribe(new DisposableObserverGoldfinger.Result() { Override public void onNext(Goldfinger.Result result) { // 处理每一次认证回调 } Override public void onError(Throwable e) { // 严重错误处理 } Override public void onComplete() { // 认证流程结束 } });RxGoldfinger 的接口定义在rx/src/main/java/co/infinum/goldfinger/rx/RxGoldfinger.java方法签名与普通版本完全对齐几乎没有额外的学习成本。生物识别认证失败的处理最佳实践Goldfinger 把认证结果统一收敛为Result.type()SUCCESS / INFO / ERROR与Result.reason()两个维度常见失败原因及建议处理方式整理如下Reason含义建议处理USER_CANCELED用户主动取消静默处理不打扰用户NEGATIVE_BUTTON用户点击了取消按钮通常引导用户改用密码登录NO_BIOMETRICS / HW_NOT_PRESENT未录入生物信息 / 无硬件引导用户去系统设置录入LOCKOUT / LOCKOUT_PERMANENT失败次数过多被锁定提示稍后再试或降级为密码TIMEOUT认证超时可让用户重新发起认证同时记得在页面销毁或用户离开时调用goldfinger.cancel()取消进行中的认证避免回调泄漏或内存问题。Android-Goldfinger 源码结构导读想深入了解实现原理或做二次开发的读者可以按以下路径阅读核心模块core/src/main/java/co/infinum/goldfinger/Goldfinger.java对外接口、PromptParams、Result、Callback 等全部模型定义core/src/main/java/co/infinum/goldfinger/GoldfingerImpl.java核心实现内部封装 BiometricPrompt 全流程core/src/main/java/co/infinum/goldfinger/GoldfingerMock.javaAndroid 6.0 以下设备的降级实现core/src/main/java/co/infinum/goldfinger/crypto/impl/AesCipherFactory.java默认 AES 加密工厂core/src/main/java/co/infinum/goldfinger/crypto/impl/Base64CipherCrypter.java默认 Base64 加解码实现rx/src/main/java/co/infinum/goldfinger/rx/RxGoldfingerImpl.javaRxJava 响应式封装实现example/src/main/java/co/infinum/example/完整可运行的示例工程登录、支付、设置等场景获取完整示例代码示例工程中已经包含登录、支付、设置等多个完整场景的实现可以通过 git clone 获取全部源码git clone https://gitcode.com/gh_mirrors/an/Android-Goldfinger小结通过本文你应该已经掌握了 Android-Goldfinger 的完整接入方法如何引入依赖、如何完成设备检查与弹窗配置、如何用 authenticate / encrypt / decrypt 实现生物识别认证与自动登录以及如何通过 RxGoldfinger 走响应式开发路线。整套流程代码量极小、结构清晰非常适合在支付确认、登录验证等需要生物识别认证的场景中快速落地。【免费下载链接】Android-GoldfingerAndroid library to simplify Biometric authentication implementation.项目地址: https://gitcode.com/gh_mirrors/an/Android-Goldfinger创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考