文
章
目
录
章
目
录
HarmonyOS 5的生态体系里，VisionKit是一个非常实用的场景化视觉服务工具包。它将一些原本需要三方应用借助SDK进行集成的常见解决方案，以Kit的形式直接集成到了HarmonyOS系统中，极大地方便了三方应用的快速开发，为人脸活体检测功能的实现提供了便利途径。今天，我们就深入了解一下VisionKit中的人脸活体检测技术。
一、认识VisionKit人脸活体检测
（一）功能与应用场景
人脸活体检测，顾名思义，其主要作用是判断当前进行检测的对象是不是真实的人，而不是照片、硅胶面具或者AI合成的视频等伪装物。虽然该算法接口已经通过了中金金融（CECA）认证，但出于安全考虑，官方不建议在高风险的支付和金融场景中直接使用，更推荐在登录、考勤、实名认证这类低风险场景中应用。另外，需要特别注意的是，人脸活体检测功能不支持在模拟器和预览器上使用。
（二）基本概念与相关配置
- 模块导入：在代码中，通过
import {interactiveLiveness } from @kit.VisionKit来导入人脸活体检测功能接口。 - 检测模式：检测模式分为两种，
SILENT_MODE表示静默活体检测，不过目前暂未支持；INTERACTIVE_MODE是动作活体检测，这是当前可用的模式。 - 动作数量：可设置的动作数量有
ONE_ACTION（1个，暂未支持）、TWO_ACTION（2个，暂未支持）、THREE_ACTION（3个，随机选择且有规则限制）、FOUR_ACTION（4个，同样随机选择并遵循规则）。 - 跳转模式：
RouteRedirectionMode定义了两种跳转模式，BACK_MODE是检测完成后返回上一页，REPLACE_MODE则是检测完成后替换跳转页面，默认使用REPLACE_MODE。 - 配置项：
InteractiveLivenessConfig用于配置检测的各项参数。其中，isSilentMode（检测模式，默认INTERACTIVE_MODE）是必填项，其他如actionsNum（动作数量，默认3）、successfulRouteUrl和failedRouteUrl（成功/失败跳转路径，可选）、routeMode（跳转模式，默认REPLACE_MODE）、challenge（安全摄像头场景挑战值，16 – 128位，可选）、speechSwitch（语音播报开关，默认开启）、isPrivacyMode（隐私模式，需申请权限，默认关闭）均为可选参数。
二、人脸活体检测的使用方法
（一）核心接口调用
- 启动检测接口：
interactiveLiveness.startLivenessDetection是启动人脸活体检测的核心接口，使用时需要传入InteractiveLivenessConfig配置对象来设置检测模式、动作数量等。它支持两种调用方式：- Promise方式：仅返回跳转结果（
boolean类型），示例代码如下：
- Promise方式：仅返回跳转结果（
interactiveLiveness.startLivenessDetection(routerOptions).then((DetectState: boolean) => {
hilog.info(0x0001, "LivenessCollectionIndex", `Succeeded in jumping.`);
}).catch((err: BusinessError) => {
hilog.error(0x0001, "LivenessCollectionIndex", `Failed to jump. Code：${err.code}，message：${err.message}`);
})
- **Promise + 回调方式**：这种方式同时返回跳转结果和检测结果，但仅适用于`BACK_MODE`。示例代码如下：
interactiveLiveness.startLivenessDetection(routerOptions, (err: BusinessError, result: interactiveLiveness.InteractiveLivenessResult | undefined) => {
if(err.code!== 0 &&!result) {
hilog.error(0x0001, "LivenessCollectionIndex", `Failed to detect. Code：${err.code}，message：${err.message}`);
return;
}
hilog.info(0x0001, 'LivenessCollectionIndex', `Succeeded in detecting result：${result}`);
})
- 获取检测结果接口：在检测成功跳转后，可通过
getInteractiveLivenessResult接口获取检测结果，返回值是InteractiveLivenessResult对象，包含检测模式（livenessType，如INTERACTIVE_LIVENESS表示动作活体检测成功、SILENT_LIVENESS暂未支持、NOT_LIVENESS表示非活体）、活体特征图片（mPixelMap，检测成功才有）、安全摄像头相关数据（securedImageBuffer和certificate，安全场景才有）等信息。示例代码如下：
let successResult = interactiveLiveness.getInteractiveLivenessResult();
successResult.then(data => {
hilog.info(0x0001, "LivenessCollectionIndex", `Succeeded in detecting.`);
}).catch((err: BusinessError) => {
hilog.error(0x0001, "LivenessCollectionIndex", `Failed to detect. Code：${err.code}，message：${err.message}`);
})
（二）配置接口详解
调用人脸活体检测时，必须正确配置InteractiveLivenessConfig对象。以下是各项配置参数的详细说明：
- 检测模式（DetectionMode）：
SILENT_MODE：静默活体检测，当前版本暂未支持。INTERACTIVE_MODE：动作活体检测，为默认模式，用户需要完成指定动作来配合检测。
- 动作数量（ActionsNumber）：
ONE_ACTION：随机1个动作，暂未支持。TWO_ACTION：随机2个动作，暂未支持。THREE_ACTION：随机3个动作，其中“眨眼”和“注视”不同时存在且不相邻，相邻动作不重复。FOUR_ACTION：随机4个动作，眨眼仅1次，注视最多1次，“眨眼”和“注视”不相邻，相邻动作不重复。
- 跳转模式（RouteRedirectionMode）：
BACK_MODE：检测完成后调用router.back返回上一页。REPLACE_MODE：检测完成后调用router.replaceUrl跳转，默认采用此模式。
- 其他配置项：
isSilentMode：必填，用于指定检测模式，默认值为INTERACTIVE_MODE。actionsNum：可选，设置动作数量，默认值为3。successfulRouteUrl：可选，检测成功后的跳转路径，若未填写则使用系统默认页面。failedRouteUrl：可选，检测失败后的跳转路径，未填写时也使用系统默认页面。routeMode：可选，设置跳转模式，默认值为REPLACE_MODE。challenge：可选，安全摄像头场景挑战值，长度在16 – 128位之间，空值表示不使用安全摄像头。speechSwitch：可选，语音播报开关，默认开启。isPrivacyMode：可选，隐私模式，开启需申请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"
}
三、DEMO源码示例解析
下面通过一个完整的DEMO示例，来帮助大家更好地理解如何在实际应用中使用人脸活体检测功能：
import { interactiveLiveness } from '@kit.VisionKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { abilityAccessCtrl, common } from '@kit.AbilityKit';
@Entry
@Component
struct FaceLivenessDemo {
// 权限状态，默认未授权
@State userGrant: boolean = false
// 检测结果展示
@State detectionResult: string = ""
// 动作数量，默认3个
@State actionCount: interactiveLiveness.ActionsNumber = interactiveLiveness.ActionsNumber.THREE_ACTION;
// 语音播报开关，默认开启
@State speechEnabled: boolean = true
// 跳转模式，默认检测完成后返回上一页
@State routeMode: interactiveLiveness.RouteRedirectionMode = interactiveLiveness.RouteRedirectionMode.BACK_MODE;
// 权限申请逻辑
private async requestPermissions() {
const context = getContext() as common.UIAbilityContext;
const atManager = abilityAccessCtrl.createAtManager();
const results = await atManager.requestPermissionsFromUser(context, ["ohos.permission.CAMERA"]);
// 判断权限是否全部申请成功
this.userGrant = results.authResults.every(status => status === 0);
}
// 检测配置生成
private generateDetectionConfig(): interactiveLiveness.InteractiveLivenessConfig {
return {
// 设置为动作活体检测模式
isSilentMode: interactiveLiveness.DetectionMode.INTERACTIVE_MODE,
// 设置动作数量
actionsNum: this.actionCount,
// 检测成功后的跳转路径，可自定义，未填则用系统默认
// successfulRouteUrl: "pages/result/success",
// 检测失败后的跳转路径，可自定义，未填则用系统默认
// failedRouteUrl: "pages/result/fail",
// 设置跳转模式
routeMode: this.routeMode,
// 语音播报开关
speechSwitch: this.speechEnabled,
// 安全摄像头场景挑战值，可自定义，未填则不使用安全摄像头
// challenge: "自定义挑战值1234567890abcdef",
// 是否开启隐私模式，开启需申请权限，默认关闭
// isPrivacyMode: true
};
}
// 启动检测
private async startDetection() {
if (!this.userGrant) {
this.detectionResult = "请先申请相机权限";
return;
}
const config = this.generateDetectionConfig();
try {
const jumpSuccess = await interactiveLiveness.startLivenessDetection(config);
if (jumpSuccess) {
hilog.info(0x0001, "Detection", "跳转检测页面成功");
// 检测完成后获取结果（需在返回页面时调用）
const result = await interactiveLiveness.getInteractiveLivenessResult();
this.processResult(result);
}
} catch (err) {
const error = err as BusinessError;
hilog.error(0x0001, "Detection", `检测失败: 错误码${error.code}, 信息${error.message}`);
this.detectionResult = `检测异常：错误码${error.code}`;
}
}
// 结果处理
private processResult(result: interactiveLiveness.InteractiveLivenessResult) {
let status = "";
let livenessType = result.livenessType;
switch (livenessType) {
case 0: // 动作活体检测成功
status = "活体检测通过";
// 可在此处处理特征图片或安全数据
break;
case 2: // 非活体
status = "检测到非活体（照片/视频GJ）";
break;
default:
status = "检测结果异常";
}
this.detectionResult = status;
}
build() {
Column({ space: 40 })
{
// 权限申请按钮
Button(this.userGrant? "权限已授权" : "申请相机权限")
.fontSize(18)
.margin(10)
.padding(12)
.backgroundColor(this.userGrant? Color.Green : Color.Blue)
.onClick(() => this.requestPermissions())
// 动作数量选择
Row({ space: 20 }) {
Text("动作数量:")
.fontSize(16)
Button("3个动作")
.backgroundColor(this.actionCount === 3? Color.Blue : Color.White)
.border({ width: 1, color: Color.Gray })
.onClick(() => this.actionCount = 3)
Button("4个动作")
.backgroundColor(this.actionCount === 4? Color.Blue : Color.White)
.border({ width: 1, color: Color.Gray })
.onClick(() => this.actionCount = 4)
}
// 语音播报开关
Toggle({ type: ToggleType.Checkbox, isOn: this.speechEnabled })
.onChange((isOn: boolean)=>{
this.speechEnabled = isOn;
})
// 跳转模式选择
Row({ space: 20 }) {
Text("跳转模式:")
.fontSize(16)
Button("替换页面")
.backgroundColor(this.routeMode === "replace"? Color.Blue : Color.White)
.border({ width: 1, color: Color.Gray })
.onClick(() => {
this.routeMode = interactiveLiveness.RouteRedirectionMode.REPLACE_MODE;
})
Button("返回上页")
.backgroundColor(this.routeMode === "back"? Color.Blue : Color.White)
.border({ width: 1, color: Color.Gray })
.onClick(() => {
this.routeMode = interactiveLiveness.RouteRedirectionMode.BACK_MODE;
})
}
// 启动检测按钮
Button("开始人脸活体检测")
.fontSize(20)
.padding(16)
.backgroundColor(Color.Orange)
.onClick(() => this.startDetection())
// 结果显示
Text(this.detectionResult)
.fontSize(16)
.margin({
top: 30
})
.foregroundColor(this.detectionResult.includes("通过")? Color.Green : Color.Red)
}
.width("100%")
.height("100%")
.justifyContent(FlexAlign.Center)
.alignItems(HorizontalAlign.Center)
}
}
在这个示例中，FaceLivenessDemo组件实现了权限申请、检测配置生成、启动检测以及结果处理等功能。用户可以在界面上选择动作数量、跳转模式，控制语音播报开关，点击按钮启动检测，检测结果会在界面上展示出来。
四、注意事项
（一）检测模式
目前仅INTERACTIVE_MODE（动作活体检测）可用，用户需完成3或4个随机动作（如眨眼、点头、张嘴、左摇头、右摇头、注视）来完成检测，系统会通过动作组合验证活体，同时遵循特定规则避免相邻动作重复或出现特定组合。SILENT_MODE（静默活体检测）虽然暂未支持，但未来可能会带来更便捷的检测体验，无需用户做动作，通过其他技术（如微表情、光线反射等）就能检测活体。
（二）配置要点
通过InteractiveLivenessConfig配置对象，开发者可以灵活设置动作数量和跳转逻辑。actionsNum可选3或4，默认3个动作，不同数量下动作组合有不同规则。routeMode可选择BACK_MODE返回上一页或REPLACE_MODE替换跳转，默认是REPLACE_MODE 。successfulRouteUrl和failedRouteUrl可设置成功或失败后的自定义跳转路径，若不设置则使用系统默认页面。
（三）错误处理
在使用过程中，可能会遇到一些错误：
201（Permission denied）：表示未申请ohos.permission.CAMERA权限，需要在代码中添加权限申请逻辑。1008301002（Route switching failed）：说明路由配置错误，此时需要检查successfulRouteUrl和failedRouteUrl路径是否正确，以及routeMode是否与页面路由匹配。1008302000 - 1008302004（检测相关错误）：这类错误通常是检测过程中算法初始化失败、超时或动作不符合规则导致的。可以通过回调或Promise的catch捕获错误码，提示用户重新检测并检查动作是否合规。
通过以上内容，相信大家对HarmonyOS 5中VisionKit的人脸活体检测功能有了全面的了解，希望能帮助大家在实际开发中更好地运用这一技术。
