目录

interactiveLiveness (Face Liveness Detection)

Face liveness detection is a method of determining the real physiological features of an object in certain identity verification scenarios.

Among facial recognition applications, liveness detection can capture faces in real time or trace a user's combined actions of blinking, mouth opening, head shaking, and nodding, and use technologies such as facial keypoint recognition and face tracking to check whether a user is a real live person. This capability effectively defends against common attacks, including print photos, videos, masks, occlusions, and screen recapture, helping to identify fraud and protect user interests.

Since: 5.0.0(12)

Modules to Import

import { interactiveLiveness } from '@kit.VisionKit';

DetectionMode(deprecated)

Enumeration of detection modes.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.AI.Component.LivenessDetect

Since: 5.0.0(12)

Deprecated since: 26.0.0

Name Value Description
SILENT_MODE(deprecated) 'SILENT_MODE'

Silent liveness detection mode, which is not supported currently.

NOTE

This value is deprecated since API version 26.0.0.
INTERACTIVE_MODE(deprecated) 'INTERACTIVE_MODE'

Interactive liveness detection mode.

NOTE

This value is deprecated since API version 26.0.0.

ActionsNumber

Enumeration of the number of actions for face liveness detection.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.AI.Component.LivenessDetect

Since: 5.0.0(12)

Name Value Description
ONE_ACTION 1 Select one action randomly. Currently, this option is not supported.
TWO_ACTION 2 Select two actions randomly. Currently, this option is not supported.
THREE_ACTION 3 Select three actions randomly.
FOUR_ACTION 4 Select four actions randomly.

RouteRedirectionMode

Enumeration of route redirection modes after face liveness detection.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.AI.Component.LivenessDetect

Since: 5.0.0(12)

Name Value Description
BACK_MODE 'back' Returns to the previous page after the face liveness detection is complete.
REPLACE_MODE 'replace' Display the success or failure screen after face liveness detection is complete.

InteractiveLivenessConfig

Configuration of face liveness detection.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.AI.Component.LivenessDetect

Since: 5.0.0(12)

Name Type Read-Only Optional Description
isSilentMode(deprecated) DetectionMode No No

Face liveness detection mode. The default mode is interactive liveness detection.

INTERACTIVE_MODE: interactive liveness detection

NOTE

This value is deprecated since API version 26.0.0.
actionsNum ActionsNumber No Yes

Number of actions for interactive liveness detection. The value can be 3 or 4. The default value is 3. The value is randomly generated based on the following rules:

If the value of actionsNum is 3, actions in combination [Blink,Gaze] do not coexist, and adjacent actions are different.

If the value of actionsNum is 4, the Blink action must exist and appear only once, the Gaze action can appear at most once, actions in combination [Blink,Gaze] are not adjacent to each other, and adjacent actions are different.

This parameter is valid only when isSilentMode is set to INTERACTIVE_MODE.
successfulRouteUrl string No Yes

Path of the screen displayed after face liveness detection is successful. If a screen is customized, this parameter takes effect when routeMode is set to replace.

If this parameter is left empty, the system displays a default detection success screen.

If the redirection fails (for example, the page does not exist), the user remains on the current page.
failedRouteUrl string No Yes

Path of the screen displayed after face liveness detection fails. If a screen is customized, this parameter takes effect when routeMode is set to replace.

If this parameter is left empty, the system displays a default detection failure screen.

If the value is incorrect and the page redirection fails (for example, the page does not exist), the user remains on the current page.
routeMode RouteRedirectionMode No Yes Redirection mode after face liveness detection is complete. The default value is REPLACE_MODE.
challenge string No Yes

Challenge value. This parameter is used only for liveness detection in the image security verification scenario (corresponding to the userData field in the initializeAttestContext method).

To use image security verification, you need to enable Device Security Kit.

The value is a string of 16 to 128 characters. (For a scenario other than image security verification, challenge is left empty or undefined.)

For details about device models supported by image security verification, please refer to Constraints.
speechSwitch boolean No Yes

Indicates whether to enable voice broadcast.

- true: yes

- false: no

Voice broadcast is enabled by default.
isPrivacyMode boolean No Yes

Indicates whether to enable the privacy mode.

true: yes

false: no

The default value is false.

NOTE

To enable the privacy mode, you need to apply for the ohos.permission.PRIVACY_WINDOW permission.

Example

import { interactiveLiveness } from '@kit.VisionKit';

let isSilentMode = "INTERACTIVE_MODE" as interactiveLiveness.DetectionMode;
let routeMode = "replace" as interactiveLiveness.RouteRedirectionMode;
let actionsNum = 3 as interactiveLiveness.ActionsNumber;
let routerOptions: interactiveLiveness.InteractiveLivenessConfig = {
  isSilentMode: isSilentMode,
  routeMode: routeMode,
  actionsNum: actionsNum,
  failedRouteUrl: "pages/FailPage",
  successfulRouteUrl: "pages/SuccessPage"
};

startLivenessDetection

startLivenessDetection(config: InteractiveLivenessConfig): Promise<boolean>

Entry for redirecting to the face liveness detection screen. This API uses a promise to return the result.

Required permission: ohos.permission.CAMERA

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.AI.Component.LivenessDetect

Since: 5.0.0(12)

Parameters

Parameter Type Mandatory Description
config InteractiveLivenessConfig Yes Configuration for redirecting to the face liveness detection screen.

Returns

Type Description
Promise<boolean> Promise used to return the result. true: The face liveness detection screen is successfully displayed. false: The face liveness detection screen fails to be displayed.

Error codes

For details about the error codes, please refer to Universal Error Codes and ArkTS API Error Codes.

ID Error Message
201 Permission denied.
1008301002 Route switching failed.

