ySKAuth

来自于:云识客立即使用

概述

云识客互联网人脸核身通过检测身份证人像照,与活体检测的人脸照做比对,判断是否是同一人,并返回身份证文字信息。包括如下功能:

1 . 身份证检测识别:扫描身份证,获取身份证照片与身份证人像,并识别身份证文字信息

2 . 活体检测:本地端动作活体检测+云端防攻击,确保当前用户是真人,防止照片欺诈,视频翻拍等问题

3 . 人脸比对:将活体照与身份证人像照进行人脸比对,返回相似度

4 . 实人认证:将姓名、身份证号、活体照送至权威机关核验,判断信息是否是一致

商户接入操作步骤

开发者在使用云识客模块(模块名:ySKAuth)时,需要联系市场人员开通服务,获取appKey和secretKey值后,方可使用云识客模块。整体流程分为以下步骤:

1.联系云识客 开发者在使用云识客的模块时,可通过电话(0571-56278596)或者官网(http://www.yskplus.com)联系云识客。

2.对接 请双方商务人员完成开户。在开户过程中,商户需提供商户名称;智趣智能将提供app_key和secret_key。 友情提醒:app_key和secret_key为商户的重要身份信息,商户需要自行妥善保管。

3.开始对接 商户在APICloud官网导入云识客的模块(模块名:ySKAuth),打包编译并使用。在开发或使用模块接口时,产生疑问或出现问题,可通过微信、Email、手机联系相关技术人员,相关技术支持人员会及时处理。

4.完成以上步骤,即可开始对接联调

版本兼容

编译时候的固件版本android4.0.2(minSdkVersion 15)以上,IOS8.0以上的终端设备使用。

UI界面图

身份证OCR识别UI页面、身份识别结果页面、活体检测UI页面如下:


注:如UI界面图所示,参考调用方法,成功调用出现”身份证OCR”界面扫描身份证,OCR完成确认扫描信息后进入活体检测界面。该流程UI界面等已封装,商户可按流程完成操作无须自定义。

参数约定

  1. 是否必传:指接口的请求报文和返回报文中的参数:Y表示必传参数;N表示非必传参数;
  2. 返回结果码:表示功能调用是否成功

调用步骤

  • 引入云识客模块 ySKAuth

  • 调用与回调方法,全流程:startAuth(),调用示例如下

   // 1.云识客全流程
   function runySKAuth() {
      var ySKAuth = api.require('ySKAuth');
      ySKAuth.startAuth(params, function(ret, err) {
          if (!err) {
              //success回调
              console.log(JSON.stringify(ret))
          } else {
              //error回调    
          }
        });
    }
   // 默认配置
   var params = {
        appKey: 'xxx', 
        secretKey: 'xxx', 
        traceId:'xxx', 
        notifyUrl: 'xxx', 
        extensionInfo: 'xxx',
        needUserGuide: true,
        isOcrFirst: true,      
        idCardOperation: {
            mode: 'FRONT_RECOGNIZE_BACK_RECOGNIZE',
            displayText: true,
            displayFaceImage: false,
            modifyIdNo: false
        },
        livenessOperation: {
            actionNum: 3,
            actions: '0,1,2,3,6',
            openSpeaker: true,
            realAuth: true,
            isNeedFaceCompare: true
        }
    }
  • 调用与回调方法,身份证OCR:startOcr(),调用示例如下
   // 1.云识客身份证ocr
    function runOcrAuth() {
        var ySKAuth = api.require('ySKAuth');
        ySKAuth.startOcr(params, function(ret, err) {
             if (!err) {
              //success回调
              console.log(JSON.stringify(ret))
          } else {
              //error回调    
          }
        });
    }
   // 默认配置
   var params = {
        appKey: 'xxx', 
        secretKey: 'xxx', 
        traceId:'xxx', 
        notifyUrl: 'xxx', 
        extensionInfo: 'xxx',
        needUserGuide: true,     
        idCardOperation: {
            mode: 'FRONT_RECOGNIZE_BACK_RECOGNIZE',
            displayText: true,
            displayFaceImage: false,
            modifyIdNo: false
        }
    }
  • 调用与回调方法,活体检测:startLiveness(),调用示例如下
   // 1.云识客活体检测
   function runLivenessAuth() {
      var ySKAuth = api.require('ySKAuth');
      ySKAuth.startLiveness(params, function(ret, err) {
          if (!err) {
              //success回调
              console.log(JSON.stringify(ret))
          } else {
              //error回调    
          }
        });
    }
   // 默认配置
   var params = {
        appKey: 'xxx', 
        secretKey: 'xxx', 
        traceId:'xxx', 
        notifyUrl: 'xxx', 
        extensionInfo: 'xxx',
        needUserGuide: true,
        livenessOperation: {
            actionNum: 3,
            actions: '0,1,2,3,6',
            openSpeaker: true,
            isCompare: false,
            compareImage: 'base64格式图片', 
            compareImageType: "IMAGE_TYPE_ID_FACE"
        }
    }
  • 入参配置参数列表
参数名 是否必传 参数类型 参数说明 描述
appKey Y String 商户开户后的appKey 用于商户权限校验
secretKey Y String 商户开户后的secretKey 用于通讯报文验签
traceId Y String 商户接口调用跟踪号 商户跟踪号,建议唯一
notifyUrl N String 商户接收异步通知的web url 当需要接收异步通知时设定,默认不设置
extensionInfo N String 商户异步通知需要的额外信息 当需要接收异步通知且有其他额外需要添加的信息时设置,默认不设置
needUserGuide N boolean 是否显示用户使用说明窗口 当需要显示用户使用说明窗口时设置为true,默认为true(显示)
isOcrFirst Y boolean 是否先加载OCR true:先OCR后活体
false:先活体后OCR
idCardOperation Y IDCardOperation OCR功能选项 OCR功能选项封装类,字段详细见下面说明
idCardOperation.mode Y String ocr检测动作模式 正面、反面、检测、识别等功能选项。可选值见:OCR检测识别模式
idCardOperation.modifyIdNo N boolean 设置是否允许修改身份证号码 设置是否允许修改身份证号码,默认false(不修改)
idCardOperation.displayText N boolean 是否显示识别结果页 是否显示识别结果页,默认为true(显示)。当需要进行文字识别后有效
idCardOperation.displayFaceImage N boolean 识别结果页是否显示证件人相照 识别结果页中是否显示证件人像照,默认为false(不显示)。当需要显示识别结果页时有效
livenessOperation Y LivenessOperation 活体检测功能选项 根据业务需要设定,包括多个子参数。
livenessOperation.openSpeaker N boolean 是否打开扬声器 进入活体检测界面时的语音提示控制,默认为true(打开)
livenessOperation.actionNum N int 活体动作数量 商户可以自定义,默认值为3,表示三个随机动作。动作数量不能少于1个,不能大于3个。
livenessOperation.actions N String 自定义动作,最多不超过3个,用逗号隔开 数量不能小于设置的actionNum。默认为系统支持的全部动作。可添加的动作类型见:活体检测动作类型
livenessOperation.realAuth N boolean 是否实人认证 当调用全流程(startAuth方法)时设置,默认true(实人)
livenessOperation.isNeedFaceCompare N boolean 是否进行人脸比对 当调用全流程(startAuth方法)时设置,默认true((比对)
livenessOperation.isCompare N boolean 是否需要和外部照片比对 当调用活体检测(startLiveness方法)时设置,默认false(不对比)
livenessOperation.compareImage N String 比对的外部图片 当调用活体检测(startLiveness方法),且需要和外部比对时设置,默认null
livenessOperation.compareImageType N String 比对的外部图片类型 当调用活体检测(startLiveness方法),且需要和外部比对时设置。支持的类型见:比对图片类型

OCR检测识别模式

FRONT_RECOGNIZE——正面检测识别;
FRONT_RECOGNIZE_BACK_DETECT——正面检测识别+反面检测;
FRONT_RECOGNIZE_BACK_RECOGNIZE——正面检测识别+反面检测识别;

活体检测动作类型

idlivenessOperation.actions
0--眨眼;
1--微笑;
2--左转头;
3--右转头;
6--左右摇头;

比对图片类型

idlivenessOperation.compareImageType
活体人脸照(IMAGE_TYPE_LIVE_FACE)
证件人脸照(IMAGE_TYPE_ID_FACE)
水印人脸照(IMAGE_TYPE_WATER_FACE)

回调返回结果

success回调结果示例

  //success回调
  {
      "zqOrderId": "xxx",
      "idCardFrontInfo": {
          "name": "xxx",
          "idNo": "xxx",
          "address": "xxx",
          "birth": "xxx",
          "gender": "xxx",
          "race": "xxx",
          "cardImage": "base64格式图片",
          "faceImage": "base64格式图片"
      },
      "idCardBackInfo": {
          "issuedBy": "xxx",
          "validDate": "xxx",
          "cardImage": "base64格式图片"
      },
      "newName": "xxx",
      "newIdNo": "xxx",
      "livenessCompareInfo": {
          "livenessScore": "xxx",
          "similarity": "xxx",
          "verifyStatus": 0,
          "reason": "xxx",
          "reasonCode": 0,
          "realAuthSimilarity": 0.7,
          "faceImage": "base64格式图片"
      }
  }

success回调参数列表

字段名称 字段描述 是否必传 备注
zqOrderId 云识客订单号 Y
idCardFrontInfo
idCardFrontInfo.idNo 居民身份证18位号码 Y
idCardFrontInfo.name 居民身份证姓名 Y
idCardFrontInfo.gender 性别 Y 男/女
idCardFrontInfo.birth 生日 Y 格式为yyyy.MM.dd
idCardFrontInfo.race 民族 Y 汉字
idCardFrontInfo.address 地址 Y
idCardFrontInfo.cardImage 证件正面图片 Y base64格式
idCardFrontInfo.faceImage 证件人像照图片 Y base64格式
idCardBackInfo
idCardBackInfo.issuedBy 居民身份证发证机关 N
idCardBackInfo.validDate 居民身份证有效期 N 两种格式。16位长度的字符串:
YYYY.MM.DD-YYYY.MM.DDYYYY.MM.DD-长期
idCardBackInfo.cardImage 证件反面图片 N base64格式
newName 正面修改后姓名 N 当修改姓名时返回
newIdNo 正面修改后身份证号码 N 当修改身份证号码时返回
livenessCompareInfo
livenessCompareInfo.livenessScore 活体置信度 Y 0到1之间,如何取值参见:活体置信度阈值说明
livenessCompareInfo.similarity 活体和身份证人脸照片相似度 Y 0到1之间,如何取值参见:活体和身份证人脸照片比对相似度阈值说明
livenessCompareInfo.faceImage 活体清晰照 Y base64格式
livenessCompareInfo.verifyStatus 实人认证状态 N 0:不通过
1:通过
livenessCompareInfo.reason 实人认证结果描述 N 认证通过
姓名身份证号不匹配
人脸与公安底库不一致
认证异常
livenessCompareInfo.reasonCode 实人认证失败原因编码 N 0: 姓名身份证号不匹配
1: 人脸与公安底库不一致
2: 认证异常
livenessCompareInfo.realAuthSimilarity 活体照与权威照片的比对相似度 N 相似度值大于0.7,认证状态通过,反之不通过

error回调结果示例

  //error回调
  {
    "zqOrderId": "xxx",
      "resultCode": 900001,
      "resultMessage": "xxx",
      "resultDetail": "xxx"
  }

error回调参数列表

字段名称 字段描述 是否必传 备注
zqOrderId 云识客订单号 Y
resultCode 结果码 Y 结果码参见:回调结果码
resultMessage 结果码描述 Y
resultDetail 结果码详情 Y

回调结果码

结果码 ErrorCode枚举 结果码描述 结果码详情
200001 LIVENESS_DETECT_RECOGNIZE_ERROR 活体检测识别失败 活体检测识别失败
200002 USER_COUNTOUT 活体错误次数超限 活体错误次数超限
900001 PARAM_INVALID 参数无效 无效参数说明
900002 NO_NETWORK 无网络连接 无网络连接
900003 AUTH_ERROR sdk授权失败 授权错误信息
900004 USER_CANCEL 用户取消 用户取消
900005 CAMERA_ERROR 打开摄像头失败 打开摄像头失败
900006 USER_TIMEOUT 用户操作超时 用户操作超时
999999 PRO_ERROR 处理错误 处理错误

活体置信度阈值说明

误拒率(FRR) 阈值
千分之一 0.3
千分之五 0.5
百分之一 0.6
百分之三 0.7
百分之五 0.8
  • 误拒率(FRR):如千分之五,指1000次真人请求,会有5次因为活体分数低于阈值被错误拒绝;
  • 阈值:将阈值与返回的livenessScore进行比较,可以作为判断是否为活体的依据;
  • 建议商户根据自身业务场景设置阈值,一般场景设置为0.5,严格场景可设置为0.7或更高;
  • 模型升级不影响活体分数的阈值范围(云识客已经进行了归一化处理);

活体和身份证人脸照片比对相似度阈值说明

误识率(FPR) 阈值
千分之一 0.7
万分之一 0.8
十万分之一 0.9
百万分之一 0.95
  • 误识率(FPR):如千分之一,指1000次不同人的两张照片比对,会有1次因高于阈值而被识别成同一个人;
  • 阈值:将阈值与返回的similarity进行比较,可以作为判断是否为同一个人的依据;
  • 建议商户根据自身业务场景设置阈值,如一般场景设置为0.7,严格场景可设置为0.8或更高;
  • 模型升级不影响相似度阈值范围(云识客已经进行了归一化处理)