@ohos.userIAM.userAuth (User Authentication) (System API)

The userIAM.userAuth module provides user authentication capabilities in identity authentication scenarios, such as device unlocking, payment, and app login.

NOTE

• The initial APIs of this module are supported since API version 6. Newly added APIs will be marked with a superscript to indicate their earliest API version.
• This topic describes only the system APIs provided by the module. For details about its public APIs, see @ohos.userIAM.userAuth (User Authentication).

Modules to Import

import userIAM_userAuth from '@ohos.userIAM.userAuth';

WindowModeType¹⁰⁺

Enumerates the window types of the authentication widget.

System capability: SystemCapability.UserIAM.UserAuth.Core

System API: This is a system API.

WidgetParam¹⁰⁺

Represents the information presented on the user authentication page.

System capability: SystemCapability.UserIAM.UserAuth.Core

NoticeType¹⁰⁺

Defines the type of the user authentication notification.

System capability: SystemCapability.UserIAM.UserAuth.Core

System API: This is a system API.

userAuth.sendNotice¹⁰⁺

sendNotice(noticeType: NoticeType, eventData: string): void

Sends a notification from the user authentication widget.

Required permissions: ohos.permission.SUPPORT_USER_AUTH

System capability: SystemCapability.UserIAM.UserAuth.Core

System API: This is a system API.

Parameters

Error codes

For details about the error codes, see User Authentication Error Codes.

Example

import userAuth from '@ohos.userIAM.userAuth';

interface  EventData {
  widgetContextId: number;
  event: string;
  version: string;
  payload: PayLoad;
}
interface PayLoad {
  type: Object[];
}
try {
  const eventData : EventData = {
    widgetContextId: 123456,
    event: 'EVENT_AUTH_TYPE_READY',
    version: '1',
    payload: {
      type: ['pin']
    } as PayLoad,
  };
  const jsonEventData = JSON.stringify(eventData);
  let noticeType = userAuth.NoticeType.WIDGET_NOTICE;
  userAuth.sendNotice(noticeType, jsonEventData);
  console.log('sendNotice success');
} catch (error) {
  console.error('sendNotice catch error: ' + JSON.stringify(error));
}

UserAuthWidgetMgr¹⁰⁺

Provides APIs for managing the user authentication widget. You can use the APIs to register the user authentication widget with UserAuthWidgetMgr for management and scheduling.

on¹⁰⁺

on(type: 'command', callback: IAuthWidgetCallback): void

Subscribes to commands from the user authentication framework for the user authentication widget.

System capability: SystemCapability.UserIAM.UserAuth.Core

System API: This is a system API.

Parameters

Error codes

For details about the error codes, see User Authentication Error Codes.

Example

import userAuth from '@ohos.userIAM.userAuth';

const userAuthWidgetMgrVersion = 1;
try {
  let userAuthWidgetMgr = userAuth.getUserAuthWidgetMgr(userAuthWidgetMgrVersion);
  console.log('get userAuthWidgetMgr instance success');
  userAuthWidgetMgr.on('command', {
    sendCommand(cmdData) {
      console.log('The cmdData is ' + cmdData);
    }
  })
  console.log('subscribe authentication event success');
} catch (error) {
  console.error('userAuth widgetMgr catch error: ' + JSON.stringify(error));
}

off¹⁰⁺

off(type: 'command', callback?: IAuthWidgetCallback): void

Unsubscribes from commands sent from the user authentication framework.

System capability: SystemCapability.UserIAM.UserAuth.Core

System API: This is a system API.

Parameters

Error codes

For details about the error codes, see User Authentication Error Codes.

Example

import userAuth from '@ohos.userIAM.userAuth';

const userAuthWidgetMgrVersion = 1;
try {
  let userAuthWidgetMgr = userAuth.getUserAuthWidgetMgr(userAuthWidgetMgrVersion);
  console.log('get userAuthWidgetMgr instance success');
  userAuthWidgetMgr.off('command', {
    sendCommand(cmdData) {
      console.log('The cmdData is ' + cmdData);
    }
  })
  console.log('cancel subscribe authentication event success');
} catch (error) {
  console.error('userAuth widgetMgr catch error: ' + JSON.stringify(error));
}

userAuth.getUserAuthWidgetMgr¹⁰⁺

getUserAuthWidgetMgr(version: number): UserAuthWidgetMgr

Obtains a UserAuthWidgetMgr instance for user authentication.

NOTE
A UserAuthInstance instance can be used for an authentication only once.

Required permissions: ohos.permission.SUPPORT_USER_AUTH

System capability: SystemCapability.UserIAM.UserAuth.Core

System API: This is a system API.

Parameters

Return value

Error codes

For details about the error codes, see User Authentication Error Codes.

Example

import userAuth from '@ohos.userIAM.userAuth';

let userAuthWidgetMgrVersion = 1;
try {
  let userAuthWidgetMgr = userAuth.getUserAuthWidgetMgr(userAuthWidgetMgrVersion);
  console.log('get userAuthWidgetMgr instance success');
} catch (error) {
  console.error('userAuth widgetMgr catch error: ' + JSON.stringify(error));
}

IAuthWidgetCallback¹⁰⁺

Provides the callback for returning the commands sent from the user authentication framework to the user authentication widget.

sendCommand¹⁰⁺

sendCommand(cmdData: string): void

Called to return the command sent from the user authentication framework to the user authentication widget.

System capability: SystemCapability.UserIAM.UserAuth.Core

System API: This is a system API.

Parameters

Example

import userAuth from '@ohos.userIAM.userAuth';

const userAuthWidgetMgrVersion = 1;
try {
  let userAuthWidgetMgr = userAuth.getUserAuthWidgetMgr(userAuthWidgetMgrVersion);
  console.log('get userAuthWidgetMgr instance success');
  userAuthWidgetMgr.on('command', {
    sendCommand(cmdData) {
      console.log('The cmdData is ' + cmdData);
    }
  })
  console.log('subscribe authentication event success');
} catch (error) {
  console.error('userAuth widgetMgr catch error: ' + JSON.stringify(error));
}