Example

import { interactiveLiveness } from '@kit.VisionKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

let isSilentMode = "INTERACTIVE_MODE" as interactiveLiveness.DetectionMode;
let actionsNum = 3 as interactiveLiveness.ActionsNumber;
let routerOptions: interactiveLiveness.InteractiveLivenessConfig = {
  actionsNum: actionsNum,
  isSilentMode: isSilentMode
};

// After this API is called, the face liveness detection screen is displayed, and the current screen is hidden.
// After the detection is complete, the system determines whether to return to the current page or redirect to the success or failure page based on the routeMode configuration. In addition, the system asynchronously returns the detection result. You can perform related operations based on the returned result.
interactiveLiveness.startLivenessDetection(routerOptions).then((isSuccess) => {
  if (isSuccess) {
    hilog.info(0x0001, `LivenessCollectionIndex`, `Succeeded in jumping.`);
  } else {
    hilog.info(0x0001, `LivenessCollectionIndex`, `Redirection failed.`);
  }
});

startLivenessDetection

startLivenessDetection(config: InteractiveLivenessConfig, callback: AsyncCallback<InteractiveLivenessResult | undefined>): Promise<boolean>

Entry for redirecting to the face liveness detection screen. This API returns the redirection result asynchronously through a promise and returns the detection result through a callback.

Required permission: ohos.permission.CAMERA

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.AI.Component.LivenessDetect

Since: 5.0.0(12)

Parameters

Parameter Type Mandatory Description
config InteractiveLivenessConfig Yes Configuration for redirecting to the face liveness detection screen.
callback AsyncCallback<InteractiveLivenessResult | undefined> Yes Callback used to return the result. If the face liveness detection is successful, err is undefined and data is the obtained InteractiveLivenessResult. Otherwise, an error object is returned and data is undefined. Currently, it applies only to the RouteRedirectionMode.BACK_MODE redirection mode.

Returns

Type Description
Promise<boolean> Promise used to return the result. true: The face liveness detection screen is successfully displayed. false: The face liveness detection screen fails to be displayed.

Error codes

For details about the error codes, please refer to Universal Error Codes and ArkTS API Error Codes.

ID Error Message
201 Permission denied.
401 Parameter error.
1008301002 Route switching failed.
1008302000 Detection algorithm initialization.
1008302001 Detection timeout.
1008302002 Action mutual exclusion error.
1008302003 Continuity Check Failure.
1008302004 The test is not complete.

Example

import { interactiveLiveness } from '@kit.VisionKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

let isSilentMode = "INTERACTIVE_MODE" as interactiveLiveness.DetectionMode;
let actionsNum = 3 as interactiveLiveness.ActionsNumber;
let routerOptions: interactiveLiveness.InteractiveLivenessConfig = {
  actionsNum: actionsNum,
  isSilentMode: isSilentMode,
  routeMode: "back" as interactiveLiveness.RouteRedirectionMode
};

void interactiveLiveness.startLivenessDetection(routerOptions, (err: BusinessError,
  result: interactiveLiveness.InteractiveLivenessResult | undefined) => { // Failed to obtain the result when the route redirection is incorrect. The result **undefined** is returned.
    if(err.code !== 0 && !result) { // An error code is returned when an error occurs, such as route redirection failure, parameter error, or permission denied. For details, please refer to ArkTS API error codes.
    hilog.error(0x0001, `LivenessCollectionIndex`, `Failed to detect. Code: ${err.code}, message: ${err.message}`);
    return;
  }
  hilog.info(0x0001, 'LivenessCollectionIndex', `Succeeded in detecting result: ${result}`);
});

LivenessType

Enumeration of liveness detection modes.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.AI.Component.LivenessDetect

Since: 5.0.0(12)

Name Value Description
INTERACTIVE_LIVENESS 0 Interactive liveness detection.
SILENT_LIVENESS(deprecated) 1

Silent liveness detection, which is not supported currently.

NOTE

This value is deprecated since API version 26.0.0.
NOT_LIVENESS 2 The detected object is a non-live object. The failure screen will be displayed, and no error information is returned. If you have configured your own failure screen or back route redirection, you are not advised to perform the detection again.

InteractiveLivenessResult

Parameters of the face liveness detection result.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.AI.Component.LivenessDetect

Since: 5.0.0(12)

Name Type Read-Only Optional Description
livenessType LivenessType No No Liveness detection mode.
mPixelMap image.PixelMap No Yes Image with the most liveness features, which is returned after successful detection.
securedImageBuffer ArrayBuffer No Yes Secure stream, which is returned in the image security verification scenario.
certificate Array<string> No Yes Certificate chain, which is returned in the image security verification scenario.

getInteractiveLivenessResult

getInteractiveLivenessResult(): Promise<InteractiveLivenessResult>

Obtains the face liveness detection result. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since version 5.0.0(12).

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.AI.Component.LivenessDetect

Since: 5.0.0(12)

Returns

Type Description
Promise<InteractiveLivenessResult> Promise used to return the face liveness detection result.

Error codes

For details about the error codes, please refer to ArkTS API Error Codes.

ID Error Message
1008302000 Detection algorithm initialization.
1008302001 Detection timeout.
1008302002 Action mutual exclusion error.
1008302003 Continuity Check Failure.
1008302004 The test is not complete.

Example

import { interactiveLiveness } from '@kit.VisionKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

interactiveLiveness.getInteractiveLivenessResult().then(data => {
  hilog.info(0x0001, `LivenessCollectionIndex`, `Succeeded in detecting.`);
});

Action Description

Action Description
1 Nod.
2 Open mouth.
3 Blink.
4 Turn face left.
5 Turn face right.
6 Gaze.