uni.startSoterAuthentication(options)

开始 生物认证

startSoterAuthentication 兼容性

Web	微信小程序	Android	iOS	HarmonyOS	HarmonyOS(Vapor)
x	4.41	5.08	5.08	4.61	5.0

参数

名称	类型	必填	默认值	兼容性	描述
options	StartSoterAuthenticationOptions	是	-	Web 微信小程序 Android iOS HarmonyOS x - - - -	开始生物认证参数
名称 类型 必备 默认值 兼容性 描述 requestAuthModes Array<string> 是 - Web 微信小程序 Android iOS HarmonyOS x - - - - 请求使用的可接受的生物认证方式 合法值 兼容性 描述 fingerPrint Web 微信小程序 Android iOS HarmonyOS x - - - - 指纹识别 facial Web 微信小程序 Android iOS HarmonyOS x - - - - 人脸识别 speech Web 微信小程序 Android iOS HarmonyOS x - - - - 声纹识别（暂未支持） challenge string 否 - Web 微信小程序 Android iOS HarmonyOS x - - - - 挑战因子 authContent string 否 - Web 微信小程序 Android iOS HarmonyOS x - - - - 验证描述，即识别过程中显示在界面上的对话框提示内容 success (result: StartSoterAuthenticationSuccess) => void 否 - Web 微信小程序 Android iOS HarmonyOS x - - - - 接口调用成功的回调函数 fail (result: StartSoterAuthenticationFail) => void 否 - Web 微信小程序 Android iOS HarmonyOS x - - - - 接口调用失败的回调函数 complete (result: StartSoterAuthenticationSuccess | StartSoterAuthenticationFail) => void 否 - Web 微信小程序 Android iOS HarmonyOS x - - - - 接口调用结束的回调函数（调用成功、失败都会执行）

StartSoterAuthenticationSuccess 的属性值

名称	类型	必备	默认值	兼容性	描述
errCode	number	是	-	Web 微信小程序 Android iOS HarmonyOS x - - - -	错误码
authMode	string	是	-	Web 微信小程序 Android iOS HarmonyOS x - - - -	生物认证方式
合法值 兼容性 描述 fingerPrint Web 微信小程序 Android iOS HarmonyOS x - - - - 指纹识别 facial Web 微信小程序 Android iOS HarmonyOS x - - - - 人脸识别 speech Web 微信小程序 Android iOS HarmonyOS x - - - - 声纹识别（暂未支持）
resultJSON	string	否	-	Web 微信小程序 Android iOS HarmonyOS x - - - -	在设备安全区域（TEE）内获得的本机安全信息以及本次认证信息
resultJSONSignature	string	否	-	Web 微信小程序 Android iOS HarmonyOS x - - - -	用安全密钥对 resultJSON 的签名(SHA256 with RSA/PSS, saltlen=20)
errMsg	string	是	-	Web 微信小程序 Android iOS HarmonyOS x - - - -	接口调用结果

StartSoterAuthenticationFail 的属性值

名称	类型	必备	默认值	兼容性	描述
errCode	number	是	-	Web 微信小程序 Android iOS HarmonyOS x - - - -	统一错误码
errSubject	string	是	-	Web 微信小程序 Android iOS HarmonyOS x - - - -	统一错误主题（模块）名称
data	any	否	-	Web 微信小程序 Android iOS HarmonyOS x - - - -	错误信息中包含的数据
cause	Error	否	-	-	源错误信息，可以包含多个错误，详见SourceError
errMsg	string	是	-	Web 微信小程序 Android iOS HarmonyOS x - - - -

参见

• 相关 Bug
• 参见uni-app相关文档
• 微信小程序文档
• 支付宝小程序文档
• 百度小程序文档
• 抖音小程序文档
• 飞书小程序文档
• 钉钉小程序文档
• QQ小程序文档
• 快手小程序文档
• 京东小程序文档
• 华为快应用文档
• 360小程序文档

uni.checkIsSupportSoterAuthentication(options)

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

checkIsSupportSoterAuthentication 兼容性

Web	微信小程序	Android	iOS	HarmonyOS	HarmonyOS(Vapor)
x	4.41	5.08	5.08	4.61	5.0

参数

名称	类型	必填	默认值	兼容性	描述
options	CheckIsSupportSoterAuthenticationOptions	是	-	Web 微信小程序 Android iOS HarmonyOS x - - - -	开始生物认证的参数
名称 类型 必备 默认值 兼容性 描述 success (result: CheckIsSupportSoterAuthenticationSuccess) => void 否 - Web 微信小程序 Android iOS HarmonyOS x - - - - 接口调用成功的回调函数 fail (result: CheckIsSupportSoterAuthenticationFail) => void 否 - Web 微信小程序 Android iOS HarmonyOS x - - - - 接口调用失败的回调函数 complete (result: CheckIsSupportSoterAuthenticationSuccess | CheckIsSupportSoterAuthenticationFail) => void 否 - Web 微信小程序 Android iOS HarmonyOS x - - - - 接口调用结束的回调函数（调用成功、失败都会执行）

