更新记录

1.0.1（2026-08-07）

1.0.1（2026-08-07）

• 首次发布 Android UTS 插件市场版本。
• 支持相机人脸注册、1:1验证和人脸特征管理。
• 支持静默、动作、炫彩以及动作+炫彩活体检测。

平台兼容性

uni-app(4.17)

OpenFaceUTS Android 人脸识别与活体检测

插件介绍

OpenFaceUTS 是面向 uni-app、uni-app x 的 Android 离线人脸识别 UTS 插件。插件在设备端完成人脸检测、特征提取、1:1验证以及活体检测，不主动上传人脸图片或人脸特征。

插件包含原生 AAR 和模型文件，首次运行前必须使用 HBuilderX 制作 Android 自定义调试基座；更新插件版本后也需要重新制作基座。

功能

• 相机采集并注册人脸，返回加密人脸特征和 JPEG Base64 图片
• 1:1 人脸验证并返回检测图片
• 静默活体、动作活体、炫彩活体及动作+炫彩活体
• 随机执行 1～4 个活体动作
• 查询、导入和删除指定人员的人脸特征
• SFace INT8 特征模型
• AES-256-GCM 可迁移加密人脸模板
• APP 包名与 APK 签名 SHA1 离线授权

平台兼容

当前插件只包含 arm64-v8a，请在项目 manifest.json 中保持一致的 ABI 配置。

安装与运行

1. 在插件市场购买并导入插件到目标项目。
2. 向插件作者提交订单号、Android 包名和正式签名证书 SHA1，获取 licenseKey。
3. 在 HBuilderX 中制作并选择 Android 自定义调试基座。
4. 在真机上运行项目。模拟器不建议用于摄像头和活体检测验收。

插件已声明相机权限：

<uses-permission android:name="android.permission.CAMERA" />

获取包名和签名 SHA1

从最终 APK 获取的信息最准确：

apksigner verify --print-certs app-release.apk

也可以从签名文件查询：

keytool -list -v -keystore release.keystore -alias your-alias

如果应用启用了 Google Play App Signing，请提交 Play Console 中的“应用签名证书 SHA1”，不要提交上传证书 SHA1。调试包、自定义基座和正式包使用不同签名时，需要分别申请授权。

申请授权只需提交包名和 SHA1，请勿发送 keystore、密码或私钥。

初始化

import { initialize } from '@/uni_modules/OpenFaceUTS'

const options = {
  // 插件作者根据购买订单、APP 包名和签名 SHA1 签发
  licenseKey: 'YOUR_LICENSE_KEY',
  similarityThreshold: 0.40,
  passiveLivenessThreshold: 0.80,
  activeLiveness: {
    actionCount: 2,
    candidates: ['blink', 'turnLeft', 'turnRight', 'turnLeftRight', 'nod', 'smile'],
    timeoutMillis: 20000
  },
  featureCrypto: {
    tenantId: 'YOUR_TENANT_ID',
    activeKeyId: 1,
    keys: [
      { keyId: 1, keyBase64: '32_BYTE_AES_KEY_BASE64URL' }
    ]
  }
}

initialize(options, (result) => {
  console.log('初始化结果', result.code, result.msg)
})

featureCrypto.keys 中的每个密钥必须是32字节 AES 密钥的无填充 Base64URL 字符串。生产密钥应由业务服务端或 KMS 在用户认证后安全下发，不要将生产密钥硬编码到前端代码。

生成 featureCrypto keyBase64

keyBase64 是32字节安全随机数经过无填充 Base64URL 编码后的 AES-256密钥，生成结果固定为43字符。它用于人脸特征加解密，与插件市场授权使用的 licenseKey、卖方 private-key.pem 没有关系。

使用 UTS 方法生成

import { generateFeatureKeyBase64 } from '@/uni_modules/OpenFaceUTS'

const keyBase64 = generateFeatureKeyBase64()
console.log(keyBase64, keyBase64.length) // 43

生成后配置到初始化参数：

const featureCrypto = {
  tenantId: 'your-tenant',
  activeKeyId: 1,
  keys: [
    { keyId: 1, keyBase64 }
  ]
}

