中软高科苹果iPhone手机iOS系统NFC身份证解码SDK集成说明

概要说明

iOS系统NFC相关API需要 13.0以上，因此接入的APP运行环境只有iOS 13以上才能正常调用SDK 提供的API。

说明：iOS 接入不支持模拟器模式调试。本SDK 使用开发语言为 Objective-C。

配置开发环境

1. 在Xcode的编译环境设置中，选择Linking > Other Linker Flags，添加-ObjC。

2. 应用权限配置

1）登录苹果开发者管理平台，确认当前bundle ID下的NFC Tag Reading已经选中。

2）在项目工程的info.plist文件中添加Privacy - NFC Scan Usage Description和ISO7816 application identifiers for NFC Tag Reader Session，在item0中填写 F049442E43484E（身份证）。

3）在Xcode中，选择TARGETS > Signing&Capabilities > All，添加Near Field Communication Tag Reading。

配置依赖

1）导入iOS SDK

该 SDK 为 framework 包：ZRGKReadCardSDK.framework。

2）添加库依赖

在Build Phases > Link Binary With Libraries中，添加以下系统库依赖：libc++.tbd

调用SDK

1）引入头文件

#import <ZRGKReadCardSDK/ZRGKReadCardSDK.h>

SDK包含的文件说明：

类名/文件名	说明
ZRGKReadCardSDK.h	ZRGKReadCardSDK.h
ZRGKReadCardManager	SDK证件识别主要类，单例模式，提供初始化和调用接口
ZRGKReadCardConfig	SDK初始化配置类，保存和传递配置参数
ZRGKIDCard	ZRGKIDCard

2）初始化SDK

NFC认证需要准备一些必要的数据，iOS客户端需要初始化和配置SDK相关参数,
如实例参考代码：

ZRGKReadCardConfig *config = [[ZRGKReadCardConfig alloc] init];
config.appId = @"ABCDEF888";

[ZRGKReadCardManager startWithConfig:config];

上述代码只需要 app 运行期间调用一次即可，放在调用识别证件接口之前。

3）配置参数说明

ZRGKReadCardConfig 类可配置的参数如下：

