更新记录

1.0.0（2026-04-09）

  1. 人脸识别能力

    • 新增原生实时人脸识别能力，支持打开相机后实时检测、识别、搜库并返回结果。
    • 支持两种识别模式：
    • 悬浮识别窗模式 startFaceDetect
    • 全屏原生识别页模式 openFaceDetect
    • 支持识别成功后自动关闭并回传匹配结果。
    • 支持连续识别失败达到指定次数后自动关闭。

  2. 实时检测状态回传

    • 支持实时状态回传，前端可根据事件类型做提示。
    • 当前支持的主要状态包括：
    • preview_ready
    • detecting
    • face_not_detected
    • face_detected
    • face_occluded
    • face_pose_invalid
    • face_too_dark
    • face_blurry
    • face_not_live
    • recognize_failed
    • recognize_success
    • recognize_max_failures
    • sdk_error

  3. 悬浮窗识别界面

    • 支持在前端页面中间以悬浮窗形式展示相机识别区域，不再只能全屏显示。
    • 支持自定义悬浮窗参数：
    • 是否启用悬浮窗 floatingWindowMode
    • 宽度比例 windowWidthRatio
    • 高度比例 windowHeightRatio
    • 横向偏移 windowOffsetXRatio
    • 纵向偏移 windowOffsetYRatio
    • 容器背景色 containerBackgroundColor

  4. 识别界面控制参数

    • 支持前端控制以下 UI 开关：
    • 关闭按钮 showCloseButton / showCancelButton
    • 开始检测按钮 showStartButton
    • 状态文字 showStatusText
    • 自动开始检测 autoStartAnalyze
    • 识别成功自动关闭 autoStopOnRecognize
    • 连续失败自动关闭 maxRecognizeFailures

  5. 人脸框与引导区域

    • 支持方形引导框显示控制：
    • showSquareGuide
    • 支持引导框大小和位置控制：
    • guideBoxWidthRatio
    • guideBoxHeightRatio
    • guideOffsetXRatio
    • guideOffsetYRatio
    • 支持原生遮罩显示开关：
    • showGuideMask

  6. 相机方向与图片方向控制

    • 支持统一的方向控制参数：
    • 相机朝向 cameraFacing
    • 预览方向 displayOrientationDeg
    • 抓拍图片旋转 captureImageRotationDeg
    • 抓拍镜像 captureMirrorX
    • 人脸框旋转 rectRotation
    • 人脸框镜像 rectMirrorX

  7. 人脸识别参数控制

    • 支持前端传入识别参数：
    • 识别模式 predictMode
    • 活体模式 livenessMode
    • 质量模式 qualityMode
    • 最大人脸数 maxFaceCount
    • 最小人脸尺寸 minFaceSize
    • 距离阈值 distanceThreshold
    • 人脸置信度阈值 faceScoreThreshold
    • 线程数 threadNum
    • 识别间隔 analyzeIntervalMs
    • 预览解码尺寸 previewDecodeMaxSize

  8. 授权与配置

    • 支持两种授权方式：
    • 通过 licensePath 激活
    • 通过 appId 激活
    • 支持实时识别链自动校验授权。
    • 支持数据库路径配置：
    • dbPath

  9. 图片识别与人脸库能力

    • 支持图片特征提取 getImageFeatures
    • 支持释放图片特征 releaseImageFeatures
    • 支持人脸入库 addDBRecord
    • 支持人脸搜库 searchDB
    • 支持 1:1 比对 compare1v1
    • 支持获取全部人脸库记录 getAllDBRecords
    • 支持删除库记录 deleteDBRecord
    • 支持清空人脸库 clearFaceDatabase

  10. 稳定性优化

    • 优化了实时识别反复打开关闭时的 SDK 生命周期管理。
    • 优化了成功识别后的资源释放链，降低商米授权设备上识别成功后闪退的概率。
    • 优化了悬浮层关闭与重复打开时的处理逻辑。

  11. 调试与测试

    • 提供测试页支持直接配置识别参数、窗口参数和界面参数。
    • 支持支付模式预设与调试模式预设，方便快速切换测试场景。

平台兼容性

uni-app(3.7.3)

Vue2 Vue3 Chrome Safari app-vue app-nvue Android iOS 鸿蒙
√ √ - - √ - - - -
微信小程序 支付宝小程序 抖音小程序 百度小程序 快手小程序 京东小程序 鸿蒙元服务 QQ小程序 飞书小程序 小红书小程序 快应用-华为 快应用-联盟
- - - - - - - - - - - -

其他

多语言 暗黑模式 宽屏模式
× × √

phiron-sunmiFace UTS 插件使用说明

1. 插件说明

phiron-sunmiFace 是基于商米人脸识别 SDK 封装的 uni-app UTS 插件，当前主要提供：

  1. 设备信息与 SDK 信息获取
  2. 商米人脸 SDK 初始化
  3. licensePath 激活授权
  4. 图片人脸特征提取
  5. 人脸库入库、搜库、删除、清空
  6. 实时相机识别
  7. 悬浮识别窗和全屏识别页

当前插件目录：

2. 前端引用方式

import * as SunmiFaceUTS from '@/uni_modules/phiron-sunmiFace'

不要再使用旧版原生插件的：

const sunmiFace = uni.requireNativePlugin('sunmiFace')

3. 推荐调用顺序

推荐按下面顺序接入：

  1. getDeviceInfo()
  2. checkPermissions()
  3. createHandle()
  4. init()
  5. activateByLicensePath()
  6. initDB()
  7. 再调用图片识别、实时识别、人脸库相关接口

推荐示例：

import * as SunmiFaceUTS from '@/uni_modules/phiron-sunmiFace'

async function setupSunmiFace() {
  console.log('deviceInfo', SunmiFaceUTS.getDeviceInfo())
  console.log('permissions', SunmiFaceUTS.checkPermissions())
  console.log('createHandle', SunmiFaceUTS.createHandle())
  console.log('init', SunmiFaceUTS.init({ useAssetConfig: true }))
  console.log('activate', SunmiFaceUTS.activateByLicensePath({
    licensePath: '/storage/emulated/0/SunmiRemoteFiles/license_face.txt'
  }))
  console.log('initDB', SunmiFaceUTS.initDB())
}

4. 权限申请

当前 checkPermissions() 已实现真实权限弹窗，不再只是提示文案。

会按系统版本申请这些权限：

  1. CAMERA
  2. READ_PHONE_STATE
  3. Android 13+：READ_MEDIA_IMAGES
  4. Android 12 及以下：READ_EXTERNAL_STORAGE
  5. Android 9 及以下：WRITE_EXTERNAL_STORAGE

调用示例：

const res = SunmiFaceUTS.checkPermissions()
console.log(res)

返回示例：

{
  "code": 0,
  "success": true,
  "message": "已拉起系统权限授权弹窗",
  "data": {
    "requiredPermissions": ["android.permission.CAMERA"],
    "missingPermissions": ["android.permission.CAMERA"],
    "allGranted": false,
    "requested": true
  }
}

5. 初始化与授权

5.1 创建句柄

SunmiFaceUTS.createHandle()

5.2 初始化 SDK

SunmiFaceUTS.init({
  useAssetConfig: true
})

可选参数：

  1. useAssetConfig
  2. configPath
  3. dbPath

5.3 通过文件激活，推荐

SunmiFaceUTS.activateByLicensePath({
  licensePath: '/storage/emulated/0/SunmiRemoteFiles/license_face.txt'
})

5.4 通过 AppId 激活

SunmiFaceUTS.activateByAppId({
  appId: '你的商米 AppId',
  forceRefresh: false
})

注意：

  1. 当前仓库里 licensePath 激活可用(离线激活不可用 官方更新到2.0.1后 不支持离线激活，只能远程激活拿到授权license.txt)
  2. initAuthorizeSDK / syncGetAuthorizeCode / activateByAppId 依赖商米授权 SDK 的额外运行时库
  3. 如果你只拿到了 SunmiAuthorize-SDK-1.0.1.aar，但没有商米配套的 com.sunmilib.* 依赖库，这几条接口会失败
  4. 这种情况下，建议优先走 activateByLicensePath

6. 基础接口

6.1 获取 SDK 版本

SunmiFaceUTS.getVersion()

6.2 获取设备信息

SunmiFaceUTS.getDeviceInfo()

