# CardSDK

**Repository Path**: sdksoft/card-sdk

## Basic Information

- **Project Name**: CardSDK
- **Description**: 读卡SDK
- **Primary Language**: Unknown
- **License**: GPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2023-12-19
- **Last Updated**: 2025-09-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 注意事项

> 初始化调用一次即可

> 测试使用的 appid 不可以用于商用(否则后果自负)。
   商用的 appid 请务必联系我司商务进行分配。

# 添加aar依赖

- 添加读卡SDK maven仓库

```java
allprojects {
    repositories {
        // 读卡SDK仓库
        maven {
            url 'https://gitee.com/sdksoft/card-sdk/raw/master/Repositorys'
        }
		maven { url 'https://developer.huawei.com/repo/' }
        maven { url 'https://developer.hihonor.com/repo' }
        maven { url 'https://jitpack.io' }
        google()
        jcenter()
    }
}
```

- 依赖最新版本的读卡SDK

```java
// -----------androidX库---------------------------
// 核心读卡SDK（必须）
implementation "io.gitee.sdKsoft:ReadCard:4.2.3"
// 串口、USB读卡（可选，不需要可以不添加依赖）
implementation ("io.gitee.sdKsoft:CshtReadCard_iot:1.2.0")

// OCR 识别护照机读码（可选，不需要可以不添加依赖。也可自由选择自己或其他第三方OCR库）
// OCR 库使用方法，详见文档底部：OCR使用方法 
implementation 'io.gitee.sdKsoft:ocr-android:1.0.7_beta01'

// 华为、荣耀、小米、vivo、oppo等厂商的手机使用时，请务必引用此 OAID SDK
implementation "io.github.CshtZrgk:oaid_sdk:1.0.26"
// 在 build.gradle 配置 HUAWEI Maven仓地址
// maven { url 'https://developer.huawei.com/repo/' }
// maven { url 'https://developer.hihonor.com/repo' }

// -----------support库---------------------------
// 核心读卡SDK（必须）
//implementation "io.gitee.sdKsoft:ReadCard_support:4.1.3"
// IOT（有使用USB、串口时添加）
//implementation "io.gitee.sdKsoft:ReadCard_iot_support:1.0.0"
// 电子护照读取（可选，不需要可以不添加依赖）
//implementation 'io.gitee.sdKsoft:ePassport_support:1.0.4'
```
#  1、读卡参数配置

```java
ReadSettingBuilder readSettingBuilder = ReadCardManager
                // 上下文
                .builder(getBaseContext())
                // 是否开启蜂鸣器
                .buildOpenSound(true) 
                // 是否开启日志，第二位参数为日志保存的目录，
                // 传空字符时，默认在 Android/data/包名/files/zrgkreadcardlog 下
                .buildOpenLog(true, "") 
                // 测试使用的 appid 不可以用于商用(否则后果自负)。
                // 商用的 appid 请务必联系我司商务进行分配。
                .buildAppId("test", "", "")
                // 设置IP与端口号
                .buildIpAndPort("yfs4.sfzydq.com", 9999)             
                // 设置护照服务器IP与端口号
                .buildStandbyIpAndPort("passport.sfzydq.com", 18180)
                // 设置串口号、波特率（串口读卡时需要设置）
                .buildSerialPort("/dev/ttyS0", 115200)
                // 设置读卡类型（目前支持USB、USB_XZKJ、NFC、NFC_PASSPORT、
                // SERIALPORT、SAM_USB、SAM_SERIALPORT）
                .buildReadCardType(ReadCardType.USB)
                // 循环读卡时，是否允许返回连续相同的身份证信息（读卡类型 USB_XZKJ 时有效）
                .buildResultRepeatIdCard(true)
                // 照片解码类型（目前支持无照片、服务器解码、本地解码照片）
                .buildDecodeImageType(DecodeImageType.LOCAL_DECODE)
                // 设置开启的卡片识别类型（默认已启用了IC卡、身份证、港澳台、外国人居住证，其余证卡类型需要手动配置开启，用不到的可以不开启，以免影响读卡速度）
                .buildEnableCardScanType(EnableCardScanType.CARD_LCT, EnableCardScanType.CARD_SB, EnableCardScanType.CARD_M1, EnableCardScanType.CARD_BANK)
                // 解码身份证时，是否需要生成身份证正反面照片
                .buildNeedIdCardPhoto(false)
                // 解码护照时，是否需要读取芯片里的高清人脸照（时间较长。也可由OCR提取人脸照，速度快）
                .buildNeedPassportPhoto(true);

ReadCardOutMethod readCardManager = readSettingBuilder.buildCreate();
```

# 2、读卡初始化方法

## 2.1 当选择的读卡类型是USB、NFC时，初始化方法如下：

