Back to Uni App

Bio Auth

docs/api/bio-auth.md

2.3.320.0 KB
Original Source
<!-- ## uni.startSoterAuthentication(options) @startsoterauthentication -->

::: sourceCode

uni.startSoterAuthentication(options) @startsoterauthentication

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 生物认证

startSoterAuthentication 兼容性

Web微信小程序AndroidiOSHarmonyOSHarmonyOS(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.615.0

参数

名称类型必填默认值兼容性描述
optionsStartSoterAuthenticationOptions-Web: x; 微信小程序: -; Android: x; iOS: x; HarmonyOS: -

options 的属性描述

名称类型必备默认值兼容性描述
requestAuthModesArray<string>-Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: -请求使用的可接受的生物认证方式
challengestring-Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: -挑战因子
authContentstring-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: -接口调用结束的回调函数(调用成功、失败都会执行)
requestAuthModes 的属性描述
合法值兼容性描述
fingerPrintWeb: x; 微信小程序: -; Android: x; iOS: x; HarmonyOS: -指纹识别
facialWeb: x; 微信小程序: -; Android: x; iOS: x; HarmonyOS: -人脸识别
speechWeb: x; 微信小程序: -; Android: x; iOS: x; HarmonyOS: -声纹识别(暂未支持)

StartSoterAuthenticationSuccess 的属性值 @startsoterauthenticationsuccess-values

名称类型必备默认值兼容性描述
errCodenumber-Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: -错误码
authModestring-Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: -生物认证方式
resultJSONstring-Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: -在设备安全区域(TEE)内获得的本机安全信息以及本次认证信息
resultJSONSignaturestring-Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: -用SOTER安全密钥对 resultJSON 的签名(SHA256 with RSA/PSS, saltlen=20)
errMsgstring-Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: -接口调用结果

authMode 的属性描述

合法值兼容性描述
fingerPrintWeb: x; 微信小程序: -; Android: x; iOS: x; HarmonyOS: -指纹识别
facialWeb: x; 微信小程序: -; Android: x; iOS: x; HarmonyOS: -人脸识别
speechWeb: x; 微信小程序: -; Android: x; iOS: x; HarmonyOS: -声纹识别(暂未支持)

StartSoterAuthenticationFail 的属性值 @startsoterauthenticationfail-values

名称类型必备默认值兼容性描述
errSubjectstring-Web: x; 微信小程序: -; Android: x; iOS: x; HarmonyOS: -统一错误主题(模块)名称
errCodenumber-Web: x; 微信小程序: -; Android: x; iOS: x; HarmonyOS: -统一错误码
errMsgstring-Web: x; 微信小程序: -; Android: x; iOS: x; HarmonyOS: -统一错误描述信息
dataany-Web: x; 微信小程序: -; Android: x; iOS: x; HarmonyOS: -错误信息中包含的数据
causeError-Web: x; 微信小程序: -; Android: x; iOS: x; HarmonyOS: -源错误信息,可以包含多个错误,详见SourceError
namestring-Web: x; 微信小程序: -; Android: x; iOS: x; HarmonyOS: -
messagestring-Web: x; 微信小程序: -; Android: x; iOS: x; HarmonyOS: -
<!-- UTSAPIJSON.startSoterAuthentication.example -->

参见

<!-- ## uni.checkIsSupportSoterAuthentication(options) @checkissupportsoterauthentication -->

::: sourceCode

uni.checkIsSupportSoterAuthentication(options) @checkissupportsoterauthentication

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 生物认证方式

checkIsSupportSoterAuthentication 兼容性

Web微信小程序AndroidiOSHarmonyOSHarmonyOS(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.615.0

参数

名称类型必填默认值兼容性描述
optionsCheckIsSupportSoterAuthenticationOptions-Web: x; 微信小程序: -; Android: x; iOS: x; HarmonyOS: -

options 的属性描述

名称类型必备默认值兼容性描述
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: -接口调用结束的回调函数(调用成功、失败都会执行)

CheckIsSupportSoterAuthenticationSuccess 的属性值 @checkissupportsoterauthenticationsuccess-values

名称类型必备默认值兼容性描述
supportModeArray<string>-Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: -接口调用成功的回调函数
errMsgstring-Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: -接口调用结果

supportMode 的属性描述

合法值兼容性描述
fingerPrintWeb: x; 微信小程序: -; Android: x; iOS: x; HarmonyOS: -指纹识别
facialWeb: x; 微信小程序: -; Android: x; iOS: x; HarmonyOS: -人脸识别
speechWeb: x; 微信小程序: -; Android: x; iOS: x; HarmonyOS: -声纹识别(暂未支持)

CheckIsSupportSoterAuthenticationFail 的属性值 @checkissupportsoterauthenticationfail-values

名称类型必备默认值兼容性描述
errSubjectstring-Web: x; 微信小程序: -; Android: x; iOS: x; HarmonyOS: -统一错误主题(模块)名称
errCodenumber-Web: x; 微信小程序: -; Android: x; iOS: x; HarmonyOS: -统一错误码
errMsgstring-Web: x; 微信小程序: -; Android: x; iOS: x; HarmonyOS: -统一错误描述信息
dataany-Web: x; 微信小程序: -; Android: x; iOS: x; HarmonyOS: -错误信息中包含的数据
causeError-Web: x; 微信小程序: -; Android: x; iOS: x; HarmonyOS: -源错误信息,可以包含多个错误,详见SourceError
namestring-Web: x; 微信小程序: -; Android: x; iOS: x; HarmonyOS: -
messagestring-Web: x; 微信小程序: -; Android: x; iOS: x; HarmonyOS: -
<!-- UTSAPIJSON.checkIsSupportSoterAuthentication.example -->

参见

<!-- ## uni.checkIsSoterEnrolledInDevice(options) @checkissoterenrolledindevice -->

::: sourceCode

uni.checkIsSoterEnrolledInDevice(options) @checkissoterenrolledindevice

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

:::

获取设备内是否录入如指纹等生物信息

checkIsSoterEnrolledInDevice 兼容性

Web微信小程序AndroidiOSHarmonyOSHarmonyOS(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.615.0

参数

名称类型必填默认值兼容性描述
optionsCheckIsSoterEnrolledInDeviceOptions-Web: x; 微信小程序: -; Android: x; iOS: x; HarmonyOS: -

options 的属性描述

名称类型必备默认值兼容性描述
checkAuthModestring-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: -接口调用结束的回调函数(调用成功、失败都会执行)
checkAuthMode 的属性描述
合法值兼容性描述
fingerPrintWeb: x; 微信小程序: -; Android: x; iOS: x; HarmonyOS: -指纹识别
facialWeb: x; 微信小程序: -; Android: x; iOS: x; HarmonyOS: -人脸识别
speechWeb: x; 微信小程序: -; Android: x; iOS: x; HarmonyOS: -声纹识别(暂未支持)

CheckIsSoterEnrolledInDeviceSuccess 的属性值 @checkissoterenrolledindevicesuccess-values

名称类型必备默认值兼容性描述
isEnrolledboolean-Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: -是否已录入信息
errMsgstring-Web: x; 微信小程序: 4.41; Android: x; iOS: x; HarmonyOS: -错误信息

CheckIsSoterEnrolledInDeviceFail 的属性值 @checkissoterenrolledindevicefail-values

名称类型必备默认值兼容性描述
errSubjectstring-Web: x; 微信小程序: -; Android: x; iOS: x; HarmonyOS: -统一错误主题(模块)名称
errCodenumber-Web: x; 微信小程序: -; Android: x; iOS: x; HarmonyOS: -统一错误码
errMsgstring-Web: x; 微信小程序: -; Android: x; iOS: x; HarmonyOS: -统一错误描述信息
dataany-Web: x; 微信小程序: -; Android: x; iOS: x; HarmonyOS: -错误信息中包含的数据
causeError-Web: x; 微信小程序: -; Android: x; iOS: x; HarmonyOS: -源错误信息,可以包含多个错误,详见SourceError
namestring-Web: x; 微信小程序: -; Android: x; iOS: x; HarmonyOS: -
messagestring-Web: x; 微信小程序: -; Android: x; iOS: x; HarmonyOS: -
<!-- UTSAPIJSON.checkIsSoterEnrolledInDevice.example -->

参见

示例

示例为hello uni-app x alpha分支,与最新HBuilderX Alpha版同步。与最新正式版同步的master分支示例另见

该 API 不支持 Web,请运行 hello uni-app x 到 App 平台体验

uvue
<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>

通用类型

GeneralCallbackResult

名称类型必备默认值兼容性描述
errMsgstring-Web: -; 微信小程序: 4.41; Android: -; iOS: -; HarmonyOS: -错误信息