SDK (Androd版)

1. 欢迎使用

​ 欢迎您使用身份核验移动端SDK，如果本手册能为您提供帮助，带来便利，我们将深感欣慰。如果您在使用过程中，遇到了问题，或对我们产品有好的建议，可以：

( 致电客户服务热线（010）58515511: 或访问公司网站：www.bjca.org.cn
与我们联系，对您提出的问题或建议，我们表示衷心的感谢。)

2. 版权声明

​ 本手册著作权属北京数字认证股份有限公司所有，在未经本公司许可的情况下，任何单位或个人不得已任何方式对本手册的部分或全部内容擅自进行增删、改编、节录、翻印、改写。

北京数字认证股份有限公司©2019

3. 阅读指南

本手册可以辅助您快速了解和掌握身份核验移动端SDK的各项功能和具体的使用操作方法。

本手册主要包括三部分，本节阅读指南引导您了解本手册的主要内容、快速使用说明、阅读中的注意事项以及手册约定；

第1章为产品简介，向您介绍本产品的基本功能、用途、产品特点和相关技术情况，帮助您对本产品具有直观的认识和了解；

第2章为产品使用，介绍应当如何使用该产品。其中包括产品的部署，和后续的开发、测试等；

第3章介绍本产品的各个接口，包含接口的声明、参数、返回值等详细信息；

第4章是产品错误码的说明，给出错误码的含义，以及出现该错误时，推荐的处置方法。

约定

约定标识 说明
[ ] 方括号包含可选的参数。
【】 表示按钮符号，如【确定】即指界面上的确定按钮。
… 在语法行中，省略号指示可能包括更多相同格式的项目。
img 此符号代表警告提示，需要读者特别注意该内容。
img 此符号代表对内容进行特别说明或解释。
* 此符号在界面中所对应的输入框或选择框为必填项或必选项

4. 产品简介

“互联网+”可信身份认证平台（简称“CTID平台”)通过汇聚脱敏身份证制证数据形成网上身份认证基础数据，依托身份认证服务系统，为民众提供开通身份证网上功能的服务，为网络运营商提供身份认证服务。

数字认证身份核验服务依托公安部CTID平台，以法定二代身份证为基础数据源，面向银行、保险、互联网服务等各类应用提供权威、可信、安全、便捷的身份核验服务，以解决互联网环境中身份的实名、实人、实证的可信问题。

4.1 服务内容

数字认证充分考虑“互联网＋”、“放管服”等政府改革，及现有行业应用特点，以“证件真实性、有效性、人证同一性”认证为手段，推进了“实名、实人”两类身份核验服务。数字认证身份核验服务由云服务和服务支撑产品共同组成。

服务内容

核验服务分类 服务内容 核验关键项 服务效果
身份核验服务(CTID实名) 两项信息实名核验(CTID-SM02) 身份证号+姓名 核验身份信息真实性
四项信息实名核验(CTID-SM04) 身份证号+姓名+有效期起止日期 核验身份信息真实性、有效性
身份核验服务(CTID实人) 两项信息实人核验(CTID-SR02) 人像+身份证号+姓名 核验人像相似度及身份信息真实性
四项信息实人核验(CTID-SR04) 人像+身份证号+姓名+有效期起止日期 核验人像相似度及身份信息真实性、有效性

支撑服务的相关产品

产品名称 产品编号 功能描述
身份核验SDK CTID-SDK 支持移动端，包括两个功能模块：身份信息获取、人脸信息核验，分别提供身份信息OCR获取、活体检测及人脸识别功能
身份核验管理系统 CTID-S 为业务系统提供实名核验、实人核验核验等接口；并提供核验统计、本地授权管理等管理功能
签名验签服务器(CTID专用) DSVS-G 提供基于数字证书的身份认证服务、数据签名与签名验证服务、加解密服务和数字信封服务

4.2 服务方式

数字认证身份核验服务根据不同客户的实际业务需求，设计了两种服务方式。

4.2.1 云服务方式

针对身份核验业务量级小的客户，直接通过安全通道连接到数字认证身份核验云服务平台，提供身份核验服务。部署示意如下：

img

客户按照业务需求，集成身份核验SDK，客户业务系统通过互联网安全通道连接到到数字认证身份核验云服务平台，实现数据交互功能。云服务平台使用数字认证专属的签名验签服务器（CTID专用），通过专线与公安部CTID身份认证平台互联，实现身份数据安全、可靠传输。

4.2.2 混合云服务方式

针对身份核验业务量级较大的客户，为保证服务可靠和安全，可选择混合云的服务方式。示意如下：

img