```java
readCardManager.readCardInit((code,msg) -> {
                if (code == StatusCode.ININ_ING.getCode()) {
                    Log.e("mtj", "初始化中");
                } else if (code == StatusCode.ININ_OK.getCode()) {
                    Log.e("mtj", "初始化成功");
                } else {
                    // 其他错误，对照错误码查看
                    Log.e("mtj", "初始化失败");
                }
            });
```
## 2.2 当选择的读卡类型是串口时，初始化方法如下：

```java
// 第一个参数：串口文件
// 第二个参数：波特率
readCardManager.readCardInit((new File("/dev/ttyS0"), 115200, (code,msg) -> {
                if (code == StatusCode.ININ_ING.getCode()) {
                    Log.e("mtj", "初始化中");
                } else if (code == StatusCode.ININ_OK.getCode()) {
                    Log.e("mtj", "初始化成功");
                } else {
                    // 其他错误，对照错误码查看
                    Log.e("mtj", "初始化失败");
                }
            });

```
 - 如果已经通过 buildSerialPort 设置了串口号和波特率，也可直接使用 2.1 的初始化方法


#  3、用户开启读卡

- NFC读卡类型时，开启读卡方法如下：

```java
readCardManager.readCardStart(intent, listener);
```

- NFC_PASSPORT读电子护照类型时，开启读卡方法如下：

```java
readCardManager.readPassportStart(intent, documentNumberStr, dateOfBirthStr, dateOfExpiryStr, listener);
```

- USB、SERIALPORT读卡类型时，开启读卡方法如下：

```java
readCardManager.readCardStart(listener);
```

## 方法参数说明

|参数名|必选|类型|说明|
|:----    |:---|:----- |-----   |
|intent|是  |Intent|nfc系统回调实体类|
|documentNumberStr|是  |String|9位护照号码|
|dateOfBirthStr|是  |String|生日，格式 yyMMdd 如：900203|
|dateOfExpiryStr|是  |String|护照有效期，格式 yyMMdd 如：290506|
|listener|是  |ReadCardListener| 方法回调|


## ReadCardListener回调说明
|方法名|参数|说明|
|:-----  |:-----|-----  |
| onReadIDCardSuccess(IdCardData)|IdCardData（身份证信息）|详见身份证信息表  |
| onReadICCardSuccess(icNumber: String，type:int)|icNumber（卡号） type(卡片类型)|其他类型卡成功回调方法，详见卡类型表   |
| onReadCardState(type: Int, msg: String)|type（状态码）msg（状态信息）|失败或其他状态回调，详见错误码表  |
| onReadPassportSuccess(EPassportData)|EPassportData(电子护照信息)|详见电子护照信息表 |
| onReadIDCardPhoto(Bitmap frontPhoto, Bitmap backPhoto)|frontPhoto(身份证正面照)backPhoto(反面照)|配置参数buildNeedIdCardPhoto(true)有效 |

# 4、用户关闭读卡

```java
readCardManager.readCardStop();
```


#  单独开关日志

```java
// 是否开启日志，第二位参数为日志保存的目录，
// 传空字符时，默认在 Android/data/包名/files/readcardlog 下
readSettingBuilder.buildOpenLog(false, "");
```

#  获取设备信息

```java
readCardManager.readCardDeviceid();
```
#  获取固件版本号

```java
readCardManager.readFirmwareVersion();
```

## 身份证详细信息IdCardData
|字段|类型|注释|
|:-----  |:-----|-----  |
|address|string      |    家庭住址          |
|birthday|string |   出生日期  |
|dn|string  |   dn码|
|endDate|string  |   身份证结束时间|
|startDate|string  |    身份证生效时间|
|id|string      |   身份证号码  |
|image|ByteArray|  照片原始信息  |
|issue|string      |   签发机关|
|name|string      |  姓名|
|nation|string      |   民族|
|sex|string      |  性别|
|uuid|string      |  uuid|
|bitmap|Bitmap|    照片|


## 外国人永久居住证IdCardData：
|字段|类型|注释|
|:-----  |:-----|-----  |
|type|int      |  1081:新版外国人永久居住证。1083：老版外国永久居住证  |
|birthday|string |   出生日期  |
|dn|string  |   dn码|
|endDate|string  |   身份证结束时间|
|startDate|string  |    身份证生效时间|
|id|string      |   身份证号码  |
|image|ByteArray|  照片原始信息  |
|issue|string      |   签发机关|
|sex|string      |  性别|
|uuid|string      |  uuid|
|bitmap|Bitmap|    照片|
|nameChinese|string |   中文姓名  |
|nameEnglish|string |   英文姓名  |
|nameEnglishAdd|string |   英文附加姓名  |
|nationlity|string |   国籍  |
|cardVersion|string |   卡版本号  |
|cardType|string |   卡类型  |
|historicalNumber|string |   既往版本证件号码关联项  |
|renewalNumber|string |   换证次数  |

## 电子护照详细信息EPassportData
|字段|类型|注释|
|:-----  |:-----|-----  |
|nameOfHolder|string      |    中文姓名    |
|primaryIdentifier|string |   姓  |
|secondaryIdentifier|string  |   名|
|gender|string  |   性别 M男 F女|
|dateOfBirth|string  |    生日|
|nationality|string      |   国家码  |
|dateOfExpiry|string|  有效期  |
|documentNumber|string      |   护照号码|
|duration|long      |  解码时长|
|mrz|string      |  机读码|
|personNumber|string      |  个人号码|
|idNumber|string      |  证件号码|
|image|ByteArray|    护照证件照片|


## 状态码对应表

```java
    READCARD_SUCCESS(1000, "解码成功"),

    ININ_OK(1001, "初始化成功"),
    ININ_FAILE(1002, "初始化失败"),

    USB_NODEVICE_CODE(1003, "未发现读卡设备,请检查usb连接"),
    USB_NOREADCARD_CODE(1004, "没有检测到读卡设备"),
    USB_SYSYTEMREEOE_CODE(1005, "系统usb异常,请检查usb连接"),
    USB_NOINTERFACE_CODE(1006, "usb没有建立连接"),
    USB_NOCHANNLE_CODE(1007, "usb通道打开失败"),
    USB_NOSERVICE_CODE(1008, "没有usb服务"),

    SOCKET_SYS_CODE(1010, "网络通讯异常"),
    LOCAL_DATA_ERROR(1018, "本地通信失败"),

    UNKONW_ERROR(1020, "未知异常"),
    READCARD_START(1021, "解码开始"),
    READCARD_FAILE(1022, "解码失败"),
    READCARD_READING(1023, "解码中"),

    FIND_CARD_START(1024, "开始寻卡"),
    FIND_CARD_FAIL(1025, "寻卡失败"),
    FIND_CARD_SUCCESS(1026, "寻卡成功"),

    READ_UID_FAILE(1031, "UID异常"),
    SERIALPORT_NOINTERFACE_CODE(1036, "串口异常，请检查设备"),
    SERIALPORT_DATA_ERROR(1038, "串口异常"),
```


## 其他卡类型

```java
    CARD_IC(1040, "IC卡"),
    CARD_M1(1041, "M1卡"),
    CARD_LCT_STUDENT(1051, "绿城通学生卡"),
    CARD_LCT_NORMAL(1052, "绿城通普通卡"),
    CARD_LCT_OLD(1053, "绿城通老年卡"),
    CARD_SB(1060, "社保卡"),
    CARD_BANK(1061, "银行卡"),
    CARD_CMCC_SIM(1070, "中国移动超级SIM卡"),
    CARD_CUCC_SIM(1071, "中国联通超级SIM卡"),
    CARD_CTCC_SIM(1072, "中国电信超级SIM卡"),
    // 身份证件
    CARD_IDCARD(1080, "中国居民身份证"),
    CARD_IDCARD_FOREIGN(1081, "新版外国永久居住证"),
    CARD_IDCARD_GAT(1082, "港澳台居住证"),
    CARD_IDCARD_FOREIGN_OLD(1083, "老版外国永久居住证")

```

## OCR识别库使用方法

- 目前支持护照机读码识别（MRZ码）


使用前自行申请相关权限
```
Manifest.permission.CAMERA
```

```

    /**
     * 开始扫描识别
     */
    private fun startScann() {
        ScanningManager.instance.openScanningActivity(this@MainActivity, Config(true, ScanTypeEnum.PASSPORT_MRZ, 
                object :ScanResultListener{
                    override fun onSuccessListener(value: String?) {
                        // 识别结果
                    }

                    override fun onFailureListener(error: String) {
                        // 识别失败
                    }
                }))
    }


//Config 参数说明

Config(
    /**
     * 是否循环识别，等待识别结果
     */
    val isLoopWaitResult: Boolean = true,
    /**
     * 识别类型
     * 目前支持 电子护照MRZ识别
     */
    val scanType: ScanTypeEnum = ScanTypeEnum.PASSPORT_MRZ,
    /**
     * 结果回调
     */
    val scanResultListener: ScanResultListener? = null
)
```
#### 电子护照OCR 识别结果
|字段|类型|注释|
|:-----  |:-----|-----  |
|MRZLine1|string      |    机读码第一行    |
|MRZLine2|string |   机读码第二行  |
|dateOfBirth|string  |    生日|
|dateOfExpiry|string|  有效期  |
|documentNumber|string      |   护照号码|