更新记录

1.1.0（2026-04-25）

支持Android、Harmony平台

1.0.1（2026-04-21）

代码结构调整

1.0.0（2025-09-25）

支持苹果生物认证

平台兼容性

uni-app(4.36)

uni-app x(4.36)

tt-apple-bioauth

🔐 多端生物认证 UTS 插件（displayName：多端生物认证），为 uni-app / uni-app x App 提供 iOS、Android、HarmonyOS NEXT 统一的生物识别能力：Face ID / Touch ID、系统指纹或人脸、鸿蒙 UserAuthenticationKit 等，接口侧统一为 face / fingerprint 等字符串。

包名历史为 tt-apple-bioauth，TTAppleBioauth* 等类型/方法名仍可用但已标为 deprecated，推荐全部改用 TTBiometricAuth / getTTBiometricAuth。

📖 目录

• SDK 版本与平台
• 各端环境与权限
• 快速开始
• 基础使用
• API 说明
• 错误处理
• 常见问题

SDK 版本与平台

文档参考

• LocalAuthentication (iOS)
• Android BiometricPrompt / androidx.biometric
• 鸿蒙：用户身份认证、权限模型以官方最新文档为准。

🚨 重要提示

• 必须使用含本插件的自定义基座/正式包调试，标准基座可能不包含 UTS 原生实现。
• iOS 模拟器无法完整验证 Face ID / Touch ID，Android / 鸿蒙也请在真机上测生物识别。
• 非 App（H5、小程序等）无本插件原生能力，请用 #ifdef APP 或分平台条件编译。

各端环境与权限

通用

• 用户需在系统设置中已开启对应生物识别，并已录入指纹/人脸等。
• getBiometryType() 在 App 上返回统一小写风格（如 face、fingerprint），不支持时多为 unsupported（以实际设备为准）。

iOS

• 使用 Face ID 时，在 Info.plist 配置 NSFaceIDUsageDescription（使用说明字符串）。
• 系统版本 12.0+。

Android

• minSdkVersion 建议 ≥ 23（以工程与 package.json 声明为准）。
• 在 AndroidManifest 中声明 USE_FINGERPRINT / USE_BIOMETRIC 等系统要求的权限（依模板与合并结果为准；插件已包含依赖 androidx.biometric:biometric）。

HarmonyOS NEXT

• 在应用 module（如 module.json5）中声明 ohos.permission.ACCESS_BIOMETRIC，并在 AppScope 等配置权限使用理由（string 资源），与 DCloud/鸿蒙打包要求一致。
• 首次调用会走系统授权/申请流程（以系统行为为准）。

环境配置（前置条件速查）

1. iOS 12+，支持 Face ID 或 Touch ID 的设备。
2. Android 6+（API 23+）且具备可用人脸/指纹等生物识别。
3. 鸿蒙设备支持用户认证能力且已完成上述权限配置。

重要注意事项

• 生物类型：getBiometryType() 在支持时多为 face 或 fingerprint（iOS 对应 Face ID / Touch ID；Android/鸿蒙为人脸/指纹等，由系统映射）。
• 隐私与数据：生物特征数据由系统保管，不离开本机。
• 多次失败：各端可能要求锁屏密码/图案作为回退。

快速开始

1. 导入插件

import * as authsdk from "@/uni_modules/tt-apple-bioauth";

export default {
    data() {
        return {
            // 推荐 API 名
            bioauth: null as authsdk.TTBiometricAuth | null,
        }
    },
    onLoad() {
        this.bioauth = authsdk.getTTBiometricAuth();
        // 兼容旧名：getTTAppleBioauth() 与上句等价
    },
    methods: {
        handleBioAuth() {
            // 见下文 authenticate
        }
    }
}

2. 条件编译

仅在 App 原生（iOS / Android / 鸿蒙）有实现，H5/小程序等请用 #ifndef 做降级。示例用 #ifdef APP 覆盖三端（与官方 demo 一致）；若只需某一端可改用 APP-IOS / APP-ANDROID / APP-HARMONY：

// #ifdef APP
import * as authsdk from "@/uni_modules/tt-apple-bioauth";
// #endif

export default {
    data() {
        return {
            // #ifdef APP
            bioauth: null as authsdk.TTBiometricAuth | null,
            // #endif
        }
    },
    onLoad() {
        // #ifdef APP
        this.bioauth = authsdk.getTTBiometricAuth();
        // #endif
    }
}

基础使用

平台检测

checkPlatformSupport() {
    // #ifndef APP
    uni.showModal({
        title: '平台不支持',
        content: '生物认证仅支持 iOS / Android / 鸿蒙 App',
        showCancel: false
    });
    return false;
    // #endif
    return true;
}

