uni-app x

展示全部

# uni.startSoterAuthentication(options)

开始生物认证

# startSoterAuthentication 兼容性

Web	微信小程序	Android	iOS	HarmonyOS
x	4.41	5.08	5.08	4.61

# 参数

名称

类型

必填

默认值

兼容性

描述

options

StartSoterAuthenticationOptions

是

开始生物认证参数

名称

类型

必备

默认值

兼容性

描述

requestAuthModes

Array<string>

是

请求使用的可接受的生物认证方式

合法值	兼容性	描述
fingerPrint		指纹识别
facial		人脸识别
speech		声纹识别（暂未支持）

challenge

string

否

挑战因子

authContent

string

否

验证描述，即识别过程中显示在界面上的对话框提示内容

success

(result: StartSoterAuthenticationSuccess) => void

否

接口调用成功的回调函数

fail

(result: StartSoterAuthenticationFail) => void

否

接口调用失败的回调函数

complete

(result: StartSoterAuthenticationSuccess | StartSoterAuthenticationFail) => void

否

接口调用结束的回调函数（调用成功、失败都会执行）

# StartSoterAuthenticationSuccess 的属性值

名称

类型

必备

默认值

兼容性

描述

errCode

number

是

错误码

authMode

string

是

生物认证方式

合法值	兼容性	描述
fingerPrint		指纹识别
facial		人脸识别
speech		声纹识别（暂未支持）

resultJSON

string

否

在设备安全区域（TEE）内获得的本机安全信息以及本次认证信息

resultJSONSignature

string

否

用安全密钥对 resultJSON 的签名(SHA256 with RSA/PSS, saltlen=20)

errMsg

string

是

接口调用结果

# StartSoterAuthenticationFail 的属性值

名称	类型	必备	描述
errCode	number	是	统一错误码
errSubject	string	是	统一错误主题（模块）名称
data	any	否	错误信息中包含的数据
cause	Error	否	源错误信息，可以包含多个错误，详见SourceError
errMsg	string	是

# 参见

# 注意

鸿蒙平台权限设置此接口需要权限 ohos.permission.ACCESS_BIOMETRIC。具体配置方法请参考鸿蒙权限配置指南

# uni.checkIsSupportSoterAuthentication(options)

获取本机支持的生物认证方式

# checkIsSupportSoterAuthentication 兼容性

Web	微信小程序	Android	iOS	HarmonyOS
x	4.41	5.08	5.08	4.61

# 参数

名称

类型

必填

默认值

兼容性

描述

options

CheckIsSupportSoterAuthenticationOptions

是

开始生物认证的参数

名称	类型	必备	描述
success	(result: CheckIsSupportSoterAuthenticationSuccess) => void	否	接口调用成功的回调函数
fail	(result: CheckIsSupportSoterAuthenticationFail) => void	否	接口调用失败的回调函数
complete	(result: CheckIsSupportSoterAuthenticationSuccess \| CheckIsSupportSoterAuthenticationFail) => void	否	接口调用结束的回调函数（调用成功、失败都会执行）

# CheckIsSupportSoterAuthenticationSuccess 的属性值

名称

类型

必备

默认值

兼容性

描述

supportMode

Array<string>

是

接口调用成功的回调函数

合法值	兼容性	描述
fingerPrint		指纹识别
facial		人脸识别
speech		声纹识别（暂未支持）

errMsg

string

是

接口调用结果

# CheckIsSupportSoterAuthenticationFail 的属性值

名称	类型	必备	描述
errCode	number	是	统一错误码
errSubject	string	是	统一错误主题（模块）名称
data	any	否	错误信息中包含的数据
cause	Error	否	源错误信息，可以包含多个错误，详见SourceError
errMsg	string	是

# 参见

# 注意

鸿蒙平台权限设置此接口需要权限 ohos.permission.ACCESS_BIOMETRIC。具体配置方法请参考鸿蒙权限配置指南

# uni.checkIsSoterEnrolledInDevice(options)

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

# checkIsSoterEnrolledInDevice 兼容性

