前置条件
合作方如果使用 App 内调起 H5 人脸核身,需要 App 平台的 webkit/blink 等组件支持调用摄像头录视频,方可正常使用人脸核身功能。
说明
1. App 内调用 H5 人脸核身或者短信链接调用 H5 人脸核身等场景,若当前设备无法正常调用摄像头进行视频录制,前端将返回特定的错误码(如下)告知合作方,合作方拿到错误码后可选择用备用方案核身处理。
2. 在 App、微信公众号、浏览器中调用 H5实时检测人脸核身,需要用户允许使用摄像头权限(授权操作形式包括弹窗、动作菜单、应用设置等,具体形式视手机型号而异)。如用户误操作导致拒绝授权,需要退出人脸核身并重新进入和允许授权。部分浏览器会缓存用户之前的授权操作,故如果退出人脸核身并重新进入时仍然出现无摄像头权限的情况,可以尝试清除浏览器缓存。
返回码 | 返回信息 | 处理措施 |
3001 | 该浏览器不支持视频录制 | 请使用其它验证方案 |
3002 | 登录态异常,cookie 参数缺失 | 重新进入 |
3003 | 人脸核身中途中断 | 重新进入 |
3004 | 无摄像头权限 | 重新进入并授权摄像头 |
3005 | 该浏览器不支持实时检测模式 | 请使用其它浏览器 |
300101 | 报文包体问题 | 重新进入 |
摄像头授权操作示例:
形式1:弹窗(popup)

形式2:动作菜单(action sheet)

形式3 :应用设置(setting)




生成签名
前置条件
说明
参与签名的数据需要和使用该签名的接口中的请求参数保持一致。
参数 | 说明 | 来源 |
appId | 业务流程唯一标识 | |
orderNo | 订单号,本次人脸核身合作伙伴上传的订单号,字母/数字组成的字符串,唯一标识 | 合作方自行分配 |
userId | 用户 ID ,用户的唯一标识(不要带有特殊字符) | 合作方自行分配(与接口中使用的 userId 保持一致) |
version | 参数值为:1.0.0 | - |
faceId | getAdvFaceId 接口返回的唯一标识 | - |
ticket | 合作伙伴服务端获取的 ticket,注意是 NONCE 类型 |
基本步骤
1. 将 appId、userId、orderNo、version、faceId 连同 ticket 共 6 个参数的值进行字典序排序。
2. 将排序后的所有参数字符串拼接成一个字符串。
3. 将排序后的字符串进行 SHA1 编码,编码后的40位字符串作为签名(sign)。签名算法可参考 签名算法说明。
参考示例
请求参数:
参数名 | 参数值 |
appId | appId001 |
userId | userID19959248596551 |
version | 1.0.0 |
faceId | bwiwe1457895464 |
orderNo | aabc1457895464 |
ticket | zxc9Qfxlti9iTVgHAjwvJdAZKN3nMuUhrsPdPlPVKlcyS50N6tlLnfuFBPIucaMS |
字典排序后的参数为:
[1.0.0, aabc1457895464, appId001, bwiwe1457895464, userID19959248596551, zxc9Qfxlti9iTVgHAjwvJdAZKN3nMuUhrsPdPlPVKlcyS50N6tlLnfuFBPIucaMS]
拼接后的字符串为:
1.0.0aabc1457895464appId001bwiwe1457895464userID19959248596551zxc9Qfxlti9iTVgHAjwvJdAZKN3nMuUhrsPdPlPVKlcyS50N6tlLnfuFBPIucaMS
计算 SHA1 得到签名:
DE10A4DC8D52E2A2390C7098E89E3B6386491455
注意:
该字串就是最终生成的签名(40位),不区分大小写。
启动 H5 人脸核身
合作方上传 faceId 以及 sign,后台校验 sign 通过之后重定向到 H5 人脸核身。
注意
1. optimalDomain 使用合作方后台上送身份信息 接口返回的 optimalDomain 域名,如果 optimalDomain 字段返回为空或者取不到,默认使用域名 kyc1.qcloud.com。
2. 该跳转 url 不能直接暴露在前端 html 页面的<a>标签中。某些浏览器会预加载<a>标签中的 url,导致用户点击访问该 url 时,因 url 已经被预加载访问过,于是签名失效,页面报错“签名不合法”。
3. 合作方如果使用 iframe 框架,需要给 iframe 开启相机权限 allow="camera;",并且内外层都需要使用 https 协议,方可正常使用实时检测人脸核身功能。
示例:<iframe allow="camera *;autoplay *;"></iframe>
请求 URL:
https://{optimalDomain}/s/web/h5
optimalDomain 使用 合作方后台上传身份信息 接口返回的 optimalDomain 域名,如果 optimalDomain 字段返回为空或者取不到,默认使用域名
kyc1.qcloud.com。该跳转 URL 不能直接暴露在前端 HTML 页面的
<a>标签中。某些浏览器会预加载<a>标签中的 url,导致用户点击访问该 url 时,因 url 已经被预加载访问过,于是签名失效,页面报错“签名不合法”。请求方法:GET
请求参数:
参数 | 说明 | 类型 | 长度 | 是否必填 |
appId | String | 8 | 是 | |
version | 接口版本号,默认参数值1.0.0 | String | 20 | 是 |
orderNo | 订单号,由合作方上传,字母/数字组成的字符串,每次唯一,此信息为本次人脸核身上传的信息,不能超过32位 | String | 32 | 是 |
faceId | getAdvFaceId 接口返回的唯一标识 | String | 32 | 是 |
userId | 用户 ID ,用户的唯一标识(不要带有特殊字符) | String | - | 是 |
sign | 签名:使用上面生成的签名 | String | 40 | 是 |
请求示例:
https://kyc1.qcloud.com/s/web/h5?appId=appId001&version=1.0.0&orderNo=161709188560917432576916585&faceId=tx04f10695c3651ce155fea7070b74c9&userId=23333333333333&sign=5DD4184F4FB26B7B9F6DC3D7D2AB3319E5F7415F