# interactiveLiveness（人脸活体检测）

人脸活体检测是指在一些身份验证场景中，确定对象真实生理特征的方法。

在人脸识别应用中，活体检测能实时捕捉人脸或者通过眨眼、张嘴、摇头、点头等组合动作，使用人脸关键点定位和人脸追踪等技术，验证用户是否为真实活体操作。可有效抵御照片、视频、面具、遮挡以及屏幕翻拍等常见的攻击手段，从而帮助用户甄别欺诈行为，保障用户的利益。

**起始版本：** 5.0.0(12)

#### 导入模块

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

#### DetectionMode

检测模式的枚举值。

**元服务API：** 从版本5.0.0(12)开始，该接口支持在元服务中使用。

**模型约束：** 此接口仅可在Stage模型下使用。

**系统能力：** SystemCapability.AI.Component.LivenessDetect

**起始版本：** 5.0.0(12)

| 名称 | 值 | 说明 |
| --- | --- | --- |
| SILENT_MODE | SILENT_MODE | 表示静默活体检测模式，暂未支持。 |
| INTERACTIVE_MODE | INTERACTIVE_MODE | 表示动作活体检测模式。 |

#### ActionsNumber

人脸活体检测的动作检测个数的枚举值。

**元服务API：** 从版本5.0.0(12)开始，该接口支持在元服务中使用。

**模型约束：** 此接口仅可在Stage模型下使用。

**系统能力：** SystemCapability.AI.Component.LivenessDetect

**起始版本：** 5.0.0(12)

| 名称 | 值 | 说明 |
| --- | --- | --- |
| ONE_ACTION | 1 | 随机选择一个动作，暂未支持。 |
| TWO_ACTION | 2 | 随机选择两个动作，暂未支持。 |
| THREE_ACTION | 3 | 随机选择三个动作。 |
| FOUR_ACTION | 4 | 随机选择四个动作。 |

#### RouteRedirectionMode

人脸活体检测完成的路由跳转模式的枚举值。

**元服务API：** 从版本5.0.0(12)开始，该接口支持在元服务中使用。

**模型约束：** 此接口仅可在Stage模型下使用。

**系统能力：** SystemCapability.AI.Component.LivenessDetect

**起始版本：** 5.0.0(12)

| 名称 | 值 | 说明 |
| --- | --- | --- |
| BACK_MODE | back | 表示人脸活体检测完成后返回到上一页。 |
| REPLACE_MODE | replace | 表示人脸活体检测完跳转到成功或失败页面。 |

#### InteractiveLivenessConfig

人脸活体检测的配置项。

**元服务API：** 从版本5.0.0(12)开始，该接口支持在元服务中使用。

**模型约束：** 此接口仅可在Stage模型下使用。

**系统能力：** SystemCapability.AI.Component.LivenessDetect

**起始版本：** 5.0.0(12)

| 名称 | 类型 | 只读 | 可选 | 说明 |
| --- | --- | --- | --- | --- |
| isSilentMode | DetectionMode | 否 | 否 | 表示的是人脸活体检测模式，默认动作活体检测模式。 INTERACTIVE_MODE表示动作活体检测模式。 |
| actionsNum | ActionsNumber | 否 | 是 | 表示动作活体检测的动作数量，数量范围3或4个，默认3个动作。随机生成，规则如下： 当actionsNum=3时，[眨眼，注视]组合中的动作元素不会同时存在并且相邻的动作元素不会相同。 当actionsNum=4时，眨眼动作元素有且仅有1次，注视动作元素最多出现1次，[眨眼，注视]组合中的动作元素不会相邻，相邻的动作元素不会相同。 该参数只有当isSilentMode是INTERACTIVE_MODE的时候有效。 |
| successfulRouteUrl | string | 否 | 是 | 表示人脸活体检测成功后跳转的页面路径。如果自定义界面，routeMode值为replace时生效。 如果不填，系统有默认的检测成功页面。 |
| failedRouteUrl | string | 否 | 是 | 表示人脸活体检测失败后跳转的页面路径。如果自定义界面，routeMode值为replace时生效。 如果不填，系统有默认的检测失败页面。 |
| routeMode | RouteRedirectionMode | 否 | 是 | 人脸活体检测完成后跳转模式，默认REPLACE_MODE模式。 |
| challenge | string | 否 | 是 | 挑战值。仅用于安全摄像头场景（对应initializeAttestContext方法中的“userData”字段）的活体检测。 使用安全摄像头场景的前提需要开通Device Security服务。 长度范围是[16,128]之间（challenge传空或者undefined表示不使用安全摄像头）。 安全摄像头目前支持的设备详情请查看约束与限制。 |
| speechSwitch | boolean | 否 | 是 | 语音播报的开关。 - true表示开启语音播报。 - false表示关闭语音播报。 默认开启语音播报。 |
| isPrivacyMode | boolean | 否 | 是 | 是否设置隐私模式。 - true：设置隐私模式。 - false：不设置隐私模式。 默认值为false。 说明： 当设置隐私模式时，需要申请ohos.permission.PRIVACY_WINDOW权限。 |

**示例：**

