启动 H5 人脸核身

最近更新时间：2023-10-20 14:31:01

我的收藏

本页目录：

前置条件
合作方如果使用 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 值保持一致）
nonce
随机数：32位随机串（字母 + 数字组成的随机数）
合作方自行生成（与接口中的随机数保持一致）
基本步骤
1. 生成一个32位的随机字符串（字母和数字）nonce（接口请求时也要用到）。
2. 将 appId、userId、orderNo、version、faceId 连同 ticket、nonce 共7个参数的值进行字典序排序。
3. 将排序后的所有参数字符串拼接成一个字符串。
4. 将排序后的字符串进行 SHA1 编码，编码后的40位字符串作为签名（sign）。签名算法可参考 签名算法说明 。
参考示例
请求参数：
参数名
参数值
appId
appId001
userId
userID19959248596551
nonce
kHoSxvLZGxSoFsjxlbzEoUzh5PAnTU7T
version
1.0.0
faceId
bwiwe1457895464
orderNo
aabc1457895464
ticket
zxc9Qfxlti9iTVgHAjwvJdAZKN3nMuUhrsPdPlPVKlcyS50N6tlLnfuFBPIucaMS
字典排序后的参数为：
[1.0.0, aabc1457895464, appId001, bwiwe1457895464, kHoSxvLZGxSoFsjxlbzEoUzh5PAnTU7T, userID19959248596551, zxc9Qfxlti9iTVgHAjwvJdAZKN3nMuUhrsPdPlPVKlcyS50N6tlLnfuFBPIucaMS]
拼接后的字符串为：
1.0.0aabc1457895464appId001bwiwe1457895464kHoSxvLZGxSoFsjxlbzEoUzh5PAnTU7TuserID19959248596551zxc9Qfxlti9iTVgHAjwvJdAZKN3nMuUhrsPdPlPVKlcyS50N6tlLnfuFBPIucaMS
计算 SHA1 得到签名：
4E9DFABF938BF37BDB7A7DC25CCA1233D12D986B  该字串就是最终生成的签名（40位），不区分大小写。
启动 H5 人脸核身
合作方上传 faceId 以及 sign，后台校验 sign 通过之后重定向到 H5 人脸核身。
注意
 为了保证服务的高可用，全面消除单点风险，我们启用了多域名服务。启动 H5 人脸核身需要使用 合作方后台上传身份信息 接口返回内容中 optimalDomain 字段的域名。
请求 URL：
https://{optimalDomain}/api/web/login
optimalDomain 使用 合作方后台上传身份信息 接口返回的 optimalDomain 域名，如果 optimalDomain 字段返回为空或者取不到，默认使用域名 kyc.qcloud.com。
该跳转 url 不能直接暴露在前端 html 页面的<a>标签中。某些浏览器会预加载<a>标签中的 url，导致用户点击访问该 url 时，因 url 已经被预加载访问过，于是签名失效，页面报错“签名不合法”。
请求方法：GET
请求参数：
参数
说明
类型
长度
是否必填
appId
参考 获取 WBappid 指引在人脸核身控制台内申请
String
8
是
version
接口版本号，默认参数值1.0.0
String
20
是
nonce
随机数：32位随机串（字母 + 数字组成的随机数）
String
32
是
orderNo
订单号，由合作方上传，字母/数字组成的字符串,每次唯一，此信息为本次人脸核身上传的信息，不能超过32位
String
32
是
faceId
getAdvFaceId接口返回的唯一标识
String
32
是
url
H5 人脸核身完成后回调的第三方 URL，需要第三方提供完整 URL 且做 URL Encode。完整 URL Encode 示例：
原 URL：https://cloud.tencent.com
Encode 后：https%3a%2f%2fcloud.tencent.com
String
-
是
resultType
是否显示结果页面，参数值为“1”时直接跳转到 url 回调地址，null 或其他值跳转提供的结果页面
String
-
否，非必填
userId
用户 ID ，用户的唯一标识（不要带有特殊字符）
String
-
是
sign
签名：使用上面生成的签名
String
40
是
from
browser：表示在浏览器启动刷脸；App：表示在 App 里启动刷脸，默认值为 App
String
-
是
redirectType
跳转模式，参数值为“1”时，刷脸页面使用 replace 方式跳转，不在浏览器 history 中留下记录；不传或其他值则正常跳转
String
-
否，非必填
请求示例：
https:// kyc.qcloud.com/api/web/login?appId=appId001
&version=1.0.0
&nonce=4bu6a5nv9t678m2t9je5819q46y9hf93
&orderNo=161709188560917432576916585
&faceId=wb04f10695c3651ce155fea7070b74c9
&url=https%3a%2f%2fcloud.tencent.com
&from=browser
&userId=23333333333333
&sign=5DD4184F4FB26B7B9F6DC3D7D2AB3319E5F7415F
&redirectType=1
﻿

