Android-Goldfinger API 完全参考Goldfinger 接口方法逐个解析【免费下载链接】Android-GoldfingerAndroid library to simplify Biometric authentication implementation.项目地址: https://gitcode.com/gh_mirrors/an/Android-Goldfinger如果你正在寻找一个能大幅简化 Android 生物识别Biometric接入流程的开源库Android-Goldfinger 绝对值得一试。它把 Android 官方 BiometricPrompt 繁琐的初始化、CryptoObject 创建和结果回调封装成了几个简单直观的接口方法。本文作为 Goldfinger 的完整 API 参考将带你逐个解析Goldfinger接口的每一个方法、Builder 配置项以及结果类型让你在 10 分钟内掌握这套生物识别封装库的全部用法。一、快速认识 Goldfinger 接口Goldfinger是整个库的核心接口定义在 Goldfinger.java 中。它主要分为三类能力硬件与状态检测检查设备是否有生物识别硬件、是否录入过指纹认证操作执行认证、加密、解密、取消结果反馈通过枚举和回调返回每一步的状态Goldfinger goldfinger new Goldfinger.Builder(context).build();在 Android 6.0API 23及以上Builder 会返回真正的实现类GoldfingerImpl见 GoldfingerImpl.java更老的系统则自动降级为GoldfingerMock见 GoldfingerMock.java所有方法返回空值无需你额外做兼容判断。二、设备能力检测方法认证前的三道检查1. 检查生物识别硬件是否可用hasFingerprintHardware()/hasFingerprintHardware(int authenticators)已废弃推荐用下面方法hasBiometricHardware(int authenticators)推荐判断设备是否存在生物识别硬件authenticators参数用于指定认证类型常用BiometricManager.Authenticators.BIOMETRIC_WEAK。2. 检查是否已录入生物识别信息hasEnrolledFingerprint()/hasEnrolledFingerprint(int authenticators)已废弃hasEnrolledBiometrics(int authenticators)推荐判断用户是否已在系统设置中录入指纹或面容3. 一条龙检查canAuthenticatecanAuthenticate()已废弃canAuthenticate(int authenticators)推荐同时检查硬件、录入状态和系统状态返回true才说明当前可以发起认证if (goldfinger.canAuthenticate(Goldfinger.TYPE_BIOMETRIC_WEAK)) { // 可以开始认证 }这组方法内部都封装了BiometricManager.canAuthenticate()的返回值判断是你在弹窗前的必经检查步骤。三、核心认证方法authenticate、encrypt、decrypt 与 cancel1. authenticate最基础的生物识别认证authenticate(PromptParams params, Callback callback)只做身份验证不涉及任何加解密。适合支付确认、解锁应用等纯验证场景。2. encrypt / decrypt认证同时加解密数据encrypt(PromptParams params, String key, String value, Callback callback)认证成功后自动用解锁的 CryptoObject 加密valuedecrypt(PromptParams params, String key, String value, Callback callback)认证成功后自动解密用于读取之前加密保存的数据这对方法适合记住密码自动登录的场景先把用户密码加密后存进 SharedPreferences下次登录时解密。key用于在系统密钥库中标识密钥。3. cancel随时取消认证cancel()会中断当前正在进行的认证同时清理内部状态避免内存泄漏。四、Builder一行代码完成自定义配置Goldfinger.Builder同样定义在 Goldfinger.java提供以下链式配置方法作用cipherFactory()/cipherCrypter()自定义加解密算法默认使用 AesCipherFactory.java 与 Base64CipherCrypter.javamacFactory()/macCrypter()使用 Mac 类型 CryptoObject两者必须同时提供signatureFactory()/signatureCrypter()使用 Signature 类型 CryptoObject两者必须同时提供logEnabled(true)开启内部日志默认关闭方便排查问题Goldfinger goldfinger new Goldfinger.Builder(context) .logEnabled(true) .build();注意Mac 或 Signature 的 Factory 与 Crypter 必须成对设置否则build()会抛出异常。五、PromptParams定制认证弹窗PromptParams是认证弹窗的参数模型对应 Android 官方的BiometricPrompt.PromptInfo。通过它的内部 Builder 可设置title()/subtitle()/description()标题、副标题和描述文案negativeButtonText()取消按钮文字confirmationRequired(true)是否要求确认操作allowedAuthenticators()允许的认证方式Goldfinger.PromptParams params new Goldfinger.PromptParams.Builder(activity) .title(验证指纹) .negativeButtonText(取消) .build();构造时既支持传入FragmentActivity也支持传入Fragment。六、Callback、Result、Type 与 Reason理解回调结果Callback 回调接口每个认证方法都需要传入Goldfinger.Callback它有两个回调onResult(Result result)认证过程中会多次触发返回每次状态变化onError(Exception e)发生致命错误如硬件缺失、参数非法时触发Result 结果对象Result封装了认证结果包含四个信息type()结果类型、reason()原因、value()加密/解密后的值、message()系统错误提示。Type 三种结果类型SUCCESS认证成功若是 encrypt/decryptvalue()中有密文或明文INFO认证进行中例如用户指纹匹配失败AUTHENTICATION_FAILERROR认证失败通过reason()查看具体原因Reason 失败原因枚举Reason枚举几乎覆盖了所有错误场景包括LOCKOUT尝试次数过多被锁定、LOCKOUT_PERMANENT永久锁定、USER_CANCELED用户取消、NEGATIVE_BUTTON点击了取消按钮、TIMEOUT超时等。完整的错误码到枚举的转换逻辑见 EnumConverter.java。if (result.type() Goldfinger.Type.SUCCESS) { String pin result.value(); // 解密后的数据 }七、Rx 模块响应式编程支持如果你使用 RxJavaGoldfinger 还提供了单独的 Rx 封装模块 RxGoldfinger.java。接口方法一一对应只是把 Callback 换成了ObservableResultRxGoldfinger.Builder(context).build() .authenticate(params) .subscribe(result - { /* 处理结果 */ });RxGoldfingerImpl 的实现逻辑见 RxGoldfingerImpl.java内部依然委托给标准的 Goldfinger 实例。八、最佳实践小结认证前必查先调用canAuthenticate()再决定是否弹出认证框加密场景用 encrypt/decrypt保存密码、令牌等敏感数据时不要存明文区分 INFO 与 ERROR指纹匹配失败是 INFO可重试锁定、取消才是 ERROR及时 cancel页面销毁时调用cancel()避免回调泄漏Rx 项目用 RxGoldfinger与 RxJava 生态无缝衔接代码更优雅至此你已经掌握了 Android-Goldfinger 的完整 API 参考。从状态检测、认证执行到结果解析这套接口设计简洁且覆盖全面是 Android 生物识别接入中非常值得参考的封装范例。【免费下载链接】Android-GoldfingerAndroid library to simplify Biometric authentication implementation.项目地址: https://gitcode.com/gh_mirrors/an/Android-Goldfinger创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考