@yidun/livedetect-sdk-h5

v3.0.2

Published

a month ago

活体检测 H5

Downloads

175

0High
0Medium
0Low

livedetect h5 livedetect-sdk-h5

活体检测（NELiveDetection）

简介

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
# yarn
yarn add @yidun/livedetect-sdk-h5
# pnpm
pnpm add @yidun/livedetect-sdk-h5

在代码中引用：

import NELiveDetection from '@yidun/livedetect-sdk-h5';

// 样式文件引入
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.v3.0.2.min.css" />
<!-- body 标签下引入 sdk -->
<script src="https://yidunfe.nosdn.127.net/sdk/NELiveDetection.v3.0.2.umd.js"></script>

引入该脚本之后，不需要像模块引入方式一样通过 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 | 语言，支持列表见下方语言支持列表 | 否 | | 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 | 浏览器不支持 | | 11003 | 用户拒绝相机权限授权 | | 11004 | 找不到摄像头 | | 11005 | 异常硬件导致无法读取摄像头 | | 11006 | 摄像头分辨率过低 | | 11007 | 未知问题导致摄像头无法被使用 | | 11008 | 炫瞳检测失败 | | 12000 | 获取配置接口网络错误 | | 12001 | 获取配置失败，请检查接入配置是否正确 |

常⻅问题

1. 提示「浏览器不⽀持」：

先检查下部署是否为 https 协议；
然后检查当前使⽤的浏览器是否⽀持 webrtc。

2. 提示「没有摄像头权限」：

检查客户是否开启相机授权，没有开启权限可根据错误回调做提示用户。