指纹登录

更新时间：2025-09-10 01:33:28下载pdf

概述

指纹登录 SDK 是基于 Android Biometric API 的安全登录解决方案，支持指纹生物识别，提供了简易易用的接口，能够帮助开发者快速集成生物识别登录功能。

集成步骤

添加依赖

在您的应用模块的 build.gradle 文件中添加依赖：

dependencies {
    implementation 'com.thingclips.smart:thingsmart-biometrics-login:1.0.0'
     // App SDK 最新稳定安卓版
    implementation("com.thingclips.smart:thingsmart:6.7.3")
    implementation("androidx.biometric:biometric:1.1.0")
}

添加权限

在 AndroidManifest.xml 文件中添加必要的权限：

<!-- 生物识别权限 -->
<uses-permission android:name="android.permission.USE_BIOMETRIC" />
<uses-permission android:name="android.permission.USE_FINGERPRINT" />

<!-- 网络权限 -->
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />

API 接口说明

获取 SDK 实例

val biometricSDK = ThingBiometricsLoginSDK.getInstance()

检查设备支持

fun isSupportBiometricLogin(context: Context): Boolean

接口说明

检查设备是否支持生物识别登录。

参数说明

参数	说明
`context`	应用上下文

返回值

返回值	说明
`true`	设备支持生物识别
`false`	设备不支持生物识别

使用示例

val isSupported = biometricSDK.isSupportBiometricLogin(context)
if (isSupported) {
    // 设备支持生物识别，可以启用相关功能
} else {
    // 设备不支持生物识别，显示提示信息
}

检查用户状态

fun isBiometricLoginEnabled(uid: String): Boolean

接口说明

检查用户是否已启用生物识别登录。

参数说明

参数	说明
`uid`	用户唯一标识符

返回值

返回值	说明
`true`	用户已启用生物识别登录
`false`	用户未启用生物识别登录

使用示例

val isEnabled = biometricSDK.isBiometricLoginEnabled(userId)
if (isEnabled) {
    // 显示生物识别登录选项
} else {
    // 显示启用生物识别登录的引导
}

启用生物识别登录

fun enableBiometricLogin(
    activity: FragmentActivity,
    uid: String,
    callback: IThingBiometricFingerCallback
)

接口说明

启用用户的生物识别登录功能。

参数说明

参数	说明
`activity`	`FragmentActivity` 实例
`uid`	用户唯一标识符
`callback`	回调接口，处理认证结果

使用示例

biometricSDK.enableBiometricLogin(
    activity = this,
    uid = userId,
    callback = object : IThingBiometricFingerCallback {
        override fun onSuccess(user: User?) {
            // 生物识别登录启用成功
            showToast("生物识别登录已启用")
        }
        
        override fun onError(errorCode: String, errorMsg: String) {
            // 启用失败
            showToast("启用失败: $errorMsg")
        }
        
        override fun onNegative() {
            // 用户取消操作
            showToast("已取消启用")
        }
        
        override fun onFingerInfoInvalid() {
            // 指纹信息无效，需要重新设置
            showToast("指纹信息无效，请重新设置")
        }
    }
)

禁用生物识别登录

fun disableBiometricLogin(uid: String)

接口说明

禁用用户的生物识别登录功能。

参数说明

参数	说明
`uid`	用户唯一标识符

使用示例

biometricSDK.disableBiometricLogin(userId)
showToast("生物识别登录已禁用")

执行生物识别认证

fun authenticate(
    activity: FragmentActivity, 
    uid: String,
    accountName: String,
    countryCode: String,
    callback: IThingBiometricFingerCallback
)

接口说明

执行生物识别认证登录。

参数说明

参数	说明
`activity`	`FragmentActivity` 实例
`uid`	用户唯一标识符
`accountName`	账户名称
`countryCode`	国家代码
`callback`	回调接口，处理认证结果

使用示例

biometricSDK.authenticate(
    activity = this,
    uid = userId,
    accountName = "user@example.com",
    countryCode = "CN",
    callback = object : IThingBiometricFingerCallback {
        override fun onSuccess(user: User?) {
            // 认证成功，执行登录逻辑
            performLogin(user)
        }
        
        override fun onError(errorCode: String, errorMsg: String) {
            // 认证失败
            showToast("认证失败: $errorMsg")
        }
        
        override fun onNegative() {
            // 用户取消认证
            showToast("已取消认证")
        }
        
        override fun onFingerInfoInvalid() {
            // 指纹信息无效，需要重新启用
            showToast("指纹信息已失效，请重新启用生物识别登录")
        }
    }
)