设备支持检测

checkDeviceSupport() {
    // #ifdef APP
    if (this.bioauth) {
        const isSupported = this.bioauth.isSupported();
        const biometryType = this.bioauth.getBiometryType();
        if (isSupported) {
            console.log('设备支持生物识别:', biometryType);
            return true;
        }
        uni.showModal({
            title: '设备不支持',
            content: '当前设备无可用生物识别',
            showCancel: false
        });
        return false;
    }
    // #endif
    return false;
}

API 说明

主要类型（推荐命名）

• TTBiometricAuth：实例接口。
• getTTBiometricAuth()：获取单例。
• TTBiometricAuthOptions / TTBiometricAuthSuccess / TTBiometricAuthFail：入参与回调类型。
• 旧名 TTAppleBioauth / getTTAppleBioauth / TTAppleBioauthOptions 等为兼容别名。

生物认证

参数说明

TTBiometricAuthOptions（同旧名 TTAppleBioauthOptions）

示例代码

// 基础生物认证（三端 App）
handleBioAuth() {
    // #ifdef APP
    if (!this.checkDeviceSupport()) {
        return;
    }
    this.bioauth?.authenticate({
        reason: '请验证您的身份',
        fallbackTitle: '使用密码',
        cancelTitle: '取消',
        success: (result) => {
            console.log('生物认证成功:', result);
            this.handleAuthSuccess(result);
        },
        fail: (error) => {
            console.error('生物认证失败:', error);
            this.handleAuthError(error);
        },
        complete: () => {
            console.log('生物认证结束');
        }
    } as authsdk.TTBiometricAuthOptions);
    // #endif

    // #ifndef APP
    uni.showModal({
        title: '平台不支持',
        content: '请在 iOS / Android / 鸿蒙 App 中使用',
        showCancel: false
    });
    // #endif
}

// 处理认证成功
handleAuthSuccess(result: authsdk.TTBiometricAuthSuccess) {
    console.log('biometryType:', result.biometryType); // 如 face、fingerprint
    console.log('verified:', result.verified);

    // 执行需要验证的操作
    this.performSecureAction();
}

// 处理认证失败
handleAuthError(error: any) {
    const errCode = error.errCode;
    const errMsg = error.errMsg;

    console.log('错误码:', errCode);
    console.log('错误信息:', errMsg);

    // 根据错误码处理
    switch(errCode) {
        case 101:
            uni.showModal({
                title: '设备不支持',
                content: '当前设备不支持生物识别功能',
                showCancel: false
            });
            break;

        case 102:
            uni.showToast({
                title: '用户取消验证',
                icon: 'none'
            });
            break;

        case 103:
            uni.showModal({
                title: '需要密码验证',
                content: '请使用设备密码进行验证',
                showCancel: false
            });
            break;

        default:
            uni.showToast({
                title: errMsg || '验证失败',
                icon: 'error'
            });
            break;
    }
}

设备检测

检查设备支持

// 检查设备是否支持生物识别
const isSupported = this.bioauth?.isSupported();
console.log('设备支持生物识别:', isSupported);

获取生物识别类型

// 获取生物识别类型
const biometryType = this.bioauth?.getBiometryType();
console.log('生物识别类型:', biometryType); // 如 face、fingerprint、unsupported

返回值说明

TTBiometricAuthSuccess（同 TTAppleBioauthSuccess）

错误处理

插件错误码

错误处理最佳实践

// 统一错误处理函数
handleBioAuthError(error: any) {
    console.error('❌ 生物认证失败:', error);

    const errCode = error.errCode;
    const errMsg = error.errMsg;
    const cause = error.cause; // 原始错误信息

    console.log('插件错误码:', errCode);
    console.log('错误信息:', errMsg);
    if (cause) {
        console.log('原始错误:', cause);
    }

    switch(errCode) {
        case 101:
            uni.showModal({
                title: '设备不支持',
                content: '当前设备不支持生物识别功能，请使用密码验证',
                showCancel: false
            });
            break;

        case 102:
            // 用户取消，不显示错误提示
            console.log('用户取消生物认证');
            break;

        case 103:
            uni.showModal({
                title: '需要密码验证',
                content: '生物识别不可用，请使用设备密码',
                showCancel: false
            });
            break;

        case 999:
            // 处理其他错误
            if (cause && cause.message) {
                uni.showToast({
                    title: cause.message,
                    icon: 'error'
                });
            } else {
                uni.showToast({
                    title: errMsg || '验证失败',
                    icon: 'error'
                });
            }
            break;

        default:
            uni.showToast({
                title: errMsg || '验证失败',
                icon: 'error'
            });
            break;
    }
}

