diff --git a/zh-cn/application-dev/reference/apis/js-apis-useriam-userauth.md b/zh-cn/application-dev/reference/apis/js-apis-useriam-userauth.md index c7ca4781f1471cb644fe477972ac8bc0604fe88d..f4f17343d06ccd433449871dccce15fe8b4365cb 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-useriam-userauth.md +++ b/zh-cn/application-dev/reference/apis/js-apis-useriam-userauth.md @@ -12,11 +12,676 @@ import userIAM_userAuth from '@ohos.userIAM.userAuth'; ``` +## WindowModeType10+ + +表示用户身份认证组件的窗口类型。 + +**系统能力**：SystemCapability.UserIAM.UserAuth.Core + +| 名称 | 值 | 说明 | +| ---------- | ---- | ---------- | +| DIALOG_BOX | 1 | 弹框类型。 | +| FULLSCREEN | 2 | 全屏类型。 | + +## AuthParam10+ + +用户认证相关参数。 + +**系统能力**：SystemCapability.UserIAM.UserAuth.Core + +| 名称 | 类型 | 必填 | 说明 | +| -------------- | ---------------------------------- | ---- | -------------------------------------- | +| challenge | Uint8Array | 是 | 挑战值，最大长度为32字节，可以填null。 | +| authType | [UserAuthType](#userauthtype8)[] | 是 | 认证类型。 | +| authTrustLevel | [AuthTrustLevel](#authtrustlevel8) | 是 | 认证信任等级。 | + +## WidgetParam10+ + +统一认证组件相关参数。 + +**系统能力**：SystemCapability.UserIAM.UserAuth.Core + +| 名称 | 类型 | 必填 | 说明 | +| -------------------- | ----------------------------------- | ---- | -------------------- | +| title | string | 是 | 认证组件标题。 | +| navigationButtonText | string | 否 | 导航按键的说明文本。 | +| windowModeType | [WindowModeType](#windowmodetype10) | 否 | 组件是否全屏显示。 | + +## UserAuthResult10+ + +用户认证结果。 + +**系统能力**：SystemCapability.UserIAM.UserAuth.Core + +| 名称 | 类型 | 必填 | 说明 | +| -------- | ------------------------------ | ---- | ------------------------------------------------------------ | +| result | number | 是 | 用户认证结果，详细介绍请参见[用户认证错误码](../errorcodes/errorcode-useriam.md)。 | +| token | Uint8Array | 否 | 认证通过的令牌信息。 | +| authType | [UserAuthType](#userauthtype8) | 否 | 认证类型。 | + + +## IAuthCallback10+ + +返回认证结果的回调对象。 + +### onResult10+ + +onResult(result: UserAuthResult): void + +回调函数，返回认证结果。 + +**系统能力**：SystemCapability.UserIAM.UserAuth.Core + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------ | ---------------------------------- | ---- | ---------- | +| result | [UserAuthResult](userauthresult10) | 是 | 认证结果。 | + +**示例：** + +```js +import userIAM_userAuth from '@ohos.userIAM.userAuth'; + +AuthParam authParam = { + challenge: new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]); + authType: userIAM_userAuth.UserAuthType.PIN; + authTrustLevel: userIAM_userAuth.AuthTrustLevel.ATL1; +} +WidgetParam widgetParam = { + title: "输入口令密码"; + windowMode: userIAM_userAuth.WindowModeType.DIALOG_BOX; +} +let userAuthInstance; +try { + userAuthInstance = userIAM_userAuth.getUserAuthInstance(authParam, widgetParam); + console.info("get userAuth instance success"); +} catch (error) { + console.info("get userAuth instance failed, error = " + error); +} + +try { + userAuthInstance.on('result', { + callback: onResult(result) { + console.log("authV10 result " + result.result); + console.log("authV10 token " + result.token); + console.log("authV10 authType " + result.authType); + } + }); + console.info("subscribe authentication event success"); +} catch (error) { + console.info("subscribe authentication event failed" + error); + //do error +} +``` + +## UserAuthInstance10+ + +用于执行用户身份认证，并支持使用统一用户身份认证组件。 +使用以下接口前，都需要先通过[getUserAuthInstance](#useriam_userauthgetuserauthinstance10)方法获取UserAuthInstance对象。 + +### on10+ + +on(type: 'result', callback: IAuthCallback): void + +订阅用户身份认证结果。 + +**系统能力**：SystemCapability.UserIAM.UserAuth.Core + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------------------------------- | ---- | ------------------------------------------ | +| type | 'result' | 是 | 订阅事件类型，表明该事件用来返回认证结果。 | +| callback | [IAuthCallback](iauthcallback10) | 是 | 认证接口的回调函数，用于返回认证结果。 | + +**错误码：** + +以下错误码的详细介绍请参见[用户认证错误码](../errorcodes/errorcode-useriam.md)。 + +| 错误码ID | 错误信息 | +| -------- | ------------------------ | +| 401 | Incorrect parameters. | +| 12500002 | General operation error. | + +**示例：** + +```js +import userIAM_userAuth from '@ohos.userIAM.userAuth'; + +AuthParam authParam = { + challenge: new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]); + authType: userIAM_userAuth.UserAuthType.PIN; + authTrustLevel: userIAM_userAuth.AuthTrustLevel.ATL1; +} +WidgetParam widgetParam = { + title: "输入口令密码"; + windowMode: userIAM_userAuth.WindowModeType.DIALOG_BOX; +} +let userAuthInstance; +try { + userAuthInstance = userIAM_userAuth.getUserAuthInstance(authParam, widgetParam); + console.info("get userAuth instance success"); +} catch (error) { + console.info("get userAuth instance failed, error = " + error); +} + +try { + userAuthInstance.on('result', { + callback: onResult(result) { + console.log("authV10 result " + result.result); + console.log("authV10 token " + result.token); + console.log("authV10 authType " + result.authType); + } + }); + console.info("subscribe authentication event success"); +} catch (error) { + console.info("subscribe authentication event failed" + error); + //do error +} +``` + +### off10+ + +off(type: 'result', callback?: IAuthCallback): void + +取消订阅用户身份认证结果。 + +> **说明：**需要使用已经成功订阅事件的[UserAuthInstance](#userauthinstance10)对象调用该接口进行取消订阅。 + +**系统能力**：SystemCapability.UserIAM.UserAuth.Core + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------------------------------- | ---- | ------------------------------------------ | +| type | 'result' | 是 | 订阅事件类型，表明该事件用来返回认证结果。 | +| callback | [IAuthCallback](iauthcallback10) | 否 | 认证接口的回调函数，用于返回认证结果。 | + +**错误码：** + +以下错误码的详细介绍请参见[用户认证错误码](../errorcodes/errorcode-useriam.md)。 + +| 错误码ID | 错误信息 | +| -------- | ------------------------ | +| 401 | Incorrect parameters. | +| 12500002 | General operation error. | + +**示例：** + +```js +import userIAM_userAuth from '@ohos.userIAM.userAuth'; + +AuthParam authParam = { + challenge: new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]); + authType: userIAM_userAuth.UserAuthType.PIN; + authTrustLevel: userIAM_userAuth.AuthTrustLevel.ATL1; +} +WidgetParam widgetParam = { + title: "输入口令密码"; + windowMode: userIAM_userAuth.WindowModeType.DIALOG_BOX; +} +let userAuthInstance; +try { + userAuthInstance = userIAM_userAuth.getUserAuthInstance(authParam, widgetParam); + console.info("get userAuth instance success"); +} catch (error) { + console.info("get userAuth instance failed, error = " + error); +} + +//订阅认证结果 +try { + userAuthInstance.on('result', { + callback: onResult(result) { + console.log("authV10 result " + result.result); + console.log("authV10 token " + result.token); + console.log("authV10 authType " + result.authType); + } + }); + console.info("subscribe authentication event success"); +} catch (error) { + console.info("subscribe authentication event failed" + error); + //do error +} +//取消订阅认证结果 +try { + userAuthInstance.off('result'); + console.info("cancel subscribe authentication event success"); +} catch (error) { + console.info("cancel subscribe authentication event failed" + error); + //do error +} +``` + +### start10+ + +start(): void + +开始认证。 + +**需要权限**：ohos.permission.ACCESS_BIOMETRIC + +**系统能力**：SystemCapability.UserIAM.UserAuth.Core + +**错误码：** + +以下错误码的详细介绍请参见[用户认证错误码](../errorcodes/errorcode-useriam.md)。 + +| 错误码ID | 错误信息 | +| -------- | ------------------------------------------------ | +| 201 | Permission verification failed. | +| 401 | Incorrect parameters. | +| 12500001 | Authentication failed. | +| 12500002 | General operation error. | +| 12500003 | The operation is canceled. | +| 12500004 | The operation is time-out. | +| 12500005 | The authentication type is not supported. | +| 12500006 | The authentication trust level is not supported. | +| 12500007 | The authentication task is busy. | +| 12500009 | The authenticator is locked. | +| 12500010 | The type of credential has not been enrolled. | +| 12500011 | The authentication is canceled from widget's navigation button. | + +**示例：** + +```js +import userIAM_userAuth from '@ohos.userIAM.userAuth'; + +AuthParam authParam = { + challenge: new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]); + authType: userIAM_userAuth.UserAuthType.PIN; + authTrustLevel: userIAM_userAuth.AuthTrustLevel.ATL1; +} +WidgetParam widgetParam = { + title: "输入口令密码"; + windowMode: userIAM_userAuth.WindowModeType.DIALOG_BOX; +} +let userAuthInstance; +try { + userAuthInstance = userIAM_userAuth.getUserAuthInstance(authParam, widgetParam); + console.info("get userAuth instance success"); +} catch (error) { + console.info("get userAuth instance failed, error = " + error); +} + +try { + userAuthInstance.start(); + console.info("userAuthInstanceV10 start auth success"); +} catch (error) { + console.info("userAuthInstanceV10 start auth failed, error = " + error); + //do error +} +``` + +### cancel10+ + +cancel(): void + +取消认证。 + +> **说明**：此时UserAuthInstance需要是正在进行认证的对象。 + +**需要权限**：ohos.permission.ACCESS_BIOMETRIC + +**系统能力**：SystemCapability.UserIAM.UserAuth.Core + +**错误码：** + +| 错误码ID | 错误信息 | +| -------- | ------------------------------- | +| 201 | Permission verification failed. | +| 401 | Incorrect parameters. | +| 12500002 | General operation error. | + +**示例：** + +```js +import userIAM_userAuth from '@ohos.userIAM.userAuth'; + +AuthParam authParam = { + challenge: new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]); + authType: userIAM_userAuth.UserAuthType.PIN; + authTrustLevel: userIAM_userAuth.AuthTrustLevel.ATL1; +} +WidgetParam widgetParam = { + title: "输入口令密码"; + windowMode: userIAM_userAuth.WindowModeType.DIALOG_BOX; +} + +let userAuthInstance; +try { + userAuthInstance = userIAM_userAuth.getUserAuthInstance(authParam, widgetParam); + console.info("get userAuth instance success"); +} catch (error) { + console.info("get userAuth instance failed, error = " + error); +} + +//开始认证 +try { + userAuthInstance.start(); + console.info("userAuthInstanceV10 start auth success"); +} catch (error) { + console.info("userAuthInstanceV10 start auth failed, error = " + error); + //do error +} + +//取消认证 +try { + userAuthInstance.cancel(); + console.info("cancel auth success"); +} catch (error) { + console.info("cancel auth failed, error = " + error); + //do error +} +``` + +## userIAM_userAuth.getUserAuthInstance10+ + +getUserAuthInstance(authParam: AuthParam, widgetParam: WidgetParam): UserAuthInstance + +获取[UserAuthInstance](#userauthinstance10)对象，用于执行用户身份认证，并支持使用统一用户身份认证组件。 + +> **说明：** +> 每个UserAuthInstance只能进行一次认证，若需要再次进行认证则需重新获取UserAuthInstance。 + +**系统能力**：SystemCapability.UserIAM.UserAuth.Core + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ----------- | ----------------------------- | ---- | -------------------------------------- | +| authParam | [AuthParam](authparam10) | 是 | 挑战值，最大长度为32字节，可以填null。 | +| widgetParam | [WidgetParam](#widgetparam10) | 是 | 认证类型，当前支持FACE。 | + +**返回值：** + +| 类型 | 说明 | +| --------------------------------------- | ------------ | +| [UserAuthInstance](#userauthinstance10) | 认证器对象。 | + +**错误码：** + +以下错误码的详细介绍请参见[用户认证错误码](../errorcodes/errorcode-useriam.md)。 + +| 错误码ID | 错误信息 | +| -------- | ------------------------------------------------ | +| 401 | Incorrect parameters. | +| 12500002 | General operation error. | +| 12500005 | The authentication type is not supported. | +| 12500006 | The authentication trust level is not supported. | + +**示例：** + +```js +import userIAM_userAuth from '@ohos.userIAM.userAuth'; + +AuthParam authParam = { + challenge: new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8]); + authType: userIAM_userAuth.UserAuthType.PIN; + authTrustLevel: userIAM_userAuth.AuthTrustLevel.ATL1; +} +WidgetParam widgetParam = { + title: "输入口令密码"; + windowMode: userIAM_userAuth.WindowModeType.DIALOG_BOX; +} + +try { + let userAuthInstance = userIAM_userAuth.getUserAuthInstance(authParam, widgetParam); + console.info("get userAuth instance success"); +} catch (error) { + console.info("get userAuth instance failed, error = " + error); +} +``` + +## NoticeType10+ + +用户身份认证的通知类型。 + +**系统能力**：SystemCapability.UserIAM.UserAuth.Core + +| 名称 | 值 | 说明 | +| ------------- | ---- | -------------------- | +| WIDGET_NOTICE | 1 | 表示来自组件的通知。 | + +## userIAM_userAuth.sendNotice10+ + +sendNotice(noticeType: NoticeType, eventData: string): void + +在使用统一身份认证组件进行用户身份认证时，用于接收来自统一身份认证组件的通知。 + +**需要权限**：ohos.permission.SUPPORT_USER_AUTH + +**系统能力**：SystemCapability.UserIAM.UserAuth.Core + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ---------- | ------------------------- | ---- | ---------- | +| noticeType | [NoticeType](#noticetype) | 是 | 通知类型。 | +| eventData | string | 是 | 事件数据。 | + +**错误码：** + +以下错误码的详细介绍请参见[用户认证错误码](../errorcodes/errorcode-useriam.md)。 + +| 错误码ID | 错误信息 | +| -------- | --------------------------------------- | +| 201 | Permission verification failed. | +| 202 | The caller is not a system application. | +| 401 | Incorrect parameters. | +| 12500002 | General operation error. | + +**示例：** + +```js +import userIAM_userAuth from '@ohos.userIAM.userAuth'; + +let noticeType = userIAM_userAuth.NoticeType.WIDGET_NOTICE; +sendNotice(noticeType, {"eventData" : "EVENT_AUTH_TYPE_READY"}); +``` + +## UserAuthWidgetMgr10+ + +组件管理接口，可将用身份认证组件注册到UserAuthWidgetMgr中，由UserAuthWidgetMgr进行管理、调度。 + +### on10+ + +on(type: 'command', callback: IAuthWidgetCallback): void + +身份认证组件订阅来自用户认证框架的命令。 + +**系统能力**：SystemCapability.UserIAM.UserAuth.Core + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------------------------- | ---- | ------------------------------------------------------------ | +| type | 'command' | 是 | 订阅事件类型，表明该事件用于用户认证框架向身份认证组件发送命令。 | +| callback | [IAuthWidgetCallback](#iauthwidgetcallback10) | 是 | 组件管理接口的回调函数，用于用户认证框架向身份认证组件发送命令。 | + +**错误码：** + +以下错误码的详细介绍请参见[用户认证错误码](../errorcodes/errorcode-useriam.md)。 + +| 错误码ID | 错误信息 | +| -------- | ------------------------ | +| 401 | Incorrect parameters. | +| 12500002 | General operation error. | + +**示例：** + +```js +import userIAM_userAuth from '@ohos.userIAM.userAuth'; + +let version = 1; +let userAuthWidgetMgr; +try { + userAuthWidgetMgr = userIAM_userAuth.getUserAuthWidgetMgr(version); + console.info("get userAuthWidgetMgr instance success"); +} catch (error) { + console.info("get userAuthWidgetMgr instance failed, error = " + error); +} + +try { + userAuthWidgetMgr.on('command', { + callback: sendCommand(cmdData) { + console.log("The cmdData is " + cmdData); + } + }) + console.info("subscribe authentication event success"); +} catch (error) { + console.info("subscribe authentication event failed, error = " + error); +} +``` + +### off10+ + +off(type: 'command', callback?: IAuthWidgetCallback): void + +身份认证组件取消订阅来自用户认证框架的命令。 + +**系统能力**：SystemCapability.UserIAM.UserAuth.Core + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | --------------------------------------------- | ---- | ------------------------------------------------------------ | +| type | 'command' | 是 | 订阅事件类型，表明该事件用于用户认证框架向身份认证组件发送命令。 | +| callback | [IAuthWidgetCallback](#iauthwidgetcallback10) | 否 | 组件管理接口的回调函数，用于用户认证框架向身份认证组件发送命令。 | + +**错误码：** + +以下错误码的详细介绍请参见[用户认证错误码](../errorcodes/errorcode-useriam.md)。 + +| 错误码ID | 错误信息 | +| -------- | ------------------------ | +| 401 | Incorrect parameters. | +| 12500002 | General operation error. | + +**示例：** + +```js +import userIAM_userAuth from '@ohos.userIAM.userAuth'; + +let version = 1; +let userAuthWidgetMgr; +try { + userAuthWidgetMgr = userIAM_userAuth.getUserAuthWidgetMgr(version); + console.info("get userAuthWidgetMgr instance success"); +} catch (error) { + console.info("get userAuthWidgetMgr instance failed, error = " + error); +} + +//订阅用户身份认证框架的命令 +try { + userAuthWidgetMgr.on('command', { + callback: sendCommand(cmdData) { + console.log("The cmdData is " + cmdData); + } + }) + console.info("subscribe authentication event success"); +} catch (error) { + console.info("subscribe authentication event failed, error = " + error); +} +//取消订阅用户身份认证框架的命令 +try { + userAuthWidgetMgr.off('command'); + console.info("cancel subscribe authentication event success"); +} catch (error) { + console.info("cancel subscribe authentication event failed, error = " + error); +} +``` + +## userIAM_userAuth.getUserAuthWidgetMgr10+ + +getUserAuthWidgetMgr(version: number): UserAuthWidgetMgr + +获取UserAuthWidgetMgr对象，用于执行用户身份认证。 + +> **说明：** +> 每个UserAuthInstance只能进行一次认证，若需要再次进行认证则需重新获取UserAuthInstance。 + +**系统能力**：SystemCapability.UserIAM.UserAuth.Core + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ------ | ---- | -------------------- | +| version | number | 是 | 表示认证组件的版本。 | + +**返回值：** + +| 类型 | 说明 | +| ----------------------------------------- | ------------ | +| [UserAuthWidgetMgr](#userauthwidgetmgr10) | 认证器对象。 | + +**错误码：** + +以下错误码的详细介绍请参见[用户认证错误码](../errorcodes/errorcode-useriam.md)。 + +| 错误码ID | 错误信息 | +| -------- | --------------------------------------- | +| 201 | Permission verification failed. | +| 202 | The caller is not a system application. | +| 401 | Incorrect parameters. | +| 12500002 | General operation error. | + +**示例：** + +```js +import userIAM_userAuth from '@ohos.userIAM.userAuth'; + +let version = 1; +try { + let userAuthWidgetMgr = userIAM_userAuth.getUserAuthWidgetMgr(version); + console.info("get userAuthWidgetMgr instance success"); +} catch (error) { + console.info("get userAuthWidgetMgr instance failed, error = " + error); +} +``` + +## IAuthWidgetCallback10+ + +认证组件通过该回调获取用户认证框架发送的命令。 + +### sendCommand10+ + +sendCommand(cmdData: string): void + +回调函数，用于用户认证框架向组件发送命令。 + +**系统能力**：SystemCapability.UserIAM.UserAuth.Core + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| ------- | ------ | ---- | ---------------------------------- | +| cmdData | string | 是 | 用户身份认证框架向组件发送的命令。 | + +**示例：** + +```js +import userIAM_userAuth from '@ohos.userIAM.userAuth'; + +let version = 1; +try { + let userAuthWidgetMgr = userIAM_userAuth.getUserAuthWidgetMgr(version); + userAuthWidgetMgr.on('command', { + callback: sendCommand(cmdData) { + console.log("The cmdData is " + cmdData); + } + }) + console.info("subscribe authentication event success"); +} catch (error) { + console.info("subscribe authentication event failed, error = " + error); +} +``` + ## AuthResultInfo9+ 表示认证结果信息。 -**系统能力**：以下各项对应的系统能力均为SystemCapability.UserIAM.UserAuth.Core。 +**系统能力**：以下各项对应的系统能力均为SystemCapability.UserIAM.UserAuth.Core | 名称 | 类型 | 必填 | 说明 | | ------------ | ---------- | ---- | -------------------- | @@ -49,12 +714,14 @@ import userIAM_userAuth from '@ohos.userIAM.userAuth'; ## AuthEventKey9+ -表示认证事件类型的关键字，作为[on](#on9)接口的的参数。 +表示认证事件类型的关键字，作为[on](#ondeprecated)接口的的参数。 + +**系统能力**：以下各项对应的系统能力均为SystemCapability.UserIAM.UserAuth.Core。 | 取值类型 | 说明 | | ---------- | ----------------------- | -| "result" | [on](#on9)接口第一个参数为"result"时，[callback](#callback9)回调返回认证的结果信息。 | -| "tip" | [on](#on9)接口第一个参数为"tip"时，[callback](#callback9)回调返回认证操作中的提示信息。 | +| "result" | [on](#ondeprecated)接口第一个参数为"result"时，[callback](#callback9)回调返回认证的结果信息。 | +| "tip" | [on](#ondeprecated)接口第一个参数为"tip"时，[callback](#callback9)回调返回认证操作中的提示信息。 | ## AuthEvent9+ @@ -122,18 +789,24 @@ try { } ``` -## AuthInstance9+ +## AuthInstance(deprecated) 执行用户认证的对象。 -### on9+ +> **说明：** +> 从 API version 9 开始支持，从 API version 10 开始废弃，请使用[UserAuthInstance](#userauthinstance10)替代。 + +### on(deprecated) on : (name : AuthEventKey, callback : AuthEvent) => void 订阅指定类型的用户认证事件。 > **说明：** -> 使用获取到的[AuthInstance](#authinstance9)对象调用该接口进行订阅。 +> 从 API version 9 开始支持，从 API version 10 开始废弃。 + +> **说明：** +> 使用获取到的[AuthInstance](#authinstancedeprecated)对象调用该接口进行订阅。 **系统能力**：SystemCapability.UserIAM.UserAuth.Core @@ -144,10 +817,10 @@ on : (name : AuthEventKey, callback : AuthEvent) => void | name | [AuthEventKey](#autheventkey9) | 是 | 表示认证事件类型，取值为"result"时，回调函数返回认证结果；取值为"tip"时，回调函数返回认证过程中的提示信息。 | | callback | [AuthEvent](#authevent9) | 是 | 认证接口的回调函数，用于返回认证结果或认证过程中的提示信息。 | -以下错误码的详细介绍请参见[用户认证错误码](../errorcodes/errorcode-useriam.md) - **错误码：** +以下错误码的详细介绍请参见[用户认证错误码](../errorcodes/errorcode-useriam.md)。 + | 错误码ID | 错误信息 | | -------- | ------- | | 401 | Incorrect parameters. | @@ -193,14 +866,17 @@ try { } ``` -### off9+ +### off(deprecated) off : (name : AuthEventKey) => void 取消订阅特定类型的认证事件。 +>**说明：** +>从 API version 9 开始支持，从 API version 10 开始废弃。 + > **说明：** -> 需要使用已经成功订阅事件的[AuthInstance](#authinstance9)对象调用该接口进行取消订阅。 +> 需要使用已经成功订阅事件的[AuthInstance](#authinstancedeprecated)对象调用该接口进行取消订阅。 **系统能力**：SystemCapability.UserIAM.UserAuth.Core @@ -208,10 +884,10 @@ off : (name : AuthEventKey) => void | --------- | -------------------------- | ---- | ------------------------- | | name | [AuthEventKey](#autheventkey9) | 是 | 表示认证事件类型，取值为"result"时，取消订阅认证结果；取值为"tip"时，取消订阅认证过程中的提示信息。 | -以下错误码的详细介绍请参见[用户认证错误码](../errorcodes/errorcode-useriam.md) - **错误码：** +以下错误码的详细介绍请参见[用户认证错误码](../errorcodes/errorcode-useriam.md)。 + | 错误码ID | 错误信息 | | -------- | ------- | | 401 | Incorrect parameters. | @@ -256,23 +932,26 @@ try { } ``` -### start9+ +### start(deprecated) start : () => void 开始认证。 > **说明：** -> 使用获取到的[AuthInstance](#authinstance9)对象调用该接口进行认证。 +> 从 API version 9 开始支持，从 API version 10 开始废弃。 + +> **说明：** +> 使用获取到的[AuthInstance](#authinstancedeprecated)对象调用该接口进行认证。 **需要权限**：ohos.permission.ACCESS_BIOMETRIC **系统能力**：SystemCapability.UserIAM.UserAuth.Core -以下错误码的详细介绍请参见[用户认证错误码](../errorcodes/errorcode-useriam.md) - **错误码：** +以下错误码的详细介绍请参见[用户认证错误码](../errorcodes/errorcode-useriam.md)。 + | 错误码ID | 错误信息 | | -------- | ------- | | 201 | Permission verification failed. | @@ -305,23 +984,26 @@ try { } ``` -### cancel9+ +### cancel(deprecated) cancel : () => void 取消认证。 > **说明：** -> 使用获取到的[AuthInstance](#authinstance9)对象调用该接口进行取消认证，此[AuthInstance](#authinstance9)需要是正在进行认证的对象。 +> 从 API version 9 开始支持，从 API version 10 开始废弃。 + +> **说明：** +> 使用获取到的[AuthInstance](#authinstancedeprecated)对象调用该接口进行取消认证，此[AuthInstance](#authinstancedeprecated)需要是正在进行认证的对象。 **需要权限**：ohos.permission.ACCESS_BIOMETRIC **系统能力**：SystemCapability.UserIAM.UserAuth.Core -以下错误码的详细介绍请参见[用户认证错误码](../errorcodes/errorcode-useriam.md) - **错误码：** +以下错误码的详细介绍请参见[用户认证错误码](../errorcodes/errorcode-useriam.md)。 + | 错误码ID | 错误信息 | | -------- | ------- | | 201 | Permission verification failed. | @@ -346,12 +1028,15 @@ try { } ``` -## userIAM_userAuth.getAuthInstance9+ +## userIAM_userAuth.getAuthInstance(deprecated) getAuthInstance(challenge : Uint8Array, authType : UserAuthType, authTrustLevel : AuthTrustLevel): AuthInstance 获取AuthInstance对象，用于执行用户身份认证。 +> **说明：** +> 从 API version 9 开始支持，从 API version 10 开始废弃，请使用[getUserAuthInstance](#useriam_userauthgetuserauthinstance10)替代。 + > **说明：** > 每个AuthInstance只能进行一次认证，若需要再次进行认证则需重新获取AuthInstance。 @@ -367,14 +1052,14 @@ getAuthInstance(challenge : Uint8Array, authType : UserAuthType, authTrustLevel **返回值：** -| 类型 | 说明 | -| ----------------------------------------- | ------------ | -| [AuthInstance](#authinstance9) | 认证器对象。 | - -以下错误码的详细介绍请参见[用户认证错误码](../errorcodes/errorcode-useriam.md) +| 类型 | 说明 | +| --------------------------------------- | ------------ | +| [AuthInstance](#authinstancedeprecated) | 认证器对象。 | **错误码：** +以下错误码的详细介绍请参见[用户认证错误码](../errorcodes/errorcode-useriam.md)。 + | 错误码ID | 错误信息 | | -------- | ------- | | 401 | Incorrect parameters. | @@ -416,10 +1101,10 @@ getAvailableStatus(authType : UserAuthType, authTrustLevel : AuthTrustLevel): vo | authType | [UserAuthType](#userauthtype8) | 是 | 认证类型，当前只支持FACE。 | | authTrustLevel | [AuthTrustLevel](#authtrustlevel8) | 是 | 认证信任等级。 | -以下错误码的详细介绍请参见[用户认证错误码](../errorcodes/errorcode-useriam.md) - **错误码：** +以下错误码的详细介绍请参见[用户认证错误码](../errorcodes/errorcode-useriam.md)。 + | 错误码ID | 错误信息 | | -------- | ------- | | 201 | Permission verification failed. | @@ -460,8 +1145,9 @@ try { | BUSY | 12500007 | 忙碌状态。 | | LOCKED | 12500009 | 认证器已锁定。 | | NOT_ENROLLED | 12500010 | 用户未录入认证信息。 | +| CANCELED_FROM_WIDGET | 12500011 | 当前的认证操作被用户从组件取消。返回这个错误码，表示使用应用自定义认证。 | -## UserAuth8+ +## UserAuth(deprecated) 认证器对象。 @@ -472,7 +1158,7 @@ constructor() 创建认证器对象。 > **说明：** -> 从 API version 8 开始支持，从 API version 9 开始废弃，请使用[getAuthInstance](#useriam_userauthgetauthinstance9)替代。 +> 从 API version 8 开始支持，从 API version 9 开始废弃，请使用[getAuthInstance](#useriam_userauthgetauthinstancedeprecated)替代。 **系统能力**：SystemCapability.UserIAM.UserAuth.Core @@ -480,7 +1166,7 @@ constructor() | 类型 | 说明 | | ---------------------- | -------------------- | -| [UserAuth](#userauth8) | 认证器对象。 | +| [UserAuth](#userauthdeprecated) | 认证器对象。 | **示例：** @@ -566,7 +1252,7 @@ auth(challenge: Uint8Array, authType: UserAuthType, authTrustLevel: AuthTrustLev 执行用户认证，使用回调函数返回结果。 > **说明：** -> 从 API version 8 开始支持，从 API version 9 开始废弃，建议使用[start](#start9)代替。 +> 从 API version 8 开始支持，从 API version 9 开始废弃，建议使用[start](#startdeprecated)代替。 **需要权限**：ohos.permission.ACCESS_BIOMETRIC @@ -617,7 +1303,7 @@ cancelAuth(contextID : Uint8Array) : number 表示通过contextID取消本次认证操作。 > **说明：** -> 从 API version 8 开始支持，从 API version 9 开始废弃，建议使用[cancel](#cancel9)代替。 +> 从 API version 8 开始支持，从 API version 9 开始废弃，建议使用[cancel](#canceldeprecated)代替。 **需要权限**：ohos.permission.ACCESS_BIOMETRIC @@ -818,10 +1504,11 @@ auth.auth(null, userIAM_userAuth.UserAuthType.FACE, userIAM_userAuth.AuthTrustLe **系统能力**：SystemCapability.UserIAM.UserAuth.Core -| 名称 | 值 | 说明 | -| ----------- | ------ | ---------- | -| FACE | 2 | 人脸认证。 | -| FINGERPRINT | 4 | 指纹认证。 | +| 名称 | 值 | 说明 | +| ----------- | ---- | ---------- | +| PIN | 1 | 口令认证。 | +| FACE | 2 | 人脸认证。 | +| FINGERPRINT | 4 | 指纹认证。 | ## AuthTrustLevel8+ @@ -863,7 +1550,7 @@ getAuthenticator(): Authenticator 认证器对象。 > **说明：** -> 从 API version 8 开始废弃，建议使用[UserAuth](#userauth8)替代。 +> 从 API version 8 开始废弃，建议使用[UserAuth](#userauthdeprecated)替代。 ### execute(deprecated) diff --git a/zh-cn/application-dev/reference/errorcodes/errorcode-useriam.md b/zh-cn/application-dev/reference/errorcodes/errorcode-useriam.md index e4f0730df0c192f96055bff6ccb9de918290f00e..2fe3311e9a0256c1d6856a479ec41a823fd60b00 100644 --- a/zh-cn/application-dev/reference/errorcodes/errorcode-useriam.md +++ b/zh-cn/application-dev/reference/errorcodes/errorcode-useriam.md @@ -137,6 +137,19 @@ The type of credential has not been enrolled. 检查是否录入该类型的凭据，如果没有录入，则需要成功录入该类型凭据后再调用相关接口。 +## 12500011 认证被控件取消 + +**错误信息** + +Indicates that this operation is canceled from widget's navigation button. + +**可能原因** + +当前的认证操作被用户从控件取消，返回这个错误码，标识使用应用自定义认证。例如用户点击使用自定义认证，返回到应用自定义认证流程。 + +**处理步骤** + +重新调用认证接口，发起认证。 ## 12700001 人脸录入过程中的操作失败 **错误信息**