Web	微信小程序	Android	iOS	HarmonyOS
x	4.41	5.08	5.08	4.61

# 参数

名称

类型

必填

默认值

兼容性

描述

options

CheckIsSoterEnrolledInDeviceOptions

是

获取本机支持的生物认证方式的参数

名称

类型

必备

默认值

兼容性

描述

checkAuthMode

string

是

生物认证方式

合法值	兼容性	描述
fingerPrint		指纹识别
facial		人脸识别
speech		声纹识别（暂未支持）

success

(result: CheckIsSoterEnrolledInDeviceSuccess) => void

否

接口调用成功的回调函数

fail

(result: CheckIsSoterEnrolledInDeviceFail) => void

否

接口调用失败的回调函数

complete

(result: CheckIsSoterEnrolledInDeviceSuccess | CheckIsSoterEnrolledInDeviceFail) => void

否

接口调用结束的回调函数（调用成功、失败都会执行）

# CheckIsSoterEnrolledInDeviceSuccess 的属性值

名称	类型	必备	默认值	兼容性	描述
isEnrolled	boolean	是			是否已录入信息
errMsg	string	是			错误信息

# CheckIsSoterEnrolledInDeviceFail 的属性值

名称	类型	必备	描述
errCode	number	是	统一错误码
errSubject	string	是	统一错误主题（模块）名称
data	any	否	错误信息中包含的数据
cause	Error	否	源错误信息，可以包含多个错误，详见SourceError
errMsg	string	是

# 参见

# 注意

鸿蒙平台权限设置此接口需要权限 ohos.permission.ACCESS_BIOMETRIC。具体配置方法请参考鸿蒙权限配置指南

# 示例

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

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

<template>
	<!-- #ifdef APP -->
	<scroll-view style="flex: 1;padding: 6px;">
	<!-- #endif -->
		<text class="uni-h2">生物认证</text>
		<text class="notice">低版本安卓仅支持指纹，高版本 Android 指纹和人脸会弹出统一认证框。</text>

		<text class="uni-h3">设备支持情况</text>
		<text class="log-text">{{ supportStatus }}</text>
		<button class="margin-v" @tap="checkSupport">检查支持的认证方式</button>

		<text class="uni-h3">录入状态检查</text>
		<button class="margin-v" @tap="checkAuth('fingerPrint')">检查指纹</button>
		<button class="margin-v" @tap="checkAuth('facial')">检查人脸识别</button>

		<text class="uni-h3">认证结果</text>
		<text class="log-text">{{ authResult }}</text>
		<button class="margin-v" @tap="startAuth('fingerPrint')" type="primary">指纹认证</button>
		<button class="margin-v" @tap="startAuth('facial')" type="primary">人脸认证</button>
	<!-- #ifdef APP -->
	</scroll-view>
	<!-- #endif -->
</template>

<script setup lang="uts">

type AuthMode = 'fingerPrint' | 'facial'

const supportStatus = ref('未检查')
const authResult = ref('等待认证')

const getModeLabel = (mode: AuthMode): string => {
  return mode == 'fingerPrint' ? '指纹' : '人脸'
}

const checkSupport = () => {
  uni.checkIsSupportSoterAuthentication({
    success: (res) => {
      supportStatus.value = res.supportMode.length > 0 ?
        `支持: ${res.supportMode.join(', ')}` :
        '不支持任何生物认证'
    },
    fail: (err) => {
			console.log('err: ', err);
      supportStatus.value = `检查失败：[${err.errCode}]${err.errMsg}`
    }
  })
}

const checkAuth = (mode: AuthMode) => {
  uni.checkIsSoterEnrolledInDevice({
    checkAuthMode: mode,
    success: (res) => {
      // console.log('res: ',res);
      authResult.value = `${getModeLabel(mode)}${res.isEnrolled ? '已录入' : '未录入'}`
    },
    fail: (err) => {
      console.log('err: ', err);
      authResult.value = `${getModeLabel(mode)}检查失败：[${err.errCode}]${err.errMsg}`
    }
  })
}