// 使用示例
this.bioauth?.authenticate({
    reason: '请验证您的身份',
    success: (result) => {
        this.handleAuthSuccess(result);
    },
    fail: (error) => {
        this.handleBioAuthError(error);
    }
} as authsdk.TTBiometricAuthOptions);

常见问题

1. 标准基座无法调试？

解决方案: 使用包含本插件的自定义基座/正式包；标准基座可能缺少 UTS 原生模块。

2. 模拟器/模拟环境？

解决方案: iOS 模拟器对 Face ID / Touch ID 支持有限，优先真机；Android / 鸿蒙同样建议在真机验证。

3. 设备显示不支持或 unsupported？

解决方案:

• 本机未录入指纹/人脸时，各端表现可能为不可用或需先走系统设置。
• 确认系统设置中已启用生物识别。
• 可提示用户使用锁屏密码等备选。

4. 用户取消验证？

解决方案:

• 用户取消是正常行为，不需要显示错误提示
• 可以提供其他验证方式供用户选择
• 记录用户选择，优化用户体验

5. 生物识别被锁定？

解决方案:

• 连续失败多次后系统会锁定生物识别
• 引导用户使用设备密码验证
• 等待锁定时间结束后再尝试

6. 跨端（H5/小程序 与 App）如何区分？

最佳实践:

handleSecureAuth() {
    // #ifdef APP
    this.handleBioAuth();
    // #endif
    // #ifndef APP
    this.showPasswordAuth();
    // #endif
}

showPasswordAuth() {
    // 显示密码输入界面
    uni.showModal({
        title: '身份验证',
        content: '请输入您的密码',
        editable: true,
        success: (res) => {
            if (res.confirm) {
                // 验证密码
                this.verifyPassword(res.content);
            }
        }
    });
}

7. 各端权限与清单？

• iOS：NSFaceIDUsageDescription 等按模板配置。
• Android：USE_BIOMETRIC 等由工程与依赖合并。
• 鸿蒙：ohos.permission.ACCESS_BIOMETRIC + 理由字符串；自定义基座/正式包含插件。

完整示例

<template>
    <view class="container">
        <text class="title">生物认证示例</text>

        <view class="status-section">
            <view class="status-item">
                <text>设备支持：</text>
                <text>{{deviceSupport}}</text>
            </view>
            <view class="status-item">
                <text>认证类型：</text>
                <text>{{biometryType}}</text>
            </view>
        </view>

        <view class="action-section">
            <button @click="handleBioAuth" :disabled="loading">
                {{loading ? '验证中...' : '开始验证'}}
            </button>
            <button @click="checkDeviceSupport">
                检测设备支持
            </button>
        </view>
    </view>
</template>

<script>
// #ifdef APP
import * as authsdk from "@/uni_modules/tt-apple-bioauth";
// #endif

export default {
    data() {
        return {
            deviceSupport: '检测中...',
            biometryType: '未知',
            loading: false,
            // #ifdef APP
            bioauth: null as authsdk.TTBiometricAuth | null,
            // #endif
        }
    },
    onLoad() {
        // #ifdef APP
        this.bioauth = authsdk.getTTBiometricAuth();
        this.checkDeviceSupport();
        // #endif
        // #ifndef APP
        this.deviceSupport = '非 App';
        this.biometryType = '仅 iOS / Android / 鸿蒙 App 支持';
        // #endif
    },
    methods: {
        checkDeviceSupport() {
            // #ifdef APP
            if (this.bioauth) {
                const isSupported = this.bioauth.isSupported();
                this.deviceSupport = isSupported ? '支持' : '不支持';
                this.biometryType = this.bioauth.getBiometryType();
            }
            // #endif
        },
        handleBioAuth() {
            // #ifdef APP
            if (this.loading) {
                return;
            }
            this.loading = true;
            this.bioauth?.authenticate({
                reason: '请验证您的身份',
                fallbackTitle: '使用密码',
                cancelTitle: '取消',
                success: () => {
                    uni.showToast({ title: '验证成功', icon: 'success' });
                },
                fail: (error) => {
                    this.handleBioAuthError(error);
                },
                complete: () => {
                    this.loading = false;
                }
            } as authsdk.TTBiometricAuthOptions);
            // #endif
        },
        handleBioAuthError(error: any) {
            // 同上文「错误处理最佳实践」
        }
    }
}
</script>

技术支持

如遇到问题，可依次：

1. 查阅本页「常见问题」中「各端权限与清单」小节的说明。
2. 对照 Apple LocalAuthentication、Android 生物识别 与鸿蒙官方用户认证相关文档。
3. 在真机、带插件的基座/安装包下复现并核对日志。

祝您开发愉快！ 🎉