检查指纹变化

fun hasBiometricChanged(uid: String): Boolean

接口说明

检查用户的指纹是否发生变化。

参数说明

参数	说明
`uid`	用户唯一标识符

返回值

返回值	说明
`true`	指纹已发生变化
`false`	指纹未发生变化

使用示例

val hasChanged = biometricSDK.hasBiometricChanged(userId)
if (hasChanged) {
    // 指纹已变化，需要重新启用生物识别登录
    showDialog("指纹信息已变化，请重新启用生物识别登录")
} else {
    // 指纹未变化，可以正常使用
}

回调接口说明

IThingBiometricFingerCallback

public interface IThingBiometricFingerCallback {
    /**
     * 生物识别操作成功
     * @param user 用户信息（认证时返回，启用时为空）
     */
    void onSuccess(@Nullable User user);

    /**
     * 生物识别操作失败
     * @param errorCode Android Biometric API 的错误码（字符串格式）
     * @param errorMsg Android 系统提供的错误信息
     */
    void onError(String errorCode, String errorMsg);

    /**
     * 用户取消操作
     */
    void onNegative();

    /**
     * 生物识别信息无效
     * 通常发生在指纹变化或密钥失效时
     */
    void onFingerInfoInvalid();
}

代码示例

class BiometricLoginActivity : AppCompatActivity() {
    private lateinit var binding: ActivityBiometricLoginBinding
    private val biometricSDK = ThingBiometricsLoginSDK.getInstance()
    private val testUid = "XXXX"
    private val testAccountName = "XXXX"
    private val testCountryCode = "AZ"

    @RequiresApi(Build.VERSION_CODES.M)
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        binding = ActivityBiometricLoginBinding.inflate(layoutInflater)
        setContentView(binding.root)

        initToolbar()
        initView()
    }

    private fun initToolbar() {
        supportActionBar?.title = "生物识别登录"
        supportActionBar?.setDisplayHomeAsUpEnabled(true)
    }

    override fun onSupportNavigateUp(): Boolean {
        onBackPressed()
        return true
    }

    @RequiresApi(Build.VERSION_CODES.M)
    private fun initView() {
        // 设置用户信息
        binding.tvName.text = "测试用户"

        // 设置防重复点击事件
        binding.ivFingerPrint.preventRepeatedClick { fingerLogin() }
        binding.tvFingerPrint.preventRepeatedClick { fingerLogin() }

        // 添加启用生物识别登录按钮的点击事件
        binding.tvEnableBiometric.preventRepeatedClick {
            enableBiometricLogin()
        }

        // 添加禁用生物识别登录按钮的点击事件
        binding.tvDisableBiometric.preventRepeatedClick {
            disableBiometricLogin()
        }

        // 检查设备是否支持生物识别
        checkBiometricSupport()
    }

    @RequiresApi(Build.VERSION_CODES.M)
    private fun checkBiometricSupport() {
        if (!biometricSDK.isSupportBiometricLogin(this)) {
            binding.tvEnableBiometric.isEnabled = false
            binding.tvDisableBiometric.isEnabled = false
            binding.ivFingerPrint.isEnabled = false
            binding.tvFingerPrint.isEnabled = false
            Toast.makeText(this, "设备不支持生物识别功能", Toast.LENGTH_LONG).show()
        }
    }

    @RequiresApi(Build.VERSION_CODES.M)
    private fun fingerLogin() {
        // 检查是否支持生物识别
        if (!biometricSDK.isSupportBiometricLogin(this)) {
            showErrorDialog("设备不支持生物识别")
            return
        }
        // 检查生物识别登录是否启用
        if (!biometricSDK.isBiometricLoginEnabled(testUid)) {
            showErrorDialog("生物识别登录未启用")
            return
        }

        // 检查指纹是否发生变化
        if (biometricSDK.hasBiometricChanged(testUid)) {
            showErrorDialog("指纹信息已变更，请重新设置")
            return
        }


        // 开始生物识别认证
        startBiometricAuthentication()
    }

    private fun disableBiometricLogin() {
        biometricSDK.disableBiometricLogin(testUid)
        Toast.makeText(this, "生物识别登录已禁用", Toast.LENGTH_SHORT).show()
    }

    private fun enableBiometricLogin() {
        // 检查是否支持生物识别
        if (!biometricSDK.isSupportBiometricLogin(this)) {
            Toast.makeText(this, "设备不支持生物识别", Toast.LENGTH_SHORT).show()
            return
        }

        biometricSDK.enableBiometricLogin(
            this,
            testUid,
            object : IThingBiometricFingerCallback {
                override fun onSuccess(user: User?) {
                    runOnUiThread {
                        Toast.makeText(this@BiometricLoginActivity, "生物识别登录已启用", Toast.LENGTH_SHORT).show()
                    }
                }

                override fun onError(errorCode: String?, errorMsg: String?) {
                    runOnUiThread {
                        if (!TextUtils.isEmpty(errorCode) && !TextUtils.isEmpty(errorMsg)) {
                            when (errorCode) {
                                BiometricManager.BIOMETRIC_ERROR_NO_HARDWARE.toString() -> {
                                    Toast.makeText(this@BiometricLoginActivity, "设备不支持生物识别", Toast.LENGTH_SHORT).show()
                                }
                                BiometricManager.BIOMETRIC_ERROR_HW_UNAVAILABLE.toString() -> {
                                    Toast.makeText(this@BiometricLoginActivity, "生物识别功能当前不可用", Toast.LENGTH_SHORT).show()
                                }
                                BiometricManager.BIOMETRIC_ERROR_NONE_ENROLLED.toString() -> {
                                    Toast.makeText(this@BiometricLoginActivity, "请先在系统设置中录入生物识别信息", Toast.LENGTH_LONG).show()
                                }
                                else -> {
                                    Toast.makeText(this@BiometricLoginActivity, errorMsg, Toast.LENGTH_SHORT).show()
                                }
                            }
                        }
                    }
                }

                override fun onNegative() {
                    runOnUiThread {
                        Toast.makeText(this@BiometricLoginActivity, "用户取消了生物识别设置", Toast.LENGTH_SHORT).show()
                    }
                }

                override fun onFingerInfoInvalid() {
                    runOnUiThread {
                        Toast.makeText(this@BiometricLoginActivity, "指纹信息无效，请检查系统指纹设置", Toast.LENGTH_SHORT).show()
                    }
                }
            }
        )
    }

    private fun startBiometricAuthentication() {
        // 禁用所有交互
        setViewsClickable(false)

        biometricSDK.authenticate(
            this,
            testUid,
            testAccountName,
            testCountryCode,
            object : IThingBiometricFingerCallback {
                override fun onSuccess(user: User?) {
                    runOnUiThread {
                        if (!isFinishing) {
                            // 启用所有交互
                            setViewsClickable(true)
                            Toast.makeText(this@BiometricLoginActivity, "生物识别登录成功", Toast.LENGTH_SHORT).show()
                            // 在实际应用中，这里应该跳转到主页面
                        }
                    }
                }

                override fun onError(errorCode: String?, errorMsg: String?) {
                    runOnUiThread {
                        // 启用所有交互
                        setViewsClickable(true)

                        if (!TextUtils.isEmpty(errorCode) && !TextUtils.isEmpty(errorMsg)) {
                            when (errorCode) {
                                BiometricManager.BIOMETRIC_ERROR_NO_HARDWARE.toString() -> {
                                    showErrorDialog("设备不支持生物识别")
                                }
                                BiometricManager.BIOMETRIC_ERROR_HW_UNAVAILABLE.toString() -> {
                                    Toast.makeText(this@BiometricLoginActivity, "生物识别功能当前不可用", Toast.LENGTH_SHORT).show()
                                }
                                BiometricManager.BIOMETRIC_ERROR_NONE_ENROLLED.toString() -> {
                                    Toast.makeText(this@BiometricLoginActivity, "请先在系统设置中录入生物识别信息", Toast.LENGTH_LONG).show()
                                }
                                else -> {
                                    Toast.makeText(this@BiometricLoginActivity, errorMsg, Toast.LENGTH_SHORT).show()
                                }
                            }
                        }
                    }
                }

                override fun onNegative() {
                    runOnUiThread {
                        // 启用所有交互
                        setViewsClickable(true)
                    }
                }

                override fun onFingerInfoInvalid() {
                    runOnUiThread {
                        // 启用所有交互
                        setViewsClickable(true)
                        // 1.新增指纹  2.系统存在指纹，但未开启锁屏密码(指纹不生效)
                        Toast.makeText(
                            this@BiometricLoginActivity,
                            "指纹信息无效，请检查系统指纹设置",
                            Toast.LENGTH_SHORT
                        ).show()
                    }
                }
            }
        )
    }

    private fun setViewsClickable(clickable: Boolean) {
        binding.ivFingerPrint.isClickable = clickable
        binding.tvFingerPrint.isClickable = clickable
        binding.tvEnableBiometric.isClickable = clickable
        binding.tvDisableBiometric.isClickable = clickable
    }

    private fun showErrorDialog(tips: String) {
        AlertDialog.Builder(this)
            .setTitle("提示")
            .setMessage(tips)
            .setPositiveButton("我知道了") { dialog, _ ->
                dialog.dismiss()
                // 在实际应用中，这里应该跳转到账号密码登录页
                Toast.makeText(this, "请使用其他方式登录", Toast.LENGTH_SHORT).show()
            }
            .setCancelable(false)
            .show()
    }
}

