You need to enable JavaScript to run this app.
导航
H5接入文档
最近更新时间:2024.03.05 19:27:30首次发布时间:2024.01.26 16:33:21
效果展示


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

  • accessKeyIdsecretAccessKeysessionToken:临时密钥,必填字段,用于服务端接口鉴权,具体的获取方式参考获取临时密钥(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_colorstring自定义主题色选填--默认颜色 rgba(56, 123, 255, 1)
show_guidestring是否展示认证首页选填,默认10不展示
1展示
show_resultstring是否展示认证结果页选填,默认10不展示,直接跳转到redirectUrl
1展示认证成功和失败页
protocol_namestring自定义协议名称选填--需要保证showGuide=1时才会显示协议名称
protocol_linkstring自定义协议链接选填--需要保证showGuide=1时才会显示协议链接
enable_recordstring优先使用更高效便捷的实时刷脸方案,当设备不支持该方案时的降级处理策略。选填,默认10当设备不支持实时刷脸能力时,则认定本次认证失败
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

无源(根据一张基准图进行认证)

1有源(根据身份证号和姓名进行认证)
liveness_typestring端上活体类型必填motion动作活体
reflection炫彩活体
liveness_timeoutnumber端上活体超时时间选填,默认10--可选范围: [5, 60]
motion_liststring[]可被下发的动作列表选填--可选动作:0:眨眼1:张嘴2:点头3:摇头
fixed_motion_liststring[]固定一定需要下发的动作列表选填--取值同motion_list
motion_countnumber选中的动作个数选填,默认2--可选范围:[1, 4]
max_liveness_trialnumber端上活体最大尝试次数选填,默认10--可选范围:[1, 100]

自定义TOS配置参数
tos_config

sts_ak

string

TOS使用的STS AK

选填

--

如果需要将认证数据存储到自定义TOS时,必填

sts_skstringTOS使用的STS SK选填--如果需要将认证数据存储到自定义TOS时,必填
sts_tokenstringTOS使用的STS Token选填--如果需要将认证数据存储到自定义TOS时,必填
bucketstringTOS使用的Bucket选填--如果需要将认证数据存储到自定义TOS时,必填
endpointstringTOS使用的Endpoint选填--如果需要将认证数据存储到自定义TOS时,必填
regionstringTOS使用的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为计费

bytedTokenstring查询query接口需要的参数
错误码

客户端错误码

resultCode说明
40001当前设备不支持WebRTC
40002摄像头权限获取失败
40003RTC初始化内部错误
40004设备录制视频异常
40005TOS上传异常
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获取人脸图失败
210801SDKData为空
210802SDKData版本异常
210803SDKData版本拦截
210804SDKData数据有误
210805SDKData配置与设置的不相符
210806SDK动作活体未通过
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
方式二:可以通过双击页面底部文字进入检测页面: