帮你快速理解、总结文档立即下载

启动 H5 人脸核身

最近更新时间:2026-11-13 15:00:59
本文档已由 AI 辅助审校
我的收藏

前置条件

合作方如果使用 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)



生成签名

前置条件

请合作方确保 NONCE ticket 已经正常获取,获取方式见 NONCE ticket 获取。合作方根据本次人脸核身的如下参数生成签名,需要签名的参数信息如下:
说明
参与签名的数据需要和使用该签名的接口中的请求参数保持一致。
参数
说明
来源
appId
业务流程唯一标识
参考 获取 WBappid 指引在人脸核身控制台内申请
orderNo
订单号,本次人脸核身合作伙伴上传的订单号,字母/数字组成的字符串,唯一标识
合作方自行分配
userId
用户 ID ,用户的唯一标识(不要带有特殊字符)
合作方自行分配(与接口中使用的 userId 保持一致)
version
参数值为:1.0.0
-
faceId
getAdvFaceId 接口返回的唯一标识
-
ticket
合作伙伴服务端获取的 ticket,注意是 NONCE 类型
获取方式见 NONCE ticket 获取(所用的 userid 参数值需要和接口里面的 userId 值保持一致)

基本步骤

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
参考 获取 WBappid 指引在人脸核身控制台内申请
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