https://h5-v2.kych5.com
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)。提供可选的配置参数,适配多样化的客户需求和业务场景,调用服务端接口(参考CertH5ConfigInit )生成configId
并拼接到URL参数上。
参数分类 | 参数 | 类型 | 功能描述 | 是否必填 | 取值 | 说明 |
---|---|---|---|---|---|---|
页面配置参数 | type | string | 具体的业务接入场景,当前主要有4种场景。 | 选填,默认0 | 0 | 正常流程:OCR上传图片识别 + 输入身份证号和姓名 + 人脸认证。 |
1 | 跳过OCR上传图片识别,直接进入输入身份证号和姓名 + 人脸认证。 | |||||
2 | 直接进入OCR上传图片识别 + 人脸认证,跳过输入身份证号和姓名。 | |||||
3 | OCR上传图片识别、输入身份证号和姓名 这两个步骤都要跳过,直接进行人脸认证流程。 | |||||
theme_color | string | 自定义主题色 | 选填 | -- | 默认颜色 rgba(56, 123, 255, 1) | |
show_guide | string | 是否展示认证首页 | 选填,默认1 | 0 | 不展示 | |
1 | 展示 | |||||
show_result | string | 是否展示认证结果页 | 选填,默认1 | 0 | 不展示,直接跳转到redirectUrl | |
1 | 展示认证成功和失败页 | |||||
protocol_name | string | 自定义协议名称 | 选填 | -- | 需要保证showGuide=1时才会显示协议名称 | |
protocol_link | string | 自定义协议链接 | 选填 | -- | 需要保证showGuide=1时才会显示协议链接 | |
enable_record | string | 优先使用更高效便捷的实时刷脸方案,当设备不支持该方案时的降级处理策略。 | 选填,默认1 | 0 | 当设备不支持实时刷脸能力时,则认定本次认证失败 | |
1 | 当设备不支持实时刷脸能力时,启用备用认证方案 - 视频录制,该方案能更好的兼容低端设备。 | |||||
redirect_url | string | 认证完成(成功or失败)后,会将部分参数拼接到redirectUrl上并执行跳转。 | 必填 | -- | 建议使用https开头的URL地址,目前也支持小程序环境下的跳转。 | |
认证动作配置参数 | ref_source | string | 在type=0或1或2时,该字段必须设置为1,表示有源认证。 | 必填 | 0 | 无源(根据一张基准图进行认证) |
1 | 有源(根据身份证号和姓名进行认证) | |||||
liveness_type | string | 端上活体类型 | 必填 | motion | 动作活体 | |
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配置参数 | 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时,必填 |
下面会列出几种常见接入场景的配置数据格式,便于业务侧快速接入。
示例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: '', }, ... };
当结束认证后,身份认证H5会在redirect_url
地址后面拼接相关的参数,业务侧可解析参数获取认证结果。
/** 拼接示例 **/ ${redirect_url}?resultCode=xxx&algorithmBaseRespCode=xxx&reqMeasureInfoValue=xxx&bytedToken=xxx
认证返回参数说明
参数 | 类型 | 功能描述 |
---|---|---|
resultCode | string | 通用错误码。若值为10000,则表示认证成功,否则认证失败。 |
algorithmBaseRespCode | string | 服务端子错误码。 |
reqMeasureInfoValue | string | 是否计费,取值为0或1 |
bytedToken | string | 查询query接口需要的参数 |
resultCode | 说明 |
---|---|
40001 | 当前设备不支持WebRTC |
40002 | 摄像头权限获取失败 |
40003 | RTC初始化内部错误 |
40004 | 设备录制视频异常 |
40005 | TOS上传异常 |
40006 | 未知错误 |
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失败 |
身份认证H5的动作活体功能使用了WebRTC相关能力,如果不支持则降级到录制视频的方式进行认证。
WebRTC 介绍
Android
通过浏览器内核和版本号来确认对WebRTC的支持。
IOS
WKWebView从iOS 14.3 (Beta)开始提供对WebRTC的支持。
Safari从iOS 11开始支持WebRTC。
由于某些设备或者浏览器环境的兼容性,导致无法完成认证流程,但是不清楚具体哪里出问题了,所以将整个认证流程中涉及到的一些浏览器标准Web API调用,单独剥离出来,供用户手动测试该设备是否正常。
方式一: 访问地址: https://h5-v2.kych5.com/checkapi
方式二:可以通过双击页面底部文字进入检测页面: