docs/api/bio-auth.md
::: sourceCode
GitCode: https://gitcode.com/dcloud/uni-api/tree/alpha/uni_modules/uni-authentication
GitHub: https://github.com/dcloudio/uni-api/tree/alpha/uni_modules/uni-authentication
:::
开始 SOTER 生物认证
| Web | 微信小程序 | Android | iOS | HarmonyOS | HarmonyOS(Vapor) |
|---|---|---|---|---|---|
| <a style="color:unset;" href="https://vote.dcloud.net.cn/#/?name=uni-app%20x">x</a> | 4.41 | <a style="color:unset;" href="https://vote.dcloud.net.cn/#/?name=uni-app%20x">x</a> | <a style="color:unset;" href="https://vote.dcloud.net.cn/#/?name=uni-app%20x">x</a> | 4.61 | 5.0 |
| 名称 | 类型 | 必填 | 默认值 | 兼容性 | 描述 |
|---|---|---|---|---|---|
| options | StartSoterAuthenticationOptions | 是 | - | Web: x; 微信小程序: -; Android: x; iOS: x; HarmonyOS: - |
| 名称 | 类型 | 必备 | 默认值 | 兼容性 | 描述 |
|---|---|---|---|---|---|
| requestAuthModes | Array<string> | 是 | - | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: - | 请求使用的可接受的生物认证方式 |
| challenge | string | 否 | - | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: - | 挑战因子 |
| authContent | string | 否 | - | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: - | 验证描述,即识别过程中显示在界面上的对话框提示内容 |
| success | (result: StartSoterAuthenticationSuccess) => void | 否 | - | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: - | 接口调用成功的回调函数 |
| fail | (result: StartSoterAuthenticationFail) => void | 否 | - | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: - | 接口调用失败的回调函数 |
| complete | (result: any) => void | 否 | - | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: - | 接口调用结束的回调函数(调用成功、失败都会执行) |
| 合法值 | 兼容性 | 描述 |
|---|---|---|
| fingerPrint | Web: x; 微信小程序: -; Android: x; iOS: x; HarmonyOS: - | 指纹识别 |
| facial | Web: x; 微信小程序: -; Android: x; iOS: x; HarmonyOS: - | 人脸识别 |
| speech | Web: x; 微信小程序: -; Android: x; iOS: x; HarmonyOS: - | 声纹识别(暂未支持) |
| 名称 | 类型 | 必备 | 默认值 | 兼容性 | 描述 |
|---|---|---|---|---|---|
| errCode | number | 是 | - | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: - | 错误码 |
| authMode | string | 是 | - | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: - | 生物认证方式 |
| resultJSON | string | 否 | - | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: - | 在设备安全区域(TEE)内获得的本机安全信息以及本次认证信息 |
| resultJSONSignature | string | 否 | - | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: - | 用SOTER安全密钥对 resultJSON 的签名(SHA256 with RSA/PSS, saltlen=20) |
| errMsg | string | 是 | - | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: - | 接口调用结果 |
| 合法值 | 兼容性 | 描述 |
|---|---|---|
| fingerPrint | Web: x; 微信小程序: -; Android: x; iOS: x; HarmonyOS: - | 指纹识别 |
| facial | Web: x; 微信小程序: -; Android: x; iOS: x; HarmonyOS: - | 人脸识别 |
| speech | Web: x; 微信小程序: -; Android: x; iOS: x; HarmonyOS: - | 声纹识别(暂未支持) |
| 名称 | 类型 | 必备 | 默认值 | 兼容性 | 描述 |
|---|---|---|---|---|---|
| errSubject | string | 是 | - | Web: x; 微信小程序: -; Android: x; iOS: x; HarmonyOS: - | 统一错误主题(模块)名称 |
| errCode | number | 是 | - | Web: x; 微信小程序: -; Android: x; iOS: x; HarmonyOS: - | 统一错误码 |
| errMsg | string | 是 | - | Web: x; 微信小程序: -; Android: x; iOS: x; HarmonyOS: - | 统一错误描述信息 |
| data | any | 否 | - | Web: x; 微信小程序: -; Android: x; iOS: x; HarmonyOS: - | 错误信息中包含的数据 |
| cause | Error | 否 | - | Web: x; 微信小程序: -; Android: x; iOS: x; HarmonyOS: - | 源错误信息,可以包含多个错误,详见SourceError |
| name | string | 是 | - | Web: x; 微信小程序: -; Android: x; iOS: x; HarmonyOS: - | |
| message | string | 是 | - | Web: x; 微信小程序: -; Android: x; iOS: x; HarmonyOS: - |
::: sourceCode
GitCode: https://gitcode.com/dcloud/uni-api/tree/alpha/uni_modules/uni-authentication
GitHub: https://github.com/dcloudio/uni-api/tree/alpha/uni_modules/uni-authentication
:::
获取本机支持的 SOTER 生物认证方式
| Web | 微信小程序 | Android | iOS | HarmonyOS | HarmonyOS(Vapor) |
|---|---|---|---|---|---|
| <a style="color:unset;" href="https://vote.dcloud.net.cn/#/?name=uni-app%20x">x</a> | 4.41 | <a style="color:unset;" href="https://vote.dcloud.net.cn/#/?name=uni-app%20x">x</a> | <a style="color:unset;" href="https://vote.dcloud.net.cn/#/?name=uni-app%20x">x</a> | 4.61 | 5.0 |
| 名称 | 类型 | 必填 | 默认值 | 兼容性 | 描述 |
|---|---|---|---|---|---|
| options | CheckIsSupportSoterAuthenticationOptions | 是 | - | Web: x; 微信小程序: -; Android: x; iOS: x; HarmonyOS: - |
| 名称 | 类型 | 必备 | 默认值 | 兼容性 | 描述 |
|---|---|---|---|---|---|
| success | (result: CheckIsSupportSoterAuthenticationSuccess) => void | 否 | - | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: - | 接口调用成功的回调函数 |
| fail | (result: CheckIsSupportSoterAuthenticationFail) => void | 否 | - | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: - | 接口调用失败的回调函数 |
| complete | (result: any) => void | 否 | - | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: - | 接口调用结束的回调函数(调用成功、失败都会执行) |
| 名称 | 类型 | 必备 | 默认值 | 兼容性 | 描述 |
|---|---|---|---|---|---|
| supportMode | Array<string> | 是 | - | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: - | 接口调用成功的回调函数 |
| errMsg | string | 是 | - | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: - | 接口调用结果 |
| 合法值 | 兼容性 | 描述 |
|---|---|---|
| fingerPrint | Web: x; 微信小程序: -; Android: x; iOS: x; HarmonyOS: - | 指纹识别 |
| facial | Web: x; 微信小程序: -; Android: x; iOS: x; HarmonyOS: - | 人脸识别 |
| speech | Web: x; 微信小程序: -; Android: x; iOS: x; HarmonyOS: - | 声纹识别(暂未支持) |
| 名称 | 类型 | 必备 | 默认值 | 兼容性 | 描述 |
|---|---|---|---|---|---|
| errSubject | string | 是 | - | Web: x; 微信小程序: -; Android: x; iOS: x; HarmonyOS: - | 统一错误主题(模块)名称 |
| errCode | number | 是 | - | Web: x; 微信小程序: -; Android: x; iOS: x; HarmonyOS: - | 统一错误码 |
| errMsg | string | 是 | - | Web: x; 微信小程序: -; Android: x; iOS: x; HarmonyOS: - | 统一错误描述信息 |
| data | any | 否 | - | Web: x; 微信小程序: -; Android: x; iOS: x; HarmonyOS: - | 错误信息中包含的数据 |
| cause | Error | 否 | - | Web: x; 微信小程序: -; Android: x; iOS: x; HarmonyOS: - | 源错误信息,可以包含多个错误,详见SourceError |
| name | string | 是 | - | Web: x; 微信小程序: -; Android: x; iOS: x; HarmonyOS: - | |
| message | string | 是 | - | Web: x; 微信小程序: -; Android: x; iOS: x; HarmonyOS: - |
::: sourceCode
GitCode: https://gitcode.com/dcloud/uni-api/tree/alpha/uni_modules/uni-authentication
GitHub: https://github.com/dcloudio/uni-api/tree/alpha/uni_modules/uni-authentication
:::
获取设备内是否录入如指纹等生物信息
| Web | 微信小程序 | Android | iOS | HarmonyOS | HarmonyOS(Vapor) |
|---|---|---|---|---|---|
| <a style="color:unset;" href="https://vote.dcloud.net.cn/#/?name=uni-app%20x">x</a> | 4.41 | <a style="color:unset;" href="https://vote.dcloud.net.cn/#/?name=uni-app%20x">x</a> | <a style="color:unset;" href="https://vote.dcloud.net.cn/#/?name=uni-app%20x">x</a> | 4.61 | 5.0 |
| 名称 | 类型 | 必填 | 默认值 | 兼容性 | 描述 |
|---|---|---|---|---|---|
| options | CheckIsSoterEnrolledInDeviceOptions | 是 | - | Web: x; 微信小程序: -; Android: x; iOS: x; HarmonyOS: - |
| 名称 | 类型 | 必备 | 默认值 | 兼容性 | 描述 |
|---|---|---|---|---|---|
| checkAuthMode | string | 是 | - | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: - | 生物认证方式 |
| success | (result: CheckIsSoterEnrolledInDeviceSuccess) => void | 否 | - | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: - | 接口调用成功的回调函数 |
| fail | (result: CheckIsSoterEnrolledInDeviceFail) => void | 否 | - | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: - | 接口调用失败的回调函数 |
| complete | (result: any) => void | 否 | - | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: - | 接口调用结束的回调函数(调用成功、失败都会执行) |
| 合法值 | 兼容性 | 描述 |
|---|---|---|
| fingerPrint | Web: x; 微信小程序: -; Android: x; iOS: x; HarmonyOS: - | 指纹识别 |
| facial | Web: x; 微信小程序: -; Android: x; iOS: x; HarmonyOS: - | 人脸识别 |
| speech | Web: x; 微信小程序: -; Android: x; iOS: x; HarmonyOS: - | 声纹识别(暂未支持) |
| 名称 | 类型 | 必备 | 默认值 | 兼容性 | 描述 |
|---|---|---|---|---|---|
| isEnrolled | boolean | 是 | - | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: - | 是否已录入信息 |
| errMsg | string | 是 | - | Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: - | 错误信息 |
| 名称 | 类型 | 必备 | 默认值 | 兼容性 | 描述 |
|---|---|---|---|---|---|
| errSubject | string | 是 | - | Web: x; 微信小程序: -; Android: x; iOS: x; HarmonyOS: - | 统一错误主题(模块)名称 |
| errCode | number | 是 | - | Web: x; 微信小程序: -; Android: x; iOS: x; HarmonyOS: - | 统一错误码 |
| errMsg | string | 是 | - | Web: x; 微信小程序: -; Android: x; iOS: x; HarmonyOS: - | 统一错误描述信息 |
| data | any | 否 | - | Web: x; 微信小程序: -; Android: x; iOS: x; HarmonyOS: - | 错误信息中包含的数据 |
| cause | Error | 否 | - | Web: x; 微信小程序: -; Android: x; iOS: x; HarmonyOS: - | 源错误信息,可以包含多个错误,详见SourceError |
| name | string | 是 | - | Web: x; 微信小程序: -; Android: x; iOS: x; HarmonyOS: - | |
| message | string | 是 | - | Web: x; 微信小程序: -; Android: x; iOS: x; HarmonyOS: - |
示例为hello uni-app x alpha分支,与最新HBuilderX Alpha版同步。与最新正式版同步的master分支示例另见
该 API 不支持 Web,请运行 hello uni-app x 到 App 平台体验
<template>
<view class="uni-container">
<page-head :title="title"></page-head>
<view class="uni-common-mt">
<text class="uni-title-text">设备支持情况:</text>
<text class="uni-subtitle-text">{{ supportStatus }}</text>
</view>
<view class="uni-common-mt">
<text class="uni-title-text">认证结果:</text>
<text class="uni-subtitle-text">{{ authResult }}</text>
</view>
<button @click="checkSupport" class="uni-common-mt">检查支持的认证方式</button>
<button @click="checkAuth('fingerPrint')" class="uni-common-mt">检查指纹</button>
<button @click="checkAuth('facial')" class="uni-common-mt">检查FaceID</button>
<button @click="startAuth('fingerPrint')" type="primary" class="uni-common-mt">指纹认证</button>
<button @click="startAuth('facial')" type="primary" class="uni-common-mt">FaceID认证</button>
</view>
</template>
<script setup lang="uts">
const title = '生物认证'
const supportStatus = ref('未检查')
const authResult = ref('等待认证')
const checkSupport = () => {
uni.checkIsSupportSoterAuthentication({
success: (res) => {
supportStatus.value = res.supportMode.length > 0 ?
`支持: ${res.supportMode.join(', ')}` :
'不支持任何生物认证'
},
fail: () => {
supportStatus.value = '检查失败'
}
})
}
const checkAuth = (mode: string) => {
uni.checkIsSoterEnrolledInDevice({
checkAuthMode: mode,
success: (res) => {
console.log('res: ',res);
authResult.value = `${mode === 'fingerPrint' ? '指纹' : 'FaceID'}${res.isEnrolled ? '已录入' : '未录入'}`
},
fail: (err) => {
console.log('err: ',err);
authResult.value = `${mode === 'fingerPrint' ? '指纹' : 'FaceID'}检查失败,${err}`
}
})
}
const startAuth = (mode: string) => {
uni.startSoterAuthentication({
requestAuthModes: [mode],
challenge: '123456',
authContent: `请用${mode === 'fingerPrint' ? '指纹' : 'FaceID'}解锁`,
success: (res) => {
console.log('res: ',res);
authResult.value = `${res.authMode === 'fingerPrint' ? '指纹' : 'FaceID'}认证成功`
},
fail: (err) => {
console.log('err: ',err);
authResult.value = `${mode === 'fingerPrint' ? '指纹' : 'FaceID'}认证失败,${err}`
}
})
}
</script>
| 名称 | 类型 | 必备 | 默认值 | 兼容性 | 描述 |
|---|---|---|---|---|---|
| errMsg | string | 是 | - | Web: -; 微信小程序: 4.41; Android: -; iOS: -; HarmonyOS: - | 错误信息 |