H5接入文档--身份认证-火山引擎

文档中心

立即注册

导航

H5接入文档

最近更新时间：2024.11.01 15:14:14首次发布时间：2024.01.26 16:33:21

效果展示

H5接入说明

如要在小程序集成H5，请参考小程序集成H5说明
如要在APP中集成H5，请参考APP集成H5说明

1. 请求域名

https://h5-v2.kych5.com

2. 拼接URL

URL示例：https://h5-v2.kych5.com?accessKeyId=xxx&secretAccessKey=xxx&sessionToken=xxx&configId=xxx&bytedToken=xxx&lng=xxx

accessKeyId、secretAccessKey、sessionToken：临时密钥，必填字段，用于服务端接口鉴权，具体的获取方式参考获取临时密钥（STS）。
configId：固定参数套餐ID，必填字段，有效期默认为15min，具体的获取方式参考下方【配置参数说明】。
bytedToken：可选字段，当业务场景为直接进入活体识别时，需要调用服务端接口CertH5Token获取。
lng：可选字段，表示页面语言。目前支持简体(zh)、繁体(zh-Hant)、英文(en)。

3. 配置参数说明

提供可选的配置参数，适配多样化的客户需求和业务场景，调用服务端接口（参考CertH5ConfigInit ）生成configId并拼接到URL参数上。

参数分类	参数	类型	功能描述	是否必填	取值	说明
页面配置参数 h5_config	type	string	具体的业务接入场景，当前主要有4种场景。	选填，默认0	0	正常流程：OCR上传图片识别 + 输入身份证号和姓名 + 人脸认证。
					1	跳过OCR上传图片识别，直接进入输入身份证号和姓名 + 人脸认证。
					2	直接进入OCR上传图片识别 + 人脸认证，跳过输入身份证号和姓名。
					3	OCR上传图片识别、输入身份证号和姓名这两个步骤都要跳过，直接进行人脸认证流程。【注意】适用于业务已存有用户资料的场景。需要业务侧调用服务端接口（参考CertH5Token ），获取bytedToken值后拼接到URL参数上。
	theme_color	string	自定义主题色	选填	--	默认颜色 rgba(56, 123, 255, 1)
	show_guide	string	是否展示认证首页	选填，默认1	0	不展示
	show_guide	string	是否展示认证首页	选填，默认1	1	展示
	show_result	string	是否展示认证结果页	选填，默认1	0	不展示，直接跳转到redirectUrl
	show_result	string	是否展示认证结果页	选填，默认1	1	展示认证成功和失败页
	protocol_name	string	自定义协议名称	选填	--	需要保证showGuide=1时才会显示协议名称
	protocol_link	string	自定义协议链接	选填	--	需要保证showGuide=1时才会显示协议链接
	enable_record	string	优先使用更高效便捷的实时刷脸方案，当设备不支持该方案时的降级处理策略。	选填，默认1	0	当设备不支持实时刷脸能力时，则认定本次认证失败
	enable_record	string	优先使用更高效便捷的实时刷脸方案，当设备不支持该方案时的降级处理策略。	选填，默认1	1	当设备不支持实时刷脸能力时，启用备用认证方案 - 视频录制，该方案能更好的兼容低端设备。
	redirect_url	string	认证完成（成功or失败）后，会将部分参数拼接到redirectUrl上并执行跳转。	必填	--	建议使用https开头的URL地址，目前也支持小程序环境下的跳转。微信小程序的URL格式：`wxmini:/pages/path1/path2?query1=xx` 支付宝小程序的URL格式：`apmini:/pages/path1/path2?query1=xx`
认证动作配置参数 liveness_config	ref_source	string	在type=0或1或2时，该字段必须设置为1，表示有源认证。在type=3时，可以设置为0或者1，用于区分有源or无源认证	必填	0	无源（根据一张基准图进行认证）
	ref_source	string		必填	1	有源（根据身份证号和姓名进行认证）
	liveness_type	string	端上活体类型	必填	motion	动作活体
	liveness_type	string	端上活体类型	必填	reflection	炫彩活体
	liveness_timeout	number	端上活体超时时间	选填，默认10	--	可选范围： [5, 60]
	motion_list	string[]	可被下发的动作列表	选填	--	可选动作：`0`：眨眼`1`：张嘴`2`：点头`3`：摇头
	fixed_motion_list	string[]	固定一定需要下发的动作列表	选填	--	取值同motion_list
	motion_count	number	选中的动作个数	选填，默认2	--	可选范围：[1, 4]
	max_liveness_trial	number	端上活体最大尝试次数	选填，默认10	--	可选范围：[1, 100]
