活体检测H5-V2
<p>[TOC]</p>
<h3>简介</h3>
<ul>
<li>活体检测H5是通过引入H5页面实现人像活体检测的RESTful Web Service接口</li>
<li>本接口支持静默、动作、闪光</li>
<li>检测成功之后提取一张人像照片</li>
</ul>
<p>演示（请在手机端打开）：<a href="https://api-h5.jumdata.com/lifecheck/v2/demo">https://api-h5.jumdata.com/lifecheck/v2/demo</a></p>
<h3>接入流程</h3>
<p><img src="https://www.showdoc.com.cn/server/api/attachment/visitFile?sign=4f31f02100af6432d170ef488b776370&amp;file=file.png" alt="" /></p>
<ol>
<li>接入者服务端通过调用聚美智数活体检测初始化接口获取token，并把token返回给接入者页面； </li>
<li>接入者页面带上token跳转至聚美智数活体检测H5页面进行活体检测；检测结束后，检测H5页面会自动跳转至初始化时指定的地址returnUrl，并返回token和检测结果；</li>
<li>接入者服务端通过调用聚美智数获取检测结果接口获取结果；</li>
</ol>
<h3>接口调用说明</h3>
<h4>请求方式</h4>
<p>如接口没有单独说明，所有接口均为：<strong>POST</strong></p>
<h4>请求格式</h4>
<p>如接口没有单独说明，所有接口均为：<strong>application/x-www-form-urlencoded</strong></p>
<h4>请求参数</h4>
<p>请求参数均包括公共参数和业务参数（业务参数见具体接口说明）
如接口没有单独说明，所有接口调用时，均需要把<strong>公共参数</strong>和<strong>业务参数</strong>一并放在<strong>请求参数</strong>中提交</p>
<p><a name="公共请求参数"></a></p>
<h5>公共请求参数</h5>
<table>
<thead>
<tr>
<th>名称</th>
<th>类型</th>
<th>必须</th>
<th><div style="width:420px;">说明</div></th>
</tr>
</thead>
<tbody>
<tr>
<td>appId</td>
<td>String</td>
<td>是</td>
<td>服务商分配的唯一标识</td>
</tr>
<tr>
<td>timestamp</td>
<td>Long</td>
<td>是</td>
<td>当前时间戳（毫秒）</td>
</tr>
<tr>
<td>sign</td>
<td>String</td>
<td>是</td>
<td>签名，详见签名算法说明</td>
</tr>
</tbody>
</table>
<h5>签名算法说明</h5>
<pre><code>sign = sha256(appId + appSecret + timestamp)</code></pre>
<p>用服务商分配的 <strong>appId</strong>、服务商分配的 <strong>appSecret</strong>，当前时间戳（毫秒） <strong>timestamp</strong>，按上述顺序拼接成字符串，再进行 <strong>sha256</strong> 哈希得到。如下：</p>
<pre><code class="language-java">String appId = &quot;xyzxy2121zxyz&quot;；
String timestamp = &quot;1555378976238&quot;；
String appSecret = &quot;efcefcef1121cefcefc1212121&quot;；
String str = appId + appSecret + timestamp；
String sign = sha256(str)；</code></pre>
<h4>返回说明</h4>
<h5>公共返回字段说明</h5>
<p>所有接口均返回以下公共字段：</p>
<table>
<thead>
<tr>
<th>字段名</th>
<th><div style="width:420px">说明</div></th>
</tr>
</thead>
<tbody>
<tr>
<td>code</td>
<td>返回码，详见：code返回码说明</td>
</tr>
<tr>
<td>msg</td>
<td>code对应的描述</td>
</tr>
<tr>
<td>charge</td>
<td>计费标志 true为计费，false为不计费</td>
</tr>
<tr>
<td>taskNo</td>
<td>本次请求号</td>
</tr>
<tr>
<td>data</td>
<td>返回具体结果，object类型，详见data返回字段描述</td>
</tr>
</tbody>
</table>
<p><a name="公共code返回码说明"></a></p>
<h5>公共code返回码说明</h5>
<p>所有接口公共返回码如下：</p>
<table>
<thead>
<tr>
<th>code</th>
<th><div style="width:420px;">说明</div></th>
</tr>
</thead>
<tbody>
<tr>
<td>200</td>
<td>成功</td>
</tr>
<tr>
<td>400</td>
<td>参数错误</td>
</tr>
<tr>
<td>404</td>
<td>接口地址不正确</td>
</tr>
<tr>
<td>500</td>
<td>系统维护，请稍候再试</td>
</tr>
<tr>
<td>601</td>
<td>接口未开通</td>
</tr>
<tr>
<td>602</td>
<td>账号停用</td>
</tr>
<tr>
<td>604</td>
<td>接口停用</td>
</tr>
<tr>
<td>606</td>
<td>调用超限，请稍候再试</td>
</tr>
<tr>
<td>607</td>
<td>ip不在白名单</td>
</tr>
<tr>
<td>609</td>
<td>请求过于频繁，请稍候再试</td>
</tr>
<tr>
<td>610</td>
<td>请求超时</td>
</tr>
<tr>
<td>999</td>
<td>其他，以实际返回为准</td>
</tr>
</tbody>
</table>
<hr />
<h3>活体检测初始化</h3>
<h4>请求地址</h4>
<p><code>https://api.jumdata.com/lifecheck/h5/v2/init</code></p>
<h4>业务参数</h4>
<table>
<thead>
<tr>
<th>名称</th>
<th>类型</th>
<th>必须</th>
<th><div style="width:420px;">说明</div></th>
</tr>
</thead>
<tbody>
<tr>
<td>returnUrl</td>
<td>String</td>
<td>是</td>
<td>检测完成后页面自动重定向地址，长度不超过128字符，接入者可以在该地址的页面中去获取检测结果。<br>-如果是在小程序中使用，传入小程序内部地址。例如：/pages/customer/index <br>-如果是h5页面使用，传入以http或https开头的网址<br>-如果是原生app使用,传入app:方法名() 例如：app:notifyResult()</td>
</tr>
<tr>
<td>colors</td>
<td>String</td>
<td>否</td>
<td>闪光颜色，多个按 , 分割。默认不开启。<br>闪光活体通过亮色和暗色交替闪烁进行活体判断。数组颜色指定两个或多个颜色时，须同时包含亮色和暗色，系统将随机在提交的颜色中选取亮色光和暗色光交替闪烁。颜色数组不区分顺序，从系统提供的颜色中配置。<br>推荐使用亮色：#FFFFFF和暗色：#000000。<br>系统提供14种闪光颜色：<br>亮色：#FFFFFF，#FFD9E3，#D8D6FF，#CFF9FF，#FFCEFD，#D8FFCD，#FFF4CB。<br>暗色：#000000，#3B3C04，#183C03，#063C28，#063C3A，#060D3C，#3C0636</td>
</tr>
<tr>
<td>actions</td>
<td>String</td>
<td>否</td>
<td>动作，多个按 , 分割，并区分顺序。默认不开启，指定一个或多个动作时开启。<br>动作参数如下：<br>LookFront：直视摄像头<br>LookLeft：向左转头<br>LookRight：向右转头<br>LookUp：抬头<br>LookDown：低头<br>OpenMouth：张嘴<br>BlinkEye：眨眼<br>ShakeHead：摇头<br>NodHead：点头</td>
</tr>
</tbody>
</table>
<p>> 闪光和动作（LookFront直视除外）同时使用时，必须在actions参数中设置LookFront直视动作，在直视摄像头时启动。单独使用闪光活体时，可不设置动作活体参数。
> colors 有值时，直视动作是必须的。colors 没值时，活体动作可以自定义除直视动作之外的其他动作参数。</p>
<p>公共请求参数请参阅：<a href="#公共请求参数">公共请求参数</a></p>
<h4>成功返回样例</h4>
<pre><code class="language-json">{
&quot;code&quot;: 200,
&quot;msg&quot;: &quot;成功&quot;,
&quot;taskNo&quot;: &quot;043439882226367117195632&quot;,
&quot;charge&quot;: true,
&quot;data&quot;: {
&quot;token&quot;: &quot;xxx&quot; // 本次检测的token，有效期为10分钟，用于后续获取结果
}
}</code></pre>
<h4>code返回码说明</h4>
<p>本接口没有特殊返回码，请参阅：<a href="#公共code返回码说明">公共code返回码说明</a></p>
<hr />
<h3>活体检测h5页面</h3>
<h4>页面地址</h4>
<p><code>https://api-h5.jumdata.com/lifecheck/v2/check/index?token=${token}</code></p>
<p>调用初始化接口获取token之后，接入者页面带上token，跳转至该页面进行检测</p>
<h4>returnUrl</h4>
<p>检测完成之后，跳转至初始化时returnUrl指定的地址, 并返回参数</p>
<p><code>returnUrl?token=${token}&amp;success=${success}</code></p>
<p>参数说明</p>
<table>
<thead>
<tr>
<th>名称</th>
<th><div style="width:420px;">说明</div></th>
</tr>
</thead>
<tbody>
<tr>
<td>token</td>
<td>初始化接口返回的token</td>
</tr>
<tr>
<td>success</td>
<td>true - 检测通过, false - 检测未通过</td>
</tr>
</tbody>
</table>
<hr />
<h3>获取活体检测结果</h3>
<h4>请求地址</h4>
<p><code>https://api.jumdata.com/lifecheck/h5/v2/result</code></p>
<h4>业务参数</h4>
<table>
<thead>
<tr>
<th>名称</th>
<th>类型</th>
<th>必须</th>
<th><div style="width:420px;">说明</div></th>
</tr>
</thead>
<tbody>
<tr>
<td>token</td>
<td>String</td>
<td>是</td>
<td>初始化接口返回的token</td>
</tr>
<tr>
<td>returnSceneImage</td>
<td>String</td>
<td>否</td>
<td>是否返回原始图片，true、false，默认false</td>
</tr>
</tbody>
</table>
<p>公共请求参数请参阅：<a href="#公共请求参数">公共请求参数</a></p>
<h4>检测通过返回样例</h4>
<pre><code class="language-json">{
&quot;code&quot;: 200,
&quot;msg&quot;: &quot;活体检测通过&quot;,
&quot;taskNo&quot;: &quot;043439882226367117195632&quot;,
&quot;data&quot;: {
&quot;faceImageUrl&quot;: &quot;xxx&quot;, // 检测通过时返回人像照片地址
&quot;faceImageBase64&quot;: &quot;xxx&quot;, // 检测通过时返回人像照片Base64
&quot;sceneImageUrl&quot;: &quot;xxx&quot; // 原始图片地址，returnSceneImage=true时返回
&quot;sceneImageBase64&quot;: &quot;xxx&quot; // 原始图片Base64，returnSceneImage=true时返回
}
}</code></pre>
<h4>检测不通过返回样例</h4>
<pre><code class="language-json">{
&quot;code&quot;: 202,
&quot;msg&quot;: &quot;活体检测未通过&quot;,
&quot;taskNo&quot;: &quot;043439882226367117195632&quot;,
}</code></pre>
<h4>未查询到检测结果返回样例</h4>
<pre><code class="language-json">{
&quot;code&quot;: 201,
&quot;msg&quot;: &quot;未查询到检测结果&quot;,
&quot;taskNo&quot;: &quot;043439882226367117195632&quot;,
}</code></pre>
<h4>检测失败样例</h4>
<pre><code class="language-json">{
&quot;code&quot;: 203,
&quot;msg&quot;: &quot;检测失败&quot;,
&quot;taskNo&quot;: &quot;043439882226367117195632&quot;,
}</code></pre>
<h4>code返回码说明</h4>
<table>
<thead>
<tr>
<th>code</th>
<th><div style="width:120px;">说明</div></th>
<th><div style="width:420px;">原因说明</div></th>
</tr>
</thead>
<tbody>
<tr>
<td>200</td>
<td>活体检测通过</td>
<td></td>
</tr>
<tr>
<td>202</td>
<td>活体检测未通过</td>
<td>1.检测到摄像头视频劫持攻击<br>2.在视频中用户做出的动作不符合给定的序列<br>3.人脸未通过活体判断<br></td>
</tr>
<tr>
<td>201</td>
<td>未查询到检测结果</td>
<td></td>
</tr>
<tr>
<td>203</td>
<td>活体检测失败</td>
<td>1.浏览器缺少进行活体采集的特性或出现软硬件故障<br>2.用户拒绝进行活体采集，例如摄像头权限被禁止<br>3.动作参数错误 <br>4.其它错误</td>
</tr>
<tr>
<td>301</td>
<td>token已过期</td>
<td>指初始化之后未在10分钟内获取结果</td>
</tr>
</tbody>
</table>
<p>公共返回码请参阅：<a href="#公共code返回码说明">公共code返回码说明</a></p>
<h3>前端(VUE)接入参考</h3>
<h4>开始检测页面</h4>
<pre><code class="language-javascript"> // 接入者服务端先提供获取token接口，详见获取初始化接口
// 然后此处调用该接口获取活体检测token
// myLifecheckService 指接入者自行封装的活体检测服务端
myLifecheckService.getToken().then(response=&gt; {
let token = response.token
// 获取token之后跳转至聚美智数活体检测H5页面
location.href = 'https://api-h5.jumdata.com/lifecheck/v2/check/index?token=' + token
})</code></pre>
<h4>returnUrl页面</h4>
<pre><code class="language-javascript"> let query = this.$route.query
let token = query.token
let passed = query.success
if(passed) {
// 检测通过
} else {
// 检测未通过
}
// passed只表示简单的通过和未通过，如需更详细信息，可自行在接入者服务端封装获取结果接口，详见获取活体检测结果
myLifecheckService.getResult(token).then(response=&gt; {
})</code></pre>
<h3>计费说明</h3>
<ul>
<li>调用初始化接口时预扣费用，当检测通过或不通过时实扣费用，其余情况系统会自动退回费用</li>
<li>查询结果接口不计费</li>
</ul>