6.3 释放句柄

SunmiFaceUTS.releaseHandle()

7. 人脸 SDK 配置

7.1 设置配置

SunmiFaceUTS.setConfig({
  threadNum: 2,
  distanceThreshold: 0.9,
  faceScoreThreshold: 0.7,
  minFaceSize: 60
})

7.2 获取当前配置

SunmiFaceUTS.getConfig()

8. 人脸库初始化

SunmiFaceUTS.initDB({
  dbPath: ''
})

如果不传 dbPath，插件会使用默认数据库路径。

9. 图片特征提取

9.1 从图片路径提取

const res = SunmiFaceUTS.getImageFeatures({
  imagePath: '/storage/emulated/0/Download/face_a.jpg',
  keepAlive: true,
  maxFaceCount: 1,
  predictMode: 3,
  livenessMode: 0,
  qualityMode: 0
})

9.2 从 base64 提取

SunmiFaceUTS.getImageFeatures({
  base64: 'data:image/jpeg;base64,...',
  keepAlive: true
})

常用参数：

  1. imagePath
  2. base64
  3. token
  4. feature
  5. keepAlive
  6. retainToken
  7. maxFaceCount
  8. predictMode
  9. livenessMode
  10. qualityMode
  11. decodeMaxSize
  12. distanceThreshold
  13. minFaceSize

9.3 释放特征对象

如果前面拿到了 token，建议用完释放：

SunmiFaceUTS.releaseImageFeatures({
  token: 'xxx'
})

10. 人脸库操作

10.1 入库

SunmiFaceUTS.addDBRecord({
  imagePath: '/storage/emulated/0/Download/face_a.jpg',
  id: 'user-001',
  name: '张三',
  phone: '***',
  dbPath: ''
})

也可以基于 token 或 feature 入库。

10.2 搜库

SunmiFaceUTS.searchDB({
  token: 'xxx'
})

10.3 获取全部记录

SunmiFaceUTS.getAllDBRecords()

10.4 删除记录

SunmiFaceUTS.deleteDBRecord({
  id: 'user-001',
  imgId: ''
})

10.5 清空人脸库

SunmiFaceUTS.clearFaceDatabase()

11. 1:1 比对

SunmiFaceUTS.compare1v1({
  first: {
    imagePath: '/storage/emulated/0/Download/face_a.jpg'
  },
  second: {
    imagePath: '/storage/emulated/0/Download/face_b.jpg'
  }
})

12. 实时识别接口

12.1 页面内悬浮识别窗

SunmiFaceUTS.startFaceDetect({
  floatingWindowMode: true,
  cameraFacing: 'front',
  autoStartAnalyze: true,
  autoStopOnRecognize: true,
  showCloseButton: false,
  showStartButton: false,
  showStatusText: false,
  showSquareGuide: true,
  showGuideMask: false,
  windowWidthRatio: 0.58,
  windowHeightRatio: 0.42,
  windowOffsetXRatio: 0,
  windowOffsetYRatio: -0.06,
  licensePath: '/storage/emulated/0/SunmiRemoteFiles/license_face.txt'
}, (event) => {
  console.log('face event', event)
})

12.2 停止悬浮识别

SunmiFaceUTS.stopFaceDetect()

12.3 打开全屏识别页

SunmiFaceUTS.openFaceDetect({
  cameraFacing: 'front',
  autoStartAnalyze: true,
  autoStopOnRecognize: true,
  showCloseButton: false,
  showStartButton: false,
  showStatusText: false,
  showSquareGuide: true,
  showGuideMask: false,
  licensePath: '/storage/emulated/0/SunmiRemoteFiles/license_face.txt'
}, (event) => {
  console.log('face event', event)
})

12.4 兼容入口

SunmiFaceUTS.startFaceRecognize(options, callback)

当前它等价于实时识别兼容入口，主要用于兼容旧调用方式。

13. 实时事件说明

实时识别过程中，回调里可能会收到这些 eventType：

  1. preview_ready
  2. detecting
  3. face_not_detected
  4. face_detected
  5. face_occluded
  6. face_pose_invalid
  7. face_too_dark
  8. face_blurry
  9. face_not_live
  10. recognize_failed
  11. recognize_success
  12. recognize_max_failures
  13. sdk_error
  14. closed
  15. stopped