参数名称	类型	是否必传	参数说明
appId	NSString	必传	测试使用的appid不可用于商用(否则后果自负)，商用的appid请务必联系我司商务进行分配
ip	NSString	非必传	服务器IP(IP传空字符时，默认使用内置地址）
port	uint16_t	非必传	服务器端口号
cacheLastIDCardInfo	BOOL	非必传	缓存上一个身份证信息数据，默认为YES（连续识别同一个身份证信息时可以加快读取）
openLog	BOOL	非必传	默认为YES， 异常日志保存时间5天
logFolderPath	NSString	非必传	日志所在文件夹路径，默认为app沙盒路径 XXX/Library/Caches/ZRGKLogCache，可以指定到其他可可读写路径

添加备用服务端ip和端口地址可以使用下面方法（非必须）：

(void)addStandbyIp:(NSString *)ip port:(uint16_t)port;

4）调用SDK开始证件识别

ZRGKReadCardManager 接口说明：

返回单例对象

/// 返回默认单例对象
(ZRGKReadCardManager *)sharedManager;

初始化和配置

/// SDK 初始化
/// 返回的 error 为 nil 表示初始化成功，否则对照错误码检测传入参数
/// -Parameter config: 参数配置
(NSError *)startWithConfig:(ZRGKReadCardConfig *)config;

识别证件信息（包括证件照片信息）

/// 识别身份证、外国人居住证，并返回证件信息（包括证件照片信息）
/// - Parameters:
///   - successCall: 成功回调
///   - failCall: 失败回调
(void)readIDCardStart:(ZRGKOnReadIDCardSuccess)successCall 
                   fail:(ZRGKOnReadIDCardFail)failCall;

识别身份证、外国人居住证，仅返回不包括照片的证件信息

不需要照片信息场景下使用，加快解码速度

/// 识别身份证、外国人居住证，仅返回不包括照片的证件信息（不需要照片信息场景下使用，加快解码速度）
/// - Parameters:
///   - successCall: 成功回调
///   - failCall: 失败回调
(void)readIDCardWithoutImageStart:(ZRGKOnReadIDCardSuccess)successCall 
                               fail:(ZRGKOnReadIDCardFail)failCall;

识别身份证，并模拟生成身份证图片

/// 识别身份证，并生成身份证图片
/// - Parameters:
///   - successCall: 识别成功并生成图片成功回调
///   - failCall: 失败回调
 (void)readIDCardToImage:(ZRGKOnReadIDCardToImageSuccess)successCall 
                     fail:(ZRGKOnReadIDCardFail)failCall;

停止读卡

/// 停止读卡
(void)stopReadCard;

检测设备是否支持识别

/// 当前设备是否支持NFC
(BOOL)isNFCAvailable;

上传异常日志到SDK服务器

可协助客户排查异常

/// 执行上传异常日志
(void)uploadLog;

查看SDK版本号

(NSString *)sdkVersion;

5）接口相关参数和类型、回调结果说明

识别证件信息成功回调

typedef void(^ZRGKOnReadIDCardSuccess)(ZRGKIDCard * _Nonnull IDCard);

身份证详细信息

名称	类型	说明
type	ZRGKIDCardType	枚举类型ZRGKIDCardType_IDCARD=中国居民身份证
ID	NSString	身份证号码
sex	NSString	性别
startDate	NSString	身份证生效时间
endDate	NSString	身份证结束时间
imageData	NSData	照片原始信息
birthday	NSString	出生日期
name	NSString	姓名
nation	NSString	民族
address	NSString	家庭住址
issue	NSString	签发机关
dn	NSString	dn码
uid	NSString	身份证uid信息

外国人永久居住证信息：

名称	类型	说明
type	ZRGKIDCardType	枚举类型ZRGKIDCardType_IDCARD_FOREIGN=外国永久居住证
ID	NSString	证件号码
sex	NSString	性别
startDate	NSString	证件生效开始时间
endDate	NSString	证件生效结束时间
imageData	NSData	照片原始信息
birthday	NSString	出生日期
name	NSString	姓名
nation	NSString	民族
address	NSString	家庭住址
issue	NSString	签发机关
historicalNumber	NSString	既往版本证件号码关联项
nameEnglishAdd	NSString	英文姓名备用
nationlity	NSString	国籍
cardType	NSString	卡类型
dn	NSString	dn码
nameEnglish	NSString	英文姓名
nameChinese	NSString	中文姓名
renewalNumber	NSString	换证次数
cardVersion	NSString	卡版本号

识别身份证并模拟生成身份证图片成功回调

typedef void(^ZRGKOnReadIDCardToImageSuccess)(UIImage * _Nonnull idCardFront, UIImage * _Nonnull idCardBack);

其中：idCardFront 为正面图片，idCardBack 为背面图片

识别失败回调

typedef void(^ZRGKOnReadIDCardFail)(ZRGKSDKStateCode reasonCode, NSString * _Nullable erroMsg);

识别失败错误码说明

错误码定义为 ZRGKSDKStateCode 枚举类型，主要包括以下这些:

复制    /// 缺少 AppId 或传入 AppId 无效，不可用
    ZRGKSDKStateCode_AppIdInvalid   = 1002,
    /// 网络不可用
    ZRGKSDKStateCode_NetNoReachable,
    /// 其他初始化错误
    ZRGKSDKStateCode_InitFail,
    /// 当前手机或系统版本不支持
    ZRGKSDKStateCode_NOSupport,
    /// 用户取消
    ZRGKSDKStateCode_UserCancel,
    /// 检测失败，识别识别
    ZRGKSDKStateCode_DetectFail,
    /// 连接芯片失败
    ZRGKSDKStateCode_ConnectTagFail,
    /// 网络连接服务器失败
    ZRGKSDKStateCode_ConnectServerFail,
    /// 网络发送数据失败
    ZRGKSDKStateCode_SendToServerFail,
    /// 指令执行出错
    ZRGKSDKStateCode_InstructFail,
    /// 数据解析失败
    ZRGKSDKStateCode_DataParseFail,
    /// token失效
    ZRGKSDKStateCode_TokenExpire,
    /// 请求数据失败
    ZRGKSDKStateCode_RequestFail,
    /// 生成图片失败
    ZRGKSDKStateCode_GenerateImageFail,
    /// 生成图片类型不支持，只支持生成身份证类型
    ZRGKSDKStateCode_ImageTypeNoSupport,
    /// 其他异常
    ZRGKSDKStateCode_Other,