• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# @ohos.userIAM.faceAuth (Facial Authentication) (System API)
2
3<!--Kit: User Authentication Kit-->
4<!--Subsystem: UserIAM-->
5<!--Owner: @WALL_EYE-->
6<!--SE: @lichangting518-->
7<!--TSE: @jane_lz-->
8
9The **userIAM.faceAuth** module provides APIs for face enrollment.
10
11> **NOTE**
12>
13> - The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version.
14>
15> - The APIs provided by this module are system APIs.
16
17## Modules to Import
18
19```ts
20import { faceAuth } from '@kit.UserAuthenticationKit';
21```
22
23## FaceAuthManager
24
25Provides APIs for facial authentication management.
26
27### constructor
28
29constructor()
30
31A constructor used to create a **FaceAuthManager** object.
32
33**System capability**: SystemCapability.UserIAM.UserAuth.FaceAuth
34
35**System API**: This is a system API.
36
37**Return value**
38
39| Type                  | Description                |
40| ---------------------- | -------------------- |
41| [FaceAuthManager](#faceauthmanager) | **FaceAuthManager** object|
42
43**Example**
44
45```ts
46import { faceAuth } from '@kit.UserAuthenticationKit';
47
48let faceAuthManager = new faceAuth.FaceAuthManager();
49```
50
51### setSurfaceId
52
53setSurfaceId(surfaceId: string): void;
54
55Sets an [XComponent surface ID](../apis-arkui/arkui-ts/ts-basic-components-xcomponent.md#getxcomponentsurfaceid9) for the face preview page in the face enrollment process. This API must be used with [addCredential](../apis-basic-services-kit/js-apis-osAccount-sys.md#addcredential8).
56
57**System capability**: SystemCapability.UserIAM.UserAuth.FaceAuth
58
59**System API**: This is a system API.
60
61**Required permissions**: ohos.permission.MANAGE_USER_IDM
62
63**Parameters**
64
65| Name        | Type                              | Mandatory| Description                      |
66| -------------- | ---------------------------------- | ---- | -------------------------- |
67| surfaceId       | string     | Yes  | ID of the surface held by [XComponent](../apis-arkui/arkui-ts/ts-basic-components-xcomponent.md#getxcomponentsurfaceid9).|
68
69For details about the error codes, see [User Authentication Error Codes](errorcode-useriam.md).
70
71**Error codes**
72
73| ID| Error Message|
74| -------- | ------- |
75| 201 | Permission denied. |
76| 202 | Permission denied. Called by non-system application. |
77| 12700001 | The service is unavailable. |
78
79**Example**
80
81```ts
82import { faceAuth } from '@kit.UserAuthenticationKit';
83import { BusinessError } from '@kit.BasicServicesKit';
84
85// The surfaceId is obtained from the XComponent control. The surfaceId here is only an example.
86let surfaceId = '123456';
87let manager = new faceAuth.FaceAuthManager();
88try {
89  manager.setSurfaceId(surfaceId);
90  console.info('set surface id success');
91} catch (error) {
92  const err: BusinessError = error as BusinessError;
93  console.error(`set surface id failed, Code is ${err?.code}, message is ${err?.message}`);
94}
95```
96