前端可以根据 eventType 自己显示提示文案。

14. 常用参数说明

14.1 识别参数

  1. predictMode
  2. livenessMode
  3. qualityMode
  4. maxFaceCount
  5. minFaceSize
  6. distanceThreshold
  7. faceScoreThreshold
  8. threadNum
  9. analyzeIntervalMs
  10. previewDecodeMaxSize

14.2 UI 控制参数

  1. showCloseButton
  2. showStartButton
  3. showStatusText
  4. autoStartAnalyze
  5. autoStopOnRecognize
  6. maxRecognizeFailures

14.3 悬浮窗参数

  1. floatingWindowMode
  2. containerBackgroundColor
  3. windowWidthRatio
  4. windowHeightRatio
  5. windowOffsetXRatio
  6. windowOffsetYRatio

14.4 引导框参数

  1. showSquareGuide
  2. showGuideMask
  3. guideBoxWidthRatio
  4. guideBoxHeightRatio
  5. guideOffsetXRatio
  6. guideOffsetYRatio

14.5 方向参数

  1. cameraFacing
  2. displayOrientationDeg
  3. captureImageRotationDeg
  4. captureMirrorX
  5. rectRotation
  6. rectMirrorX

15. 当前已知限制

  1. 推荐优先使用 licensePath 激活
  2. appId 授权链当前依赖商米未提供完整的授权运行时库
  3. 如果缺少 com.sunmilib.* 和相关 RxJava 依赖，以下接口会失败：
    • initAuthorizeSDK
    • syncGetAuthorizeCode
    • asyncGetAuthorizeToken
    • activateByAppId
  4. 实时识别在反复开关场景下已经做了多轮释放优化，但仍建议以真机长时间测试为准

16. 问题排查建议

16.1 权限不弹窗

先调用：

SunmiFaceUTS.checkPermissions()

确认返回里：

  1. allGranted
  2. requested
  3. missingPermissions

16.2 appId 激活报缺类错误

如果报：

  1. HttpConfig$Builder
  2. com.sunmilib.*
  3. io.reactivex.*

说明不是业务代码问题，而是商米授权 SDK 配套依赖不完整。

16.3 实时识别多次开关后闪退

优先检查：

  1. 是否使用最新插件版本
  2. 是否反复创建多个识别窗但没有正确关闭
  3. 是否前端在识别成功后又立刻重复打开

17. 简单接入示例

import * as SunmiFaceUTS from '@/uni_modules/phiron-sunmiFace'

export async function initFaceSdk() {
  SunmiFaceUTS.checkPermissions()
  SunmiFaceUTS.createHandle()
  SunmiFaceUTS.init({ useAssetConfig: true })
  SunmiFaceUTS.activateByLicensePath({
    licensePath: '/storage/emulated/0/SunmiRemoteFiles/license_face.txt'
  })
  SunmiFaceUTS.initDB()
}

export function openCashierFacePay() {
  return SunmiFaceUTS.startFaceDetect({
    floatingWindowMode: true,
    autoStartAnalyze: true,
    autoStopOnRecognize: true,
    showCloseButton: false,
    showStartButton: false,
    showStatusText: false,
    showSquareGuide: true,
    showGuideMask: false,
    cameraFacing: 'front',
    licensePath: '/storage/emulated/0/SunmiRemoteFiles/license_face.txt'
  }, (event) => {
    console.log('face pay event =>', event)
  })
}

隐私、权限声明

1. 本插件需要申请的系统权限列表：

<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" /> <uses-permission android:name="android.permission.READ_PHONE_STATE" /> <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" /> <uses-permission android:name="android.permission.CAMERA" /> <uses-permission android:name="android.permission.FOREGROUND_SERVICE" /> <uses-permission android:name="android.permission.FOREGROUND_SERVICE_CAMERA" /> <!-- 授权码/令牌拉取通常需要联网 --> <uses-permission android:name="android.permission.INTERNET" /> <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" /> <uses-feature android:name="android.hardware.camera" />

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明：

无

3. 本插件是否包含广告，如包含需详细说明广告表达方式、展示频率：

无

评论列表 撰写评论 向官方投诉

暂无用户评论。