上一篇: 合作方后台上传身份信息下一篇: H5 人脸核身结果跳转

返回码	返回信息	处理措施
3001	该浏览器不支持视频录制	请使用其它验证方案
3002	登录态异常，cookie 参数缺失	重新进入
3003	人脸核身中途中断	重新进入
3004	无摄像头权限	重新进入并授权摄像头
3005	该浏览器不支持实时检测模式	请使用其它浏览器
300101	报文包体问题	重新进入

参数	说明	来源
appId	业务流程唯一标识	参考获取 WBappid 指引在人脸核身控制台内申请
orderNo	订单号，本次人脸核身合作伙伴上传的订单号，字母/数字组成的字符串，唯一标识	合作方自行分配
userId	用户 ID ，用户的唯一标识（不要带有特殊字符）	合作方自行分配（与接口中使用的 userId 保持一致）
version	参数值为：1.0.0	-
faceId	getAdvFaceId接口返回的唯一标识	-
ticket	合作伙伴服务端获取的 ticket，注意是 NONCE 类型	获取方式见 NONCE ticket 获取（所用的 userid 参数值需要和接口里面的 userId 值保持一致）
nonce	随机数：32位随机串（字母 + 数字组成的随机数）	合作方自行生成（与接口中的随机数保持一致）

参数名	参数值
appId	appId001
userId	userID19959248596551
nonce	kHoSxvLZGxSoFsjxlbzEoUzh5PAnTU7T
version	1.0.0
faceId	bwiwe1457895464
orderNo	aabc1457895464
ticket	zxc9Qfxlti9iTVgHAjwvJdAZKN3nMuUhrsPdPlPVKlcyS50N6tlLnfuFBPIucaMS

参数	说明	类型	长度	是否必填
appId	参考获取 WBappid 指引在人脸核身控制台内申请	String	8	是
version	接口版本号，默认参数值1.0.0	String	20	是
nonce	随机数：32位随机串（字母 + 数字组成的随机数）	String	32	是
orderNo	订单号，由合作方上传，字母/数字组成的字符串,每次唯一，此信息为本次人脸核身上传的信息，不能超过32位	String	32	是
faceId	getAdvFaceId接口返回的唯一标识	String	32	是
url	H5 人脸核身完成后回调的第三方 URL，需要第三方提供完整 URL 且做 URL Encode。完整 URL Encode 示例：原 URL：`https://cloud.tencent.com` Encode 后：`https%3a%2f%2fcloud.tencent.com`	String	-	是
resultType	是否显示结果页面，参数值为“1”时直接跳转到 url 回调地址，null 或其他值跳转提供的结果页面	String	-	否，非必填
userId	用户 ID ，用户的唯一标识（不要带有特殊字符）	String	-	是
sign	签名：使用上面生成的签名	String	40	是
from	browser：表示在浏览器启动刷脸；App：表示在 App 里启动刷脸，默认值为 App	String	-	是
redirectType	跳转模式，参数值为“1”时，刷脸页面使用 replace 方式跳转，不在浏览器 history 中留下记录；不传或其他值则正常跳转	String	-	否，非必填