```
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>

跳转到人脸活体检测页面的入口。使用Promise异步回调。

**需要权限：** ohos.permission.CAMERA

**元服务API：** 从版本5.0.0(12)开始，该接口支持在元服务中使用。

**模型约束：** 此接口仅可在Stage模型下使用。

**系统能力：** SystemCapability.AI.Component.LivenessDetect

**起始版本：** 5.0.0(12)

**参数：**

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| config | InteractiveLivenessConfig | 是 | 跳转到人脸活体检测页面的配置项 |

**返回值：**

| 类型 | 说明 |
| --- | --- |
| Promise<boolean> | Promise对象。返回true表示跳转人脸活体检测页面成功；返回false表示跳转人脸活体检测页面失败。 |

**错误码：**

以下错误码的详细介绍请参见通用错误码和ArkTS API错误码。

| 错误码ID | 错误信息 |
| --- | --- |
| 201 | Permission denied. |
| 1008301002 | Route switching failed. |

**示例：**

```
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
};

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>

跳转到人脸活体检测页面的入口。使用Promise异步回调获取跳转结果，使用callback回调获取检测结果。

**需要权限：** ohos.permission.CAMERA

**元服务API：** 从版本5.0.0(12)开始，该接口支持在元服务中使用。

**模型约束：** 此接口仅可在Stage模型下使用。

**系统能力：** SystemCapability.AI.Component.LivenessDetect

**起始版本：** 5.0.0(12)

**参数：**

| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| config | InteractiveLivenessConfig | 是 | 跳转到人脸活体检测页面的配置项。 |
| callback | AsyncCallback<InteractiveLivenessResult \| undefined> | 是 | 回调函数。当人脸活体检测成功，err为undefined，data为获取到的InteractiveLivenessResult；否则为错误对象。当前只适用于RouteRedirectionMode.BACK_MODE跳转模式。 |

**返回值：**

| 类型 | 说明 |
| --- | --- |
| Promise<boolean> | Promise对象。返回true表示跳转人脸活体检测页面成功；返回false表示跳转人脸活体检测页面失败。 |

**错误码：**

以下错误码的详细介绍请参见ArkTS API错误码。

| 错误码ID | 错误信息 |
| --- | --- |
| 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. |

**示例：**

```
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) => { // 当路由跳转错误时，获取结果失败，result返回undefined
  if (err.code !== 0 && !result) { // 在发生错误如路由跳转失败/参数错误/权限被拒绝时，会抛出错误码，详见ArkTS API错误码
    hilog.error(0x0001, `LivenessCollectionIndex`, `Failed to detect. Code: ${err.code}, message: ${err.message}`);
    return;
  }
  hilog.info(0x0001, 'LivenessCollectionIndex', `Succeeded in detecting result: ${result}`);
});
```

#### LivenessType

活体检测模式的枚举值。

**元服务API：** 从版本5.0.0(12)开始，该接口支持在元服务中使用。

**模型约束：** 此接口仅可在Stage模型下使用。

**系统能力：** SystemCapability.AI.Component.LivenessDetect

**起始版本：** 5.0.0(12)

| 名称 | 值 | 说明 |
| --- | --- | --- |
| INTERACTIVE_LIVENESS | 0 | 表示当前检测的结果是动作活体检测。 |
| SILENT_LIVENESS | 1 | 表示当前检测的结果是静默活体检测，暂未支持。 |
| NOT_LIVENESS | 2 | 表示当前检测的结果是非活体，跳转的是失败页面，不会返回错误信息。如果配置了失败页面或者back路由跳转，不建议有重新检测的场景。 |

#### InteractiveLivenessResult

返回人脸活体检测结果的相关参数。

**元服务API：** 从版本5.0.0(12)开始，该接口支持在元服务中使用。

**模型约束：** 此接口仅可在Stage模型下使用。

**系统能力：** SystemCapability.AI.Component.LivenessDetect

**起始版本：** 5.0.0(12)

| 名称 | 类型 | 只读 | 可选 | 说明 |
| --- | --- | --- | --- | --- |
| livenessType | LivenessType | 否 | 否 | 活体检测模式。 |
| mPixelMap | image.PixelMap | 否 | 是 | 检测成功后返回最具有活体特征的图片。 |
| securedImageBuffer | ArrayBuffer | 否 | 是 | 安全摄像头场景返回的安全流。 |
| certificate | Array<string> | 否 | 是 | 安全摄像头场景返回的证书链。 |

#### getInteractiveLivenessResult

getInteractiveLivenessResult(): Promise<InteractiveLivenessResult>

获取人脸活体检测的结果。使用Promise异步回调。

**元服务API：** 从版本5.0.0(12)开始，该接口支持在元服务中使用。

**模型约束：** 此接口仅可在Stage模型下使用。

**系统能力：** SystemCapability.AI.Component.LivenessDetect

**起始版本：** 5.0.0(12)

**返回值：**

| 类型 | 说明 |
| --- | --- |
| Promise<InteractiveLivenessResult> | Promise对象，返回人脸活体检测的结果。 |

**错误码：**

以下错误码的详细介绍请参见ArkTS API错误码。

| 错误码ID | 错误信息 |
| --- | --- |
| 1008302000 | Detection algorithm initialization. |
| 1008302001 | Detection timeout. |
| 1008302002 | Action mutual exclusion error. |
| 1008302003 | Continuity Check Failure. |
| 1008302004 | The test is not complete. |

**示例：**

```
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.`);
});
```

#### 动作说明

| 动作 | 描述 |
| --- | --- |
| 1 | 点头 |
| 2 | 张嘴 |
| 3 | 眨眼 |
| 4 | 左摇头 |
| 5 | 右摇头 |
| 6 | 注视 |