自定义TOS配置参数 tos_config	sts_ak	string	TOS使用的STS AK	选填	--	如果需要将认证数据存储到自定义TOS时，必填
	sts_sk	string	TOS使用的STS SK	选填	--	如果需要将认证数据存储到自定义TOS时，必填
	sts_token	string	TOS使用的STS Token	选填	--	如果需要将认证数据存储到自定义TOS时，必填
	bucket	string	TOS使用的Bucket	选填	--	如果需要将认证数据存储到自定义TOS时，必填
	endpoint	string	TOS使用的Endpoint	选填	--	如果需要将认证数据存储到自定义TOS时，必填
	region	string	TOS使用的Region	选填	--	如果需要将认证数据存储到自定义TOS时，必填

ConfigID配置示例

下面会列出几种常见接入场景的配置数据格式，便于业务侧快速接入。
示例1： 完整的默认参数模版（推荐）。

const postData = {
  h5_config: {
    type: '0',
    theme_color: 'rgba(56, 123, 255, 1)',
    show_guide: '1',
    show_result: '1',
    protocol_name: '',
    protocol_link: '',
    enable_record: '1',
    redirect_url: 'https://xxx.com',
  },
  liveness_config: {
    ref_source: '1',
    liveness_type: 'motion',
    liveness_timeout: 10,
    motion_list: ['0', '1', '2', '3'],
    fixed_motion_list: [],
    motion_count: 2,
    max_liveness_trial: 10,
  },
  ...
};

示例2： 业务侧已存有用户资料（身份照片或者身份信息），不需要使用身份认证服务提供的证件照片上传功能和身份信息输入功能。

const postData = {
  h5_config: {
    type: '3',
    // 其余参数根据实际情况配置，注意必填参数
    ...
  },
  liveness_config: {
    // 1. 如果业务侧使用一张基准图发起认证，则配置为0
    ref_source: '0',
    // 2. 如果业务侧使用身份证号和姓名发起认证，则配置为1
    ref_source: '1',
    // 其余参数根据实际情况配置，注意必填参数
    ...
  },
  ...
};

示例3： 业务侧需要将认证数据存储到自定义TOS

const postData = {
  h5_config: {
    // 其余参数根据实际情况配置，注意必填参数
    ...
  },
  liveness_config: {
    // 其余参数根据实际情况配置，注意必填参数
    ...
  },
  // Tos参数的获取，参考火山引擎文档：https://www.volcengine.com/product/TOS
  tos_config: {
    sts_ak: '',
    sts_sk: '',
    sts_token: '',
    bucket: '',
    endpoint: '',
    region: '',
  },
  ...
};

4. 认证结束

当结束认证后，身份认证H5会在redirect_url地址后面拼接相关的参数，业务侧可解析参数获取认证结果。

/** 拼接示例 **/
${redirect_url}?resultCode=xxx&algorithmBaseRespCode=xxx&reqMeasureInfoValue=xxx&bytedToken=xxx

认证返回参数说明

参数	类型	功能描述
resultCode	string	通用错误码。若值为10000，则表示认证成功，否则认证失败。错误类型主要有：客户端错误、算法端错误、服务端错误
algorithmBaseRespCode	string	服务端子错误码。建议业务侧在resultCode为服务端错误码时，再检查该字段对应的错误类型。
reqMeasureInfoValue	string	是否计费，取值为0或1 0为不计费，1为计费
bytedToken	string	查询query接口需要的参数

错误码

客户端错误码

resultCode	说明
40001	当前设备不支持WebRTC
40002	摄像头权限获取失败
40003	RTC初始化内部错误
40004	设备录制视频异常
40005	TOS上传异常
40006	未知错误
40007	本地图片处理异常
40008	未检测到设备摄像头硬件
40009	WebSocket连接异常
40010	当前设备不支持WebSocket
40011	WebSocket页面初始化内部错误