客户按照业务需求，集成身份核验SDK，在业务服务端，可根据需要部署身份核验管理系统及一台(或多台)签名验签服务器（CTID专用），用于进行本地数据统计、业务管理与使用数据签名、签名验证、加解密、数字信封等服务；云服务平台通过专线与公安部CTID身份认证平台互联，实现身份数据安全、可靠传输。

4.3 应用领域

行业 典型客户 典型应用
政务/事业单位 公安、研究院、信息中心、国家及各省市社会保障局、金融协会、外汇交易中心 政府的网上申报、办公审批、社保发放等
企业 银行、金融服务企业、在线支付企业、保险企业、证券、大型互联网公司、信息安全企业 银行柜面/远程开户、证券柜面/远程开户、长险投保、理赔、APP实名注册、合同签署
交通 交通研究院、研究所、运输公司 高铁刷身份证+人脸乘车
卫生 省市卫健委、省市卫生政务服务中心 计划生育服务证在线办理等
教育 省市教育主管单位、高校、考试院 课程注册、考场考生在线身份验证等

4.4 条件与限制

身份核验SDK产品需要与云端身份核验服务或本地版IDSP服务配合使用。

本产品由于其产品形态受开发语言和环境的限制，其源代码存在被分析和篡改的可能，获得本产品的用户不应采取反编译、重新插入执行指令等方式对本产品进行分析和修改。所有业务相关功能的调整应与北京数字认证股份有限公司协商并在授权下进行，所有未经授权的分析和修改行为北京数字认证股份有限公司不对造成的后果负责，并保留追究使用者违法行为的权利。

本产品不具备自动升级的功能，用户获得本产品发布物后本产品提供的功能就已固定。使用者要想使用身份核验后续推出的新功能时，需要重新获得新版本的身份核验SDK，并按照新的接口进行集成升级。如何获得新版本身份核验SDK产品并使用新的功能，应依据具体身份核验业务授权协议进行。

本产品在交付时支持的终端操作系统版本受限于交付的日期，具体支持型号由交付时身份核验业务授权协议确定。本产品在按协议交付后，并不保证对未来新发布终端操作系统的支持，用户如需对新发布终端操作系统提供支持，应联系北京数字认证股份有限公司获得新的发布产品。

本产品支持的终端操作系统Android是指由谷歌公司发布的移动终端操作系统，IOS是指由苹果公司发布的移动终端操作系统。其他非上述公司授权发布的移动终端操作系统，本产品不保证功能能够正常使用。

5. 产品使用

5.1 调用流程

本产品的调用流程整体分为两步：

核验申请：业务应用调用SDK初始化接口，产生核验申请数据。业务应用将SDK返回的申请数据发送至业务服务端，业务服务端调用身份核验服务的核验申请接口，产生完整的核验申请数据并发送至公安一所；身份核验服务接收公安一所返回的申请应答数据并返回至业务服务端，流程结束。

身份信息采集，业务应用调用SDK的执行接口，根据传入核验模式的不同，采集用户的身份信息、人脸信息并进行打包，产生完整的身份核验数据。业务应用接收SDK返回的身份核验数据后，发送至业务服务端。业务服务端调用身份核验服务对应的核验模式接口，产生完整的核验数据，并发送至公安一所进行核验，身份核验服务接收公安一所返回的核验应答数据后，返回至业务服务端，流程结束。

img

核验申请流程

img

身份核验流程

5.2 产品部署

身份核验组件包组成如下表所示，IDSPSDK.aar为身份核验核心组件包，必须集成在应用工程中，若应用工程中已有gson-2.2.2.jar，则可不用重复集成，否则该jar包也必须包含在应用工程中。活体检测、OCR身份证识别控件根据应用工程所需要的功能进行选择性集成。

若使用OCR身份证识别功能，会涉及大量图片的处理，可能会产生OOM的问题，可在主工程的AndroidManifest.xml中加上如下两句：

android:hardwareAccelerated=”true”

android:largeHeap=”true”

组件名称 组件包 集成路径 说明
身份核验SDK IDSPSDK.aar libs 必须集成
gson gson-2.2.2.jar libs 应用工程中已有则可不集成
活体检测 signetLiveCheckComponent_V1.0.1.jar cloudwalk3.jar libcloudwalksdk.so jar包：libs so库：libs/armeabi-v7a 应用工程中不需要活体检测功能则可不集成
OCR身份证识别 signetOcrComponent_V1.0.1.jarlibIDCARDDLL.so jar包：libs so库：libs/armeabi-v7a 应用工程中不需要身份证识别功能则可不集成

6. 接口说明

6.1 核验模式

身份核验服务提供实名、实人等核验类型，集成商可以根据业务场景需要，选择不同安全强度的身份核验模式。具体的身份核验模式见下表，其含义及模式编码如表所示。

序号 代码 核验模式 调用控件
OCR控件 活体控件
1 0X10 4项信息 ●
2 0X12 人像+ 4项信息 ●
3 0X40 2项信息 ●
4 0X42 人像+2项信息 ●

6.2 初始化接口

接口功能：

初始化接口，用于生成者身份核验申请数据包。

接口定义：

BJCAIdentifyAPI.initialCtidIdentify(Context context, CtidModelEnum ctidModelEnum, CtidActionType ctidActionType)

参数说明：

context:上下文环境

ctidModelEnum:身份核验模式，枚举类型，定义与声明如下：

//核实模式（具体每种模式含义见表1）MODEL_0X10,MODEL_0X12,MODEL_0X40,MODEL_0X42,

ctidActionType:业务类型标志位，用于标志该次业务类型为身份核验，枚举类型，定义与声明如下：

AUTH_ACTION，该业务操作为身份核验

返回值说明：

CtidReturnParams：定义如下

{

   String status; 状态码
   String message;  状态信息
   String value; 如果状态码返回成功，则该字段为返回的身份核验申请数据包

}

调用示例：

BJCAIdentifyAPI.initialCtidIdentify(this, CtidModelEnum.MODEL_0X10

, CtidActionType.AUTH_ACTION);

6.3 执行接口

接口功能：

执行接口，用于生成者身份核验数据包。

接口定义：

BJCAIdentifyAPI.actionCtidIdentify

(Context context, String applyOriData,

CtidModelEnum ctidModelEnum, CtidActionType ctidActionType，BJCAAuthModel authModel,IdentifyCallBack identifyCallBack){

  @Override
   **public  void**  onIdentifyCallBack(CtidReturnParams ctidReturnParams) {

//TODO

​           }
​    @Override
​    **public void** onPreExecute() {

//TODO

​            }
});

参数说明：

context:上下文环境

applyOriData:身份核验申请成功后从服务端获取的返回值

ctidModelEnum:身份核验模式，枚举类型，定义与声明如下：

//核实模式（具体每种模式含义见表1）
MODEL_0X10,MODEL_0X12,MODEL_0X40,MODEL_0X42,

ctidActionType:业务类型标志位，用于标志该次业务类型为身份核验，枚举类型，定义与声明如下：

AUTH_ACTION，该业务操作为身份核验

​ authModel：用户传入的值，为BJCAAuthModel类型，定义及说明如下

{

   String name;     用户姓名
   String idNumber; 用户身份证号
   String validFrom; 用户身份证有效期起始日期
   String validEnd; 用户身份证有效期截止日期
}

/说明：姓名加身份证号简称用户两项信息，姓名加身份证号加起始日期加截止日期简称用户四项信息，上述四项信息均为选填，当用户选择的核实模式或者下证模式包括两项信息时，如果两项信息不外传，则身份信息确认页可编辑，如果两项信息从该接口传入，则身份信息确认页不可编辑，同理，当用户选择的核实模式或者下证模式包含四项信息时，如果四项信息均从该接口传入，则身份信息确认页不可编辑，否则可编辑。/

返回值说明：

​ 回调函数onIdentifyCallBack中返回ctidReturnParams，为CtidReturnParams类型，定义如下：

{

   String status; 状态码
   String message;  状态信息
   String value; 如果状态码返回成功，则该字段为返回的身份核验数据包

}

​ 回调函数onPreExecute中可选择实现，当身份核验数据包可实现等待窗，避免长时间的卡顿情况。

调用示例：

BJCAIdentifyAPI.actionCtidIdentify(this, oriapplydata,  CtidModelEnum.*MODEL_0X10*

, CtidActionType.AUTH_ACTION, bjcaAuthModel, new IdentifyCallBack(this) {
    @Override
    public void onIdentifyCallBack(CtidReturnParams ctidReturnParams) {
          }
    @Override
    public void onPreExecute() {
         }
});

7. 错误码说明

本章节主要介绍接口产品返回错误码的含义说明，和出现错误时的处理建议。

错误码名称 类型 值 含义
SUCCESS String 0x0000 操作成功
PERMISSION_NOT_GRANTED String 0x0007 未授权
MISSING_NESSARY_INPUT String 0x0008 缺少重要输入参数
DECRYPT_FAILED String 0x0010 解密失败
WRITE_EXTERNAL_STORAGE_NOT_GRANTED String 0x0011 获取读写权限失败
CAMERA_NOT_GRANTED String 0x0012 获取相机权限失败
MISSING_NESSARY_ID_INFO String 0x0016 缺少用户身份信息