更新记录

1.0.0（2025-09-25）

支持苹果生物认证

平台兼容性

uni-app(4.36)

uni-app x(4.36)

tt-apple-bioauth

🔐 苹果生物认证SDK插件，为 uni-app x 提供完整的 Face ID / Touch ID 生物识别集成解决方案

📖 目录

• SDK版本信息
• 环境配置
• 快速开始
• 基础使用
• API文档
• 错误处理
• 常见问题

SDK版本信息

📚 推荐阅读: Apple官方文档 - LocalAuthentication

🚨 重要提示

⚠️ 必须使用自定义基座运行，标准基座无法调试生物识别功能

⚠️ 仅支持 iOS 平台，与其他平台同时运行需要加条件编译

⚠️ 需要真机测试，iOS 模拟器不支持 Face ID / Touch ID

环境配置

前置条件

1. iOS 系统版本 12.0 及以上
2. 设备支持 Face ID 或 Touch ID
3. 用户已在设备设置中启用生物识别功能

Info.plist 配置

在 uni_modules/tt-apple-bioauth/utssdk/app-ios/config.json 中已自动配置：

{
  "plists": {
    "NSFaceIDUsageDescription": "此应用需要使用 Face ID 来验证您的身份，确保账户安全"
  }
}

重要注意事项

💡 生物识别类型：插件会自动检测设备支持的生物识别类型（Face ID / Touch ID）

⚠️ 用户隐私：生物识别数据不会离开设备，仅用于本地验证

🔄 验证失败：连续失败多次后，系统会要求输入设备密码

快速开始

1. 导入插件

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

export default {
    data() {
        return {
            bioauth: null as bioauth.TTAppleBioauth | null,
        }
    },
    onLoad() {
        // 初始化生物认证实例
        this.bioauth = bioauth.getTTAppleBioauth();
    },
    methods: {
        // 生物认证方法
        handleBioAuth() {
            // 认证实现代码见下方
        }
    }
}

2. 条件编译

由于生物认证仅支持 iOS 平台，建议使用条件编译：

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

export default {
    data() {
        return {
            // #ifdef APP-IOS
            bioauth: null as bioauth.TTAppleBioauth | null,
            // #endif
        }
    },
    onLoad() {
        // #ifdef APP-IOS
        this.bioauth = bioauth.getTTAppleBioauth();
        // #endif
    }
}

基础使用

平台检测

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

    return true;
}

设备支持检测

checkDeviceSupport() {
    // #ifdef APP-IOS
    if (this.bioauth) {
        const isSupported = this.bioauth.isSupported();
        const biometryType = this.bioauth.getBiometryType();

        if (isSupported) {
            console.log(`设备支持 ${biometryType}`);
            return true;
        } else {
            uni.showModal({
                title: '设备不支持',
                content: '当前设备不支持生物识别功能',
                showCancel: false
            });
            return false;
        }
    }
    // #endif

    return false;
}

API文档

生物认证

参数说明

TTAppleBioauthOptions

示例代码

// 基础生物认证
handleBioAuth() {
    // #ifdef APP-IOS
    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: (result) => {
            console.log("🔚 生物认证完成");
        }
    } as bioauth.TTAppleBioauthOptions);
    // #endif

    // #ifndef APP-IOS
    uni.showModal({
        title: '平台不支持',
        content: '生物认证仅支持 iOS 平台',
        showCancel: false
    });
    // #endif
}

// 处理认证成功
handleAuthSuccess(result: bioauth.TTAppleBioauthSuccess) {
    console.log('认证类型:', result.biometryType);
    console.log('验证结果:', 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 ID" | "Touch ID" | "不支持"

返回值说明

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 bioauth.TTAppleBioauthOptions);

常见问题

1. 标准基座无法调试？

解决方案: 生物认证必须使用自定义基座，标准基座不包含生物识别功能。

2. 模拟器测试问题？

解决方案:

• iOS 模拟器不支持 Face ID / Touch ID
• 必须在真机上测试生物认证功能
• 可以使用模拟器的 Touch ID 模拟功能进行部分测试

3. 设备不支持生物识别？

解决方案:

• 确认设备型号支持 Face ID 或 Touch ID
• 检查用户是否在设置中启用了生物识别
• 提供密码验证作为备选方案

4. 用户取消验证？

解决方案:

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

5. 生物识别被锁定？

解决方案:

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

6. 跨平台兼容性处理？

最佳实践:

// 生物认证方法封装
handleSecureAuth() {
    // #ifdef APP-IOS
    this.handleBioAuth();
    // #endif

    // #ifndef APP-IOS
    // 其他平台使用密码验证
    this.showPasswordAuth();
    // #endif
}

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

7. 权限配置问题？

检查清单:

• ✅ Info.plist 中包含 NSFaceIDUsageDescription
• ✅ 用户已授权应用使用生物识别
• ✅ 设备已设置 Face ID 或 Touch ID
• ✅ 应用使用自定义基座运行

完整示例

<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-IOS
import * as bioauth from "@/uni_modules/tt-apple-bioauth";
// #endif

export default {
    data() {
        return {
            deviceSupport: '检测中...',
            biometryType: '未知',
            loading: false,
            // #ifdef APP-IOS
            bioauth: null as bioauth.TTAppleBioauth | null,
            // #endif
        }
    },
    onLoad() {
        // #ifdef APP-IOS
        this.bioauth = bioauth.getTTAppleBioauth();
        this.checkDeviceSupport();
        // #endif

        // #ifndef APP-IOS
        this.deviceSupport = '不支持';
        this.biometryType = '当前平台不支持';
        // #endif
    },
    methods: {
        checkDeviceSupport() {
            // #ifdef APP-IOS
            if (this.bioauth) {
                const isSupported = this.bioauth.isSupported();
                this.deviceSupport = isSupported ? '支持' : '不支持';
                this.biometryType = this.bioauth.getBiometryType();
            }
            // #endif
        },

        handleBioAuth() {
            // #ifdef APP-IOS
            if (this.loading) return;

            this.loading = true;
            this.bioauth?.authenticate({
                reason: '请验证您的身份',
                fallbackTitle: '使用密码',
                cancelTitle: '取消',
                success: (result) => {
                    this.loading = false;
                    uni.showToast({
                        title: '验证成功',
                        icon: 'success'
                    });
                },
                fail: (error) => {
                    this.loading = false;
                    this.handleBioAuthError(error);
                }
            } as bioauth.TTAppleBioauthOptions);
            // #endif
        },

        handleBioAuthError(error: any) {
            // 错误处理逻辑见上方
        }
    }
}
</script>

技术支持

如果在使用过程中遇到问题，请：

1. 查阅上方常见问题
2. 参考苹果官方开发文档
3. 确认设备支持生物识别功能
4. 检查应用权限配置

祝您开发愉快！ 🎉