• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# @ohos.userIAM.faceAuth (Facial Authentication)
2
3The **userIAM.faceAuth** module provides APIs for face enrollment.
4
5> **NOTE**
6>
7> - 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.
8>- The APIs provided by this module are system APIs.
9
10## Modules to Import
11
12```ts
13import userIAM_faceAuth from '@ohos.userIAM.faceAuth';
14```
15
16## FaceAuthManager
17
18Provides APIs for facial authentication management.
19
20### constructor
21
22constructor()
23
24A constructor used to create a **FaceAuthManager** object.
25
26**System capability**: SystemCapability.UserIAM.UserAuth.FaceAuth
27
28**System API**: This is a system API.
29
30**Return value**
31
32| Type                  | Description                |
33| ---------------------- | -------------------- |
34| [FaceAuthManager](#faceauthmanager) | **FaceAuthManager** object.|
35
36**Example**
37
38```ts
39import userIAM_faceAuth from '@ohos.userIAM.faceAuth';
40
41let faceAuthManager = new userIAM_faceAuth.FaceAuthManager();
42```
43
44### setSurfaceId
45
46setSurfaceId(surfaceId: string): void;
47
48Sets an [XComponent surface ID](../arkui-ts/ts-basic-components-xcomponent.md#getxcomponentsurfaceid) for the face preview page in the face enrollment process. This API must be used with [AddCredential](./js-apis-osAccount.md#addcredential8).
49
50**System capability**: SystemCapability.UserIAM.UserAuth.FaceAuth
51
52**System API**: This is a system API.
53
54**Required permissions**: ohos.permission.MANAGE_USER_IDM
55
56**Parameters**
57
58| Name        | Type                              | Mandatory| Description                      |
59| -------------- | ---------------------------------- | ---- | -------------------------- |
60| surfaceId       | string     | Yes  | ID of the surface held by the [XComponent](../arkui-ts/ts-basic-components-xcomponent.md#getxcomponentsurfaceid).|
61
62For details about the following error codes, see [User Authentication Error Codes](../errorcodes/errorcode-useriam.md).
63
64**Error codes**
65
66| ID| Error Message|
67| -------- | ------- |
68| 201 | Permission verification failed. |
69| 202 | The caller is not a system application. |
70| 12700001 | The operation is failed. |
71
72**Example**
73
74```ts
75import userIAM_faceAuth from '@ohos.userIAM.faceAuth';
76
77// The surfaceId is obtained from the XComponent control. The surfaceId here is only an example.
78let surfaceId = '123456';
79let manager = new userIAM_faceAuth.FaceAuthManager();
80try {
81  manager.setSurfaceId(surfaceId);
82  console.info('set surface id success');
83} catch (e) {
84  console.error('set surface id failed, error = ' + e);
85}
86```
87