CheckIsSupportSoterAuthenticationSuccess 的属性值

名称	类型	必备	默认值	兼容性	描述
supportMode	Array<string>	是	-	Web 微信小程序 Android iOS HarmonyOS x - - - -	接口调用成功的回调函数
合法值 兼容性 描述 fingerPrint Web 微信小程序 Android iOS HarmonyOS x - - - - 指纹识别 facial Web 微信小程序 Android iOS HarmonyOS x - - - - 人脸识别 speech Web 微信小程序 Android iOS HarmonyOS x - - - - 声纹识别（暂未支持）
errMsg	string	是	-	Web 微信小程序 Android iOS HarmonyOS x - - - -	接口调用结果

CheckIsSupportSoterAuthenticationFail 的属性值

名称	类型	必备	默认值	兼容性	描述
errCode	number	是	-	Web 微信小程序 Android iOS HarmonyOS x - - - -	统一错误码
errSubject	string	是	-	Web 微信小程序 Android iOS HarmonyOS x - - - -	统一错误主题（模块）名称
data	any	否	-	Web 微信小程序 Android iOS HarmonyOS x - - - -	错误信息中包含的数据
cause	Error	否	-	-	源错误信息，可以包含多个错误，详见SourceError
errMsg	string	是	-	Web 微信小程序 Android iOS HarmonyOS x - - - -

参见

• 相关 Bug
• 参见uni-app相关文档
• 微信小程序文档
• 支付宝小程序文档
• 百度小程序文档
• 抖音小程序文档
• 飞书小程序文档
• 钉钉小程序文档
• QQ小程序文档
• 快手小程序文档
• 京东小程序文档
• 华为快应用文档
• 360小程序文档

uni.checkIsSoterEnrolledInDevice(options)

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

checkIsSoterEnrolledInDevice 兼容性

Web	微信小程序	Android	iOS	HarmonyOS	HarmonyOS(Vapor)
x	4.41	5.08	5.08	4.61	5.0

参数

名称	类型	必填	默认值	兼容性	描述
options	CheckIsSoterEnrolledInDeviceOptions	是	-	Web 微信小程序 Android iOS HarmonyOS x - - - -	获取本机支持的生物认证方式的参数
名称 类型 必备 默认值 兼容性 描述 checkAuthMode string 是 - Web 微信小程序 Android iOS HarmonyOS x - - - - 生物认证方式 合法值 兼容性 描述 fingerPrint Web 微信小程序 Android iOS HarmonyOS x - - - - 指纹识别 facial Web 微信小程序 Android iOS HarmonyOS x - - - - 人脸识别 speech Web 微信小程序 Android iOS HarmonyOS x - - - - 声纹识别（暂未支持） success (result: CheckIsSoterEnrolledInDeviceSuccess) => void 否 - Web 微信小程序 Android iOS HarmonyOS x - - - - 接口调用成功的回调函数 fail (result: CheckIsSoterEnrolledInDeviceFail) => void 否 - Web 微信小程序 Android iOS HarmonyOS x - - - - 接口调用失败的回调函数 complete (result: CheckIsSoterEnrolledInDeviceSuccess | CheckIsSoterEnrolledInDeviceFail) => void 否 - Web 微信小程序 Android iOS HarmonyOS x - - - - 接口调用结束的回调函数（调用成功、失败都会执行）

CheckIsSoterEnrolledInDeviceSuccess 的属性值

名称	类型	必备	默认值	兼容性	描述
isEnrolled	boolean	是	-	Web 微信小程序 Android iOS HarmonyOS x - - - -	是否已录入信息
errMsg	string	是	-	Web 微信小程序 Android iOS HarmonyOS x - - - -	错误信息

CheckIsSoterEnrolledInDeviceFail 的属性值

名称	类型	必备	默认值	兼容性	描述
errCode	number	是	-	Web 微信小程序 Android iOS HarmonyOS x - - - -	统一错误码
errSubject	string	是	-	Web 微信小程序 Android iOS HarmonyOS x - - - -	统一错误主题（模块）名称
data	any	否	-	Web 微信小程序 Android iOS HarmonyOS x - - - -	错误信息中包含的数据
cause	Error	否	-	-	源错误信息，可以包含多个错误，详见SourceError
errMsg	string	是	-	Web 微信小程序 Android iOS HarmonyOS x - - - -

参见

• 相关 Bug
• 参见uni-app相关文档
• 微信小程序文档
• 支付宝小程序文档
• 百度小程序文档
• 抖音小程序文档
• 飞书小程序文档
• 钉钉小程序文档
• QQ小程序文档
• 快手小程序文档
• 京东小程序文档
• 华为快应用文档
• 360小程序文档

示例

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

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

扫码体验（手机浏览器跳转到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>

通用类型

GeneralCallbackResult

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