活体检测（NELiveDetection）
2024.11.20 10:20:47
简介
NELiveDetection 为支持活体检测 h5 的 JS SDK，根据提示做出相应动作，SDK 实时采集动态信息，判断用户是否为活体、真人。
浏览器支持
pc 浏览器需内置 chromium 内核且保证版本符合如下要求：
| 浏览器 | 最低版本 |
|---|---|
| Chrome | 56 |
| Edge | 12 |
| Firefox | 36 |
| Opera | 40 |
| Safari | 11 |
| IE | 不支持 |
移动端浏览器：
| 浏览器 | 最低版本 |
|---|---|
| Safari in iOS | 11 |
| Android Browser | 99 |
| Opera Mobile | 64 |
| Chrome for Android | 99 |
| Firefox for Android | 96 |
| UC Browser for Android | 12.12 |
| Samsung Internet | 6.2 |
| QQ Browser | 10.4 |
| Opera Mini | 不支持 |
浏览器不支持时，会自动走降级方式（视频活体录制上传）。
快速上手
按照以下步骤快速调用示例。
资源引入
目前支持两种接入 SDK 方式。
1. 模块引入
下载 npm 包：
# npm
npm install @yidun/livedetect-sdk-h5@2.1.0
# yarn
yarn add @yidun/livedetect-sdk-h5@2.1.0
# pnpm
pnpm add @yidun/livedetect-sdk-h5@2.1.0
在代码中引用：
import NELiveDetection from '@yidun/livedetect-sdk-h5@2.1.0';
// 样式文件引入
import '@yidun/livedetect-sdk-h5/dist/es/NELiveDetection.css';
2. script 引入
body 标签下引入 SDK：
<!-- head 标签下样式文件引入 -->
<link rel="stylesheet" href="https://yidunfe.nosdn.127.net/sdk/NELiveDetection.v2.1.0.min.css"/>
<!-- body 标签下引入 sdk -->
<script src="https://yidunfe.nosdn.127.net/sdk/NELiveDetection.v2.1.0.umd.js"></script>
（v3.0.2版本针对ios 14.3及以下的系统版本兼容性不佳，如碰到相关的兼容性问题建议引入v2.0.1版本）
引入该脚本之后，不需要像模块引入方式一样通过 import 引入 NELiveDetection 变量，该变量已经挂载到全局，初始化时直接按下列方式即可：
const neLiveDetection = new NELiveDetection({
// ...
});
快速调用示例
请注意，示例需要启动一个本地服务（比如 vscode 的 LiveServer、vue-cli 的 serve 或 webpack 的 devServer，并且必须是 https 方式，不然会提示浏览器不支持。
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0, maximum-scale=1.0, viewport-fit=cover"/>
<meta http-equiv="X-UA-Compatible" content="ie=edge" />
<meta name="referrer" content="origin"/>
<title>活体检测H5接入示例</title>
<style>
#NELiveDetection {
width: 100%;
height: 100%;
}
</style>
<!-- 引入 sdk 样式文件 -->
<link rel="stylesheet" href="NELiveDetection.min.css"/>
</head>
<body>
<div id="root">
<div id="NELiveDetection"></div>
</div>
<!-- 引入 sdk -->
<script src="NELiveDetection.umd.js"></script>
<script>
(function () {
const neLiveDetection = new NELiveDetection({
businessKey: '易盾申请的 businessKey',
container: '#NELiveDetection',
diameter: 220,
onMount: (instance) => {},
// 等价于 instance.on('ready', () => {})
onReady: (instance) => {},
});
// 实例化后必须调用 mount 方法
neLiveDetection && neLiveDetection.mount();
// 调用 start 方法开始活体检测流程
neLiveDetection.on('ready', () => {
neLiveDetection.start();
});
// 流程走完并检验完成
neLiveDetection.on('verify', (token) => {
console.log('token:', token);
// 在校验成功后拿到 token 去做服务端校验
});
// 发生错误
neLiveDetection.on('error', (err) => {
console.log('err:', err);
switch (err.name) {
case '10000': // 校验未通过错误码
// 如果校验未成功，会返回 err 对象，做后续处理
break;
// 其他错误码
default:
break;
}
});
})();
</script>
</body>
</html>
配置说明
在初始化实例时，可以传入以下配置：
| 参数 | 类型 | 默认值 | 描述 | 是否必填 |
|---|---|---|---|---|
| businessKey | String | - | 从易盾申请的 bussinessKey |
是 |
| container | String | HTMLElement | - | SDK 挂载的容器 | 是 |
| diameter | Number | 220 |
图像显示区域大小，单位为 px |
否 |
| audio | Boolean | false |
摄像头唤起时是否开启声音录制 | 否 |
| footerTip | Boolean | true |
是否显示底部图像和文字提示 | 否 |
| lang | string | zh-CN |
语言，支持列表见下方语言支持列表 | 否 |
| fallback | Boolean | true |
是否降级到视频录制上传（2.1.0支持） | 否 |
| onMount | Function | - | 初始化实例挂载完成回调 | 否 |
| onReady | Function | - | 活体检测前的准备工作已完成回调 | 否 |
特别说明
onMount 和 onReady 的区别：
onMount 和 onReady 触发时，均会返回活体检测的实例，即传入的第一个参数；二者触发时机有所不同：
onMount 触发时，初始化函数结束和完成实例的生成，注意这并不代表活体检测是可用的（比如不能调用 .start() 开启流程），此方法只触发一次；
onReady 触发时，说明活体检测准备就绪，可以开始流程，所有实例方法都可调用，onReady 初始化时会触发一次，之后每次调用 .restart() 都会再次调用。
实例方法
你可以在实例完成创建之后，调用以下方法：
instance.start()：
开始验证，此时会唤起摄像头，该⽅法只会在⾸次验证的时候调⽤，后续需要⽤ restart ⽅法。
instance.restart()：
当动作超时或者采集流程超时，需要重新发起认证，这时候⽤ restart ⽅法。
instance.dispose()：
销毁验证流程，建议在组件卸载时调⽤。
事件回调
在验证过程中会抛出⼀些回调事件，⽤户可以监听这些事件，⾃⾏做⼀些处理，⽐如 ready，校验通过，超时...
- ready 事件
instance.on('ready', () => {
// 活体验证已准备好
// 可在此调用 .start() 方法
});
- timeout 事件
instance.on('timeout', () => {
// 检测超时，可提示用户重新开始流程
});
- checking 事件
instance.on('checking', () => {
// 流程走完后，进行校验的开始回调
// 可在页面显示 loading 状态
});
- check-done 事件
instance.on('check-done', () => {
// 校验完成，可在页面关闭 loading 状态，进行后续操作
});
- verify 事件
instance.on('verify', (token) => {
console.log(token);
// 在验证成功后才会触发，拿到 token，进行后续的服务端校验（recheck）
});
- error 事件
instance.on('error', (err) => {
// 发生错误
// err.name 为错误码，字符串类型；
// err.message 为错误信息，字符串类型
console.log(err);
});
支持语言
| 语言 | 参数值 |
|---|---|
| 中文 | zh-CN |
| 英文 | en-US |
错误码
| 错误码 | 错误信息 |
|---|---|
| 10000 | 校验不通过 |
| 10001 | 校验接口网络错误 |
| 11000 | 获取相机权限失败 |
| 11001 | 鉴权不通过 |
| 11002 | 浏览器不支持，默认降级到视频活体，如不需要，可以将初始化参数 fallback 设置为 false |
| 11003 | 用户拒绝相机权限授权 |
| 11004 | 找不到摄像头 |
| 11005 | 异常硬件导致无法读取摄像头 |
| 11006 | 摄像头分辨率过低 |
| 11007 | 未知问题导致摄像头无法被使用 |
| 11008 | 炫瞳检测失败 |
| 12000 | 获取配置接口网络错误 |
| 12001 | 获取配置失败，请检查接入配置是否正确 |
常⻅问题
1. 提示「浏览器不⽀持」：
- 先检查下部署是否为
https协议； - 然后检查当前使⽤的浏览器是否⽀持
webrtc。
2. 提示「没有摄像头权限」：
- 检查客户是否开启相机授权，没有开启权限可根据错误回调做提示用户。