使用 Windows BAT生成

双击运行插件目录中的：

uni_modules/OpenFaceUTS/tools/GenerateFeatureKey.bat

脚本会生成密钥、显示长度并自动复制到 Windows 剪贴板。

生产环境不要在每次启动时重新生成密钥。应只生成一次并存入服务端 KMS或其他安全密钥系统，在业务用户认证后安全下发。跨设备恢复人脸特征时，必须使用原来的 tenantId 和对应 keyBase64；密钥丢失后已有加密特征无法恢复。

轮换密钥时提高 activeKeyId 并保留仍需解密历史特征的旧密钥：

featureCrypto: {
  tenantId: 'your-tenant',
  activeKeyId: 2,
  keys: [
    { keyId: 1, keyBase64: 'OLD_43_CHARACTER_KEY' },
    { keyId: 2, keyBase64: 'NEW_43_CHARACTER_KEY' }
  ]
}

调用示例

import {
  addFaceByCamera,
  verifyFace,
  livenessDetect,
  getFaceFeature,
  registerFaceFeature,
  deleteFace
} from '@/uni_modules/OpenFaceUTS'

// 相机注册，不执行动作或炫彩活体
addFaceByCamera('person-001', (result) => {
  console.log(result.faceID, result.faceFeature, result.faceBase64)
})

// 1:1验证：动作+炫彩活体，随机两个动作
verifyFace('person-001', {
  actionCount: 2,
  livenessMethod: 'ACTION_COLOR'
}, (result) => {
  console.log(result.code, result.similarity, result.faceBase64, result.motionActions)
})

// 独立活体检测
livenessDetect({
  actionCount: 1,
  livenessMethod: 'ACTION'
}, (result) => {
  console.log(result.code, result.liveness, result.motionActions)
})

getFaceFeature('person-001', (result) => console.log(result.faceFeature))
registerFaceFeature('person-002', 'ENCRYPTED_FACE_FEATURE', console.log)
deleteFace('person-001', console.log)

活体配置

livenessMethod 支持：

动作候选值：blink、turnLeft、turnRight、turnLeftRight、nod、smile。actionCount 支持 1～4。

API

返回结果

type FaceResult = {
  code: number,
  msg: string,
  operation: string,
  faceID: string,
  similarity: number,
  liveness: number,
  faceFeature: string,
  faceBase64: string,
  motionActions: string[],
  elapsedMillis: number
}

• code = 1：操作成功或验证通过
• code = 0：未通过、未找到或用户取消
• code < 0：参数、授权或原生调用错误

授权说明

市场授权同时绑定 Android 包名和当前 APK 签名证书 SHA1，同一授权码不能用于其他包名或其他签名。更换包名、正式签名或应用签名证书后，需要重新申请授权。

授权校验完全离线，不绑定设备、不限制安装数量，也不会联网收集设备信息。若不同应用使用相同包名和相同签名，SDK 会将其视为同一个授权应用。

常见授权错误：

隐私与合规

插件会处理摄像头画面、人脸图片、人脸特征和活体检测结果。数据默认保存在应用私有目录，插件自身不主动上传数据。应用开发者仍需根据实际业务完成用户告知、授权同意、隐私政策、数据保留期限、删除机制和适用地区的人脸生物识别合规要求。

活体检测和人脸相似度阈值必须使用目标设备、目标人群和实际光照进行 FAR/FRR 与攻击样本测试，不能仅依赖默认阈值直接作为生产验收结论。

常见问题

更新插件后仍运行旧代码

删除旧自定义基座，重新制作并安装 Android 自定义调试基座。仅重新运行前端代码不会更新 AAR。

正式包授权正常，自定义基座授权失败

自定义基座通常使用不同签名，需要提交自定义基座 APK 的 SHA1 单独申请调试授权。

插件初始化成功但第一次识别较慢

第一次初始化需要加载人脸检测、活体和特征模型。建议应用启动后提前初始化，并在不再使用时调用 release()。

技术支持

申请授权或反馈问题时，请提供插件版本、HBuilderX 版本、Android 版本、设备型号、错误日志、APP 包名和签名 SHA1。请勿发送签名私钥或生产人脸数据。