常见错误码

SDK 会传递 Android Biometric API 的标准错误码，常见的错误码请见下表：

错误码	说明	处理建议
BIOMETRIC_ERROR_HW_UNAVAILABLE	生物识别硬件不可用	提示用户稍后重试
BIOMETRIC_ERROR_HW_NOT_PRESENT	设备无生物识别硬件（指纹模块不可用）	隐藏生物识别功能
BIOMETRIC_ERROR_NONE_ENROLLED	用户未设置生物识别凭据	引导用户设置指纹
BIOMETRIC_ERROR_NO_HARDWARE	设备无生物识别硬件（无指纹模块）	隐藏生物识别功能
BIOMETRIC_ERROR_SECURITY_UPDATE_REQUIRED	需要安全更新	提示用户更新系统
BIOMETRIC_ERROR_UNSUPPORTED	不支持的生物识别类型	隐藏相关功能
BIOMETRIC_ERROR_TIMEOUT	认证超时	提示用户重试
BIOMETRIC_ERROR_UNABLE_TO_PROCESS	无法处理认证请求	提示用户重试
BIOMETRIC_ERROR_INSUFFICIENT	生物识别信息不足	引导用户重新设置
BIOMETRIC_ERROR_LOCKOUT	生物识别被锁定	提示用户稍后重试
BIOMETRIC_ERROR_VENDOR	厂商特定错误	查看具体错误信息
BIOMETRIC_ERROR_LOCKOUT_PERMANENT	生物识别永久锁定	需要重置
BIOMETRIC_ERROR_USER_CANCELED	用户取消操作	正常处理
BIOMETRIC_ERROR_NO_BIOMETRICS	无生物识别凭据	引导用户设置
BIOMETRIC_ERROR_HW_NOT_PRESENT	硬件不存在	隐藏生物识别功能

错误码的具体含义可能因 Android 版本和设备而异，建议根据错误信息进行相应处理。

最佳实践

权限检查：在使用生物识别功能前，始终检查设备支持情况。
网络检查：在执行生物识别操作前，检查网络连接状态。
状态管理：正确管理生物识别登录的启用/禁用状态。
错误处理：实现完整的错误处理逻辑，提供友好的用户提示。
安全考虑：生物识别信息变化时，及时清除相关数据。
用户体验：提供清晰的引导和反馈，避免用户困惑。
离线处理：考虑网络不可用时的降级处理方案。

注意事项

Android 版本：需要 Android 6.0 (API 23) 及以上版本。
硬件要求：设备必须支持生物识别硬件。
用户设置：用户必须在系统设置中配置生物识别凭据。
权限声明：确保在 AndroidManifest.xml 中声明了必要的权限。
- 生物识别权限：
  - USE_BIOMETRIC
  - USE_FINGERPRINT
- 网络权限：
  - INTERNET
  - ACCESS_NETWORK_STATE
  - ACCESS_WIFI_STATE
网络连接：确保设备有稳定的网络连接，用于用户认证和密钥管理。
生命周期：在 Activity 销毁前取消正在进行的生物识别操作。
线程安全：回调方法在主线程中执行，需要注意 UI 更新。

参考资料

如果您在使用过程中遇到问题，请优先参考以下资源：

Android Biometric API 官方文档
示例代码和最佳实践
错误日志和调试信息

上一篇账号详情

下一篇家庭管理