算法端错误码

resultCode	说明
41000	检测尚未完成
41002	超时未检测到第一张有效人脸
41003	单个动作超时
41006	做错动作，可能是视频攻击
41007	静默活体检测失败
41008	过程中人脸不一致
41009	过程中图片质量不合格

服务端错误码

resultCode	说明
50200	参数错误
50201	缺少参数
50204	参数类型错误/参数缺失
50205	图像尺寸超过限制。输入为图片时可能返回此错误。
50206	请求参数中没有获取到图像。输入为图片时可能返回此错误。
50207	图像解码错误。输入为图片时可能返回此错误。
50209	请求参数中没有获取到视频。输入为视频时可能返回此错误。
50210	视频解码错误。输入为视频时可能返回此错误。
50211	视频尺寸超过限制。输入为视频时可能返回此错误。
50213	请求Body过大，超过10MB限制。
50214	输入视频时长过大
50215	请查看认证子错误码了解具体含义。认证子错误码说明见下方。
60102	算法服务需要输入人脸图，但未检测到
50400	权限校验失败，没有接口权限/时间戳参数不正确/签名字段错误。
50402	访问的接口不存在。
50429	超过调用QPS限制。
50500	服务器内部错误。
50501	服务器内部RPC错误。
70000	网关鉴权失败。可能是临时密钥STS过期。

服务端子错误码

algorithmBaseRespCode	说明	是否计费
0	认证一致	是
100000	服务内部错误
100001	数据源内部错误
201201	缺少输入参数或输入参数为空
201202	输入参数不合法
201301	输入图片为空
201302	输入图片解码失败
201304	输入图片无法处理
201403	身份证认证次数超出当日上限
201404	命中频控黑名单
203101	输入图片未检测到人脸
210101	输入认证字段不合格（空、不合法等）
210102	输入认证字段查询不到结果
210103	输入认证字段触发源头限流
210104	输入认证字段不匹配	是
210201	身份证号为空
210202	身份证号无效或不符合规范
210203	姓名为空
210204	姓名不符合规则
210205	身份证查询无结果
210206	姓名不匹配	是
210207	认证不一致，姓名与身份证号不匹配
210301	人脸图格式不支持	是
210302	人脸图质量不合格/已损坏	是
210303	人脸图大小过小	是
210304	人脸图为空
210305	人脸图中未检测到人脸
210306	人脸图中存在多个人脸
210307	人脸图特征提取失败
210308	数据源库中的底图质量不合格	是
210309	数据源库中无该身份信息对应的底图	是
210310	人脸图尺寸过大
210311	人脸图不匹配	是
210312	请按动作重做动作
210313	认证不一致，疑似本人	是
210314	认证不一致，待对比图像建模失败	是
210701	人脸图质量分数过低
210702	人脸图活体分数过低
210703	人脸图比对分数过低
210704	传入的token参数有误或已过期
210705	动作活体重试次数超过上限
210706	基准图质量过低
210707	基准图不合格
210708	基准图没有人脸
210709	获取基准图失败
210710	获取人脸图失败
210801	SDKData为空
210802	SDKData版本异常
210803	SDKData版本拦截
210804	SDKData数据有误
210805	SDKData配置与设置的不相符
210806	SDK动作活体未通过
210807	获取SDKData失败

常见问题

1. 设备兼容情况

身份认证H5的动作活体功能使用了WebRTC相关能力，如果不支持则降级到录制视频的方式进行认证。
WebRTC 介绍

Android
通过浏览器内核和版本号来确认对WebRTC的支持。
IOS
WKWebView从iOS 14.3 (Beta)开始提供对WebRTC的支持。
Safari从iOS 11开始支持WebRTC。

2. 如果出现无法打开摄像头、无法录制、无法完成认证等情况，应该如何处理？

由于某些设备或者浏览器环境的兼容性，导致无法完成认证流程，但是不清楚具体哪里出问题了，所以将整个认证流程中涉及到的一些浏览器标准Web API调用，单独剥离出来，供用户手动测试该设备是否正常。
方式一： 访问地址： https://h5-v2.kych5.com/checkapi
方式二：可以通过双击页面底部文字进入检测页面：