const startAuth = (mode: AuthMode) => {
  uni.startSoterAuthentication({
    requestAuthModes: [mode],
    challenge: '123456', // 正常逻辑应该由服务器生成挑战因子
    authContent: `请用${getModeLabel(mode)}解锁`,
    success: (res) => {
      // console.log('res: ',res);
      authResult.value = `${getModeLabel(res.authMode as AuthMode)}认证成功`
    },
    fail: (err) => {
      console.log('err: ',err);
      authResult.value = `${getModeLabel(mode)}认证失败，[${err.errCode}]${err.errMsg}`
    }
  })
}
</script>

<style>
  .margin-v {
    margin: 5px 0;
  }

	.log-text {
    padding: 10px;
		font-size: 14px;
    border: 1px solid #ccc;
  }

	.notice {
	  color: #550000;
		font-size: 14px;
		font-style: italic;
	}
</style>

示例源码如下，请查看 pre > code 标签中的内容

<template>
	<!-- #ifdef APP -->
	<scroll-view style="flex: 1;padding: 6px;">
	<!-- #endif -->
		<text class="uni-h2">生物认证</text>
		<text class="notice">低版本安卓仅支持指纹，高版本 Android 指纹和人脸会弹出统一认证框。</text>

		<text class="uni-h3">设备支持情况</text>
		<text class="log-text">{{ supportStatus }}</text>
		<button class="margin-v" @tap="checkSupport">检查支持的认证方式</button>

		<text class="uni-h3">录入状态检查</text>
		<button class="margin-v" @tap="checkAuth('fingerPrint')">检查指纹</button>
		<button class="margin-v" @tap="checkAuth('facial')">检查人脸识别</button>

		<text class="uni-h3">认证结果</text>
		<text class="log-text">{{ authResult }}</text>
		<button class="margin-v" @tap="startAuth('fingerPrint')" type="primary">指纹认证</button>
		<button class="margin-v" @tap="startAuth('facial')" type="primary">人脸认证</button>
	<!-- #ifdef APP -->
	</scroll-view>
	<!-- #endif -->
</template>

<script setup lang="uts">

type AuthMode = 'fingerPrint' | 'facial'

const supportStatus = ref('未检查')
const authResult = ref('等待认证')

const getModeLabel = (mode: AuthMode): string => {
  return mode == 'fingerPrint' ? '指纹' : '人脸'
}

const checkSupport = () => {
  uni.checkIsSupportSoterAuthentication({
    success: (res) => {
      supportStatus.value = res.supportMode.length > 0 ?
        `支持: ${res.supportMode.join(', ')}` :
        '不支持任何生物认证'
    },
    fail: (err) => {
			console.log('err: ', err);
      supportStatus.value = `检查失败：[${err.errCode}]${err.errMsg}`
    }
  })
}

const checkAuth = (mode: AuthMode) => {
  uni.checkIsSoterEnrolledInDevice({
    checkAuthMode: mode,
    success: (res) => {
      // console.log('res: ',res);
      authResult.value = `${getModeLabel(mode)}${res.isEnrolled ? '已录入' : '未录入'}`
    },
    fail: (err) => {
      console.log('err: ', err);
      authResult.value = `${getModeLabel(mode)}检查失败：[${err.errCode}]${err.errMsg}`
    }
  })
}

const startAuth = (mode: AuthMode) => {
  uni.startSoterAuthentication({
    requestAuthModes: [mode],
    challenge: '123456', // 正常逻辑应该由服务器生成挑战因子
    authContent: `请用${getModeLabel(mode)}解锁`,
    success: (res) => {
      // console.log('res: ',res);
      authResult.value = `${getModeLabel(res.authMode as AuthMode)}认证成功`
    },
    fail: (err) => {
      console.log('err: ',err);
      authResult.value = `${getModeLabel(mode)}认证失败，[${err.errCode}]${err.errMsg}`
    }
  })
}
</script>

<style>
  .margin-v {
    margin: 5px 0;
  }

	.log-text {
    padding: 10px;
		font-size: 14px;
    border: 1px solid #ccc;
  }

	.notice {
	  color: #550000;
		font-size: 14px;
		font-style: italic;
	}
</style>