📌 插件简介

FaceAISDK UTS 插件 是专为 uni-app / uni-app x 打造的离线人脸识别与活体检测解决方案。

• 完全离线：所有计算均在终端本地处理，无需依赖后台 API 服务，保护用户隐私并降低运营成本。
• 高性能无依赖：原生轻量封装，无需依赖任何第三方 SDK。
• 多平台兼容：完美支持 iOS、Android，兼容 Vue2、Vue3 以及全新的 uvue 渲染引擎。

🚀 快速上手

在引入和使用 UTS 插件前，请确保你已阅读并配置好基础环境：DCloud 官方 UTS 插件基础环境配置指南。

1️⃣ 运行示例项目

💡 建议：请先下载并运行最新示例项目，在熟悉功能和接口后再集成到你的主业务项目中。

2️⃣ 制作自定义调试基座

⚠️ 注意：制作基座期间请勿随意改动原生代码。

3️⃣ 使用自定义基座运行

注：人脸识别需要真机摄像头，不支持虚拟机模拟器

4️⃣ 集成到你的主项目

import { faceVerify / , ...其他方法 / } from "@/uni_modules/FaceAISDK-Core";

💡 核心提示：请务必遵循先打包自定义调试基座，再运行项目的流程。若偶遇云打包服务繁忙失败，请尝试重新提交打包。

❓ 常见问题与解决方案

1. UI 交互效果不符合业务需求？

目前 UTS 插件版本仅支持自定义字体与主题颜色。如果你需要深入修改页面 UI、布局或交互逻辑，建议拉取原生 SDK 自行二次开发并封装插件：

• iOS SDK: FaceAISDK_iOS
• Android SDK: FaceAISDK_Android

2. 炫彩活体提示光线太亮导致失败？

炫彩活体需要通过手机屏幕发射彩光投射到脸部进行感应。

• 应对方案：引导用户使用手掌遮挡强光或移至遮阳处；
• 场景建议：在室外强光或日光直射环境下，推荐改用 “动作活体 + 静默活体” 组合方案。

3. 改动原生代码后基座不能正常运行？

自定义基座生成后，原生的 Kotlin/Swift 编译产物已经固化。如修改了 native 目录下的原生代码，必须重新制作自定义调试基座 才能生效。

4. App 体积裁剪与优化

Android 动态库默认包含了针对 32 位老旧设备的兼容。若仅针对现代主流手机，可在 build.gradle 中过滤 SO 库，仅保留 arm64-v8a 架构，可大幅降低生成 APK 的体积。

🔢 状态码说明

SDK 在识别或活体检测过程中通过回调返回的状态码定义如下： Silent liveness threshold (iOS/Android): 0.85–0.95

| 状态码 (Code) | 常量名 (Constant) | 详细描述 | | --- | --- | --- | | 0 | DEFAULT | 初始化状态，流程尚未开始 | | 1 | VERIFY_SUCCESS | 1:1 人脸比对成功（相似度高于设置的阈值 threshold） | | 2 | VERIFY_FAILED | 1:1 人脸比对失败（相似度低于设置的阈值 threshold） | | 3 | MOTION_LIVENESS_SUCCESS | 动作活体检测成功（通常内部会自动过渡到后续流程） | | 4 | MOTION_LIVENESS_TIMEOUT | 动作活体检测超时 | | 5 | NO_FACE_MULTI | 连续多次未能成功检测到人脸 | | 6 | NO_FACE_FEATURE | 未检测到或无法提取有效的特征值 | | 7 | COLOR_LIVENESS_SUCCESS | 炫彩活体检测通过 | | 8 | COLOR_LIVENESS_FAILED | 炫彩活体检测失败 | | 9 | COLOR_LIVENESS_LIGHT_TOO_HIGH | 炫彩活体检测失败（环境光线亮度过高） | | 10 | ALL_LIVENESS_SUCCESS | 所有活体检测环节全部完成（包含动作与炫彩） | | 11 | SILENT_LIVENESS_FAILED | 静默活体检测失败 | | 12 | NO_BASE_FACE_FEATURE | 本地未注册/未录入基准人脸信息 | | 13 | NOT_ALLOW_MULTI_FACES | 摄像头画面中出现多张人脸 |

📱 Android 原生 SDK & 体验 Demo

如果你需要更高级的功能（如 UVC 协议外接摄像头支持、从相册批量导入 等），可下载原生体验包进行体验：

🤝 社区与支持

如果您在开发过程中遇到问题，欢迎随时联系我们！请提供尽可能详细的背景信息（包括但不限于 HBuilderX 版本、Vue 版本、测试机型平台 以及 报错日志/使用场景），这有助于我们更快为你解决问题。

• 🐛 提交 Issue: GitHub Issues
• 📧 EMAIL: [email protected]
• 💬 WeChat: FaceAISDK