iOS-NFC身份证云解码调用文档
<h1>概要说明</h1>
<p>iOS系统NFC相关API需要 13.0 系统以上，因此接入的APP运行环境只有iOS 13以上才能正常调用 SDK 提供的API。</p>
<p>如果 App支持 13.0 以下iOS系统版本，请在调用API之前判断系统版本号，屏蔽相关调用，否则将调用失败。
说明：iOS 接入不支持模拟器模式调试
本SDK 使用开发语言为 Objective-C</p>
<h1>配置开发环境</h1>
<h3>1. 在Xcode的编译环境设置中，选择Linking > Other Linker Flags，添加-ObjC。</h3>
<p><img src="http://" alt="Description" /></p>
<h3>2. 应用权限配置</h3>
<h4>1）登录苹果开发者管理平台，确认当前bundle ID下的NFC Tag Reading已经选中。</h4>
<h4>2）在项目工程的info.plist文件中添加Privacy - NFC Scan Usage Description和ISO7816 application identifiers for NFC Tag Reader Session，在item0中填写 F049442E43484E（身份证）。</h4>
<p><img src="http://imgsrc.baidu.com/forum/pic/item/377adab44aed2e7368435414c101a18b87d6fa65.jpg" alt="Description" />
<img src="http://imgsrc.baidu.com/forum/pic/item/e824b899a9014c089fb7fa9d4c7b02087bf4f47f.jpg" alt="Description" /></p>
<h4>3）在Xcode中，选择TARGETS > Signing&Capabilities > All，添加Near Field Communication Tag Reading。</h4>
<p><img src="http://imgsrc.baidu.com/forum/pic/item/562c11dfa9ec8a139e9285d8b103918fa0ecc07b.jpg" alt="Description" /></p>
<h1>配置依赖</h1>
<h2>1）导入iOS SDK</h2>
<p>该 SDK 为 framework 包：<code>ZRGKReadCardSDK.framework</code>。</p>
<h2>2）添加库依赖</h2>
<p>在Build Phases > Link Binary With Libraries中，添加以下系统库依赖：<code>libc++.tbd</code></p>
<h1>调用SDK</h1>
<h2>1）引入头文件</h2>
<pre><code>#import &lt;ZRGKReadCardSDK/ZRGKReadCardSDK.h&gt;</code></pre>
<h4>SDK包含的文件说明：</h4>
<table>
<thead>
<tr>
<th style="text-align: left;">类名/文件名</th>
<th style="text-align: left;">说明</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align: left;">ZRGKReadCardSDK.h</td>
<td style="text-align: left;">ZRGKReadCardSDK.h</td>
</tr>
<tr>
<td style="text-align: left;">ZRGKReadCardManager</td>
<td style="text-align: left;">SDK证件识别主要类，单例模式，提供初始化和调用接口</td>
</tr>
<tr>
<td style="text-align: left;">ZRGKReadCardConfig</td>
<td style="text-align: left;">SDK初始化配置类，保存和传递配置参数</td>
</tr>
<tr>
<td style="text-align: left;">ZRGKIDCard</td>
<td style="text-align: left;">ZRGKIDCard</td>
</tr>
</tbody>
</table>
<h2>2）初始化SDK</h2>
<p>NFC认证需要准备一些必要的数据，iOS客户端需要初始化和配置SDK相关参数,
如实例参考代码：</p>
<pre><code>ZRGKReadCardConfig *config = [[ZRGKReadCardConfig alloc] init];
config.appId = @&quot;ABCDEF888&quot;;
[ZRGKReadCardManager startWithConfig:config];</code></pre>
<p>上述代码只需要 app 运行期间调用一次即可，放在调用识别证件接口之前。</p>
<h2>3）配置参数说明</h2>
<h4>ZRGKReadCardConfig 类可配置的参数如下：</h4>
<table>
<thead>
<tr>
<th style="text-align: left;">参数名称</th>
<th style="text-align: left;">类型</th>
<th style="text-align: left;">是否必传</th>
<th style="text-align: left;">参数说明</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align: left;">appId</td>
<td style="text-align: left;">NSString</td>
<td style="text-align: left;">必传</td>
<td style="text-align: left;">测试使用的appid不可用于商用(否则后果自负)，商用的appid请务必联系我司商务进行分配</td>
</tr>
<tr>
<td style="text-align: left;">ip</td>
<td style="text-align: left;">NSString</td>
<td style="text-align: left;">非必传</td>
<td style="text-align: left;">服务器IP(IP传空字符时，默认使用内置地址）</td>
</tr>
<tr>
<td style="text-align: left;">port</td>
<td style="text-align: left;">uint16_t</td>
<td style="text-align: left;">非必传</td>
<td style="text-align: left;">服务器端口号</td>
</tr>
<tr>
<td style="text-align: left;">cacheLastIDCardInfo</td>
<td style="text-align: left;">BOOL</td>
<td style="text-align: left;">非必传</td>
<td style="text-align: left;">缓存上一个身份证信息数据，默认为YES（连续识别同一个身份证信息时可以加快读取）</td>
</tr>
<tr>
<td style="text-align: left;">openLog</td>
<td style="text-align: left;">BOOL</td>
<td style="text-align: left;">非必传</td>
<td style="text-align: left;">默认为YES， 异常日志保存时间5天</td>
</tr>
<tr>
<td style="text-align: left;">logFolderPath</td>
<td style="text-align: left;">NSString</td>
<td style="text-align: left;">非必传</td>
<td style="text-align: left;">日志所在文件夹路径，默认为app沙盒路径 XXX/Library/Caches/ZRGKLogCache，可以指定到其他可可读写路径</td>
</tr>
</tbody>
</table>
<p>添加备用服务端ip和端口地址可以使用下面方法（非必须）：</p>
<pre><code>(void)addStandbyIp:(NSString *)ip port:(uint16_t)port;</code></pre>
<h2>4）调用SDK开始证件识别</h2>
<h3>ZRGKReadCardManager 接口说明：</h3>
<h4>返回单例对象</h4>
<pre><code>/// 返回默认单例对象
(ZRGKReadCardManager *)sharedManager;</code></pre>
<h4>初始化和配置</h4>
<pre><code>/// SDK 初始化
/// 返回的 error 为 nil 表示初始化成功，否则对照错误码检测传入参数
/// -Parameter config: 参数配置
(NSError *)startWithConfig:(ZRGKReadCardConfig *)config;</code></pre>
<h4>识别证件信息（包括证件照片信息）</h4>
<pre><code>/// 识别身份证、外国人居住证，并返回证件信息（包括证件照片信息）
/// - Parameters:
/// - successCall: 成功回调
/// - failCall: 失败回调
(void)readIDCardStart:(ZRGKOnReadIDCardSuccess)successCall
fail:(ZRGKOnReadIDCardFail)failCall;</code></pre>
<h4>识别身份证、外国人居住证，仅返回不包括照片的证件信息</h4>
<p>不需要照片信息场景下使用，加快解码速度</p>
<pre><code>/// 识别身份证、外国人居住证，仅返回不包括照片的证件信息（不需要照片信息场景下使用，加快解码速度）
/// - Parameters:
/// - successCall: 成功回调
/// - failCall: 失败回调
(void)readIDCardWithoutImageStart:(ZRGKOnReadIDCardSuccess)successCall
fail:(ZRGKOnReadIDCardFail)failCall;</code></pre>
<h4>识别身份证，并模拟生成身份证图片</h4>
<pre><code>/// 识别身份证，并生成身份证图片
/// - Parameters:
/// - successCall: 识别成功并生成图片成功回调
/// - failCall: 失败回调
(void)readIDCardToImage:(ZRGKOnReadIDCardToImageSuccess)successCall
fail:(ZRGKOnReadIDCardFail)failCall;</code></pre>
<h4>停止读卡</h4>
<pre><code>/// 停止读卡
(void)stopReadCard;</code></pre>
<h4>检测设备是否支持识别</h4>
<pre><code>/// 当前设备是否支持NFC
(BOOL)isNFCAvailable;</code></pre>
<h4>上传异常日志到SDK服务器</h4>
<p>可协助客户排查异常</p>
<pre><code>/// 执行上传异常日志
(void)uploadLog;</code></pre>
<h4>查看SDK版本号</h4>
<pre><code>(NSString *)sdkVersion;</code></pre>
<h2>5）接口相关参数和类型、回调结果说明</h2>
<h3>识别证件信息成功回调</h3>
<pre><code>typedef void(^ZRGKOnReadIDCardSuccess)(ZRGKIDCard * _Nonnull IDCard);</code></pre>
<h3>身份证详细信息</h3>
<table>
<thead>
<tr>
<th style="text-align: left;">名称</th>
<th style="text-align: left;">类型</th>
<th>说明</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align: left;">type</td>
<td style="text-align: left;">ZRGKIDCardType</td>
<td>枚举类型ZRGKIDCardType_IDCARD=中国居民身份证</td>
</tr>
<tr>
<td style="text-align: left;">ID</td>
<td style="text-align: left;">NSString</td>
<td>身份证号码</td>
</tr>
<tr>
<td style="text-align: left;">sex</td>
<td style="text-align: left;">NSString</td>
<td>性别</td>
</tr>
<tr>
<td style="text-align: left;">startDate</td>
<td style="text-align: left;">NSString</td>
<td>身份证生效时间</td>
</tr>
<tr>
<td style="text-align: left;">endDate</td>
<td style="text-align: left;">NSString</td>
<td>身份证结束时间</td>
</tr>
<tr>
<td style="text-align: left;">imageData</td>
<td style="text-align: left;">NSData</td>
<td>照片原始信息</td>
</tr>
<tr>
<td style="text-align: left;">birthday</td>
<td style="text-align: left;">NSString</td>
<td>出生日期</td>
</tr>
<tr>
<td style="text-align: left;">name</td>
<td style="text-align: left;">NSString</td>
<td>姓名</td>
</tr>
<tr>
<td style="text-align: left;">nation</td>
<td style="text-align: left;">NSString</td>
<td>民族</td>
</tr>
<tr>
<td style="text-align: left;">address</td>
<td style="text-align: left;">NSString</td>
<td>家庭住址</td>
</tr>
<tr>
<td style="text-align: left;">issue</td>
<td style="text-align: left;">NSString</td>
<td>签发机关</td>
</tr>
<tr>
<td style="text-align: left;">dn</td>
<td style="text-align: left;">NSString</td>
<td>dn码</td>
</tr>
<tr>
<td style="text-align: left;">uid</td>
<td style="text-align: left;">NSString</td>
<td>身份证uid信息</td>
</tr>
</tbody>
</table>
<h3>外国人永久居住证信息：</h3>
<table>
<thead>
<tr>
<th style="text-align: left;">名称</th>
<th style="text-align: left;">类型</th>
<th>说明</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align: left;">type</td>
<td style="text-align: left;">ZRGKIDCardType</td>
<td>枚举类型ZRGKIDCardType_IDCARD_FOREIGN=外国永久居住证</td>
</tr>
<tr>
<td style="text-align: left;">ID</td>
<td style="text-align: left;">NSString</td>
<td>证件号码</td>
</tr>
<tr>
<td style="text-align: left;">sex</td>
<td style="text-align: left;">NSString</td>
<td>性别</td>
</tr>
<tr>
<td style="text-align: left;">startDate</td>
<td style="text-align: left;">NSString</td>
<td>证件生效开始时间</td>
</tr>
<tr>
<td style="text-align: left;">endDate</td>
<td style="text-align: left;">NSString</td>
<td>证件生效结束时间</td>
</tr>
<tr>
<td style="text-align: left;">imageData</td>
<td style="text-align: left;">NSData</td>
<td>照片原始信息</td>
</tr>
<tr>
<td style="text-align: left;">birthday</td>
<td style="text-align: left;">NSString</td>
<td>出生日期</td>
</tr>
<tr>
<td style="text-align: left;">name</td>
<td style="text-align: left;">NSString</td>
<td>姓名</td>
</tr>
<tr>
<td style="text-align: left;">nation</td>
<td style="text-align: left;">NSString</td>
<td>民族</td>
</tr>
<tr>
<td style="text-align: left;">address</td>
<td style="text-align: left;">NSString</td>
<td>家庭住址</td>
</tr>
<tr>
<td style="text-align: left;">issue</td>
<td style="text-align: left;">NSString</td>
<td>签发机关</td>
</tr>
<tr>
<td style="text-align: left;">historicalNumber</td>
<td style="text-align: left;">NSString</td>
<td>既往版本证件号码关联项</td>
</tr>
<tr>
<td style="text-align: left;">nameEnglishAdd</td>
<td style="text-align: left;">NSString</td>
<td>英文姓名备用</td>
</tr>
<tr>
<td style="text-align: left;">nationlity</td>
<td style="text-align: left;">NSString</td>
<td>国籍</td>
</tr>
<tr>
<td style="text-align: left;">cardType</td>
<td style="text-align: left;">NSString</td>
<td>卡类型</td>
</tr>
<tr>
<td style="text-align: left;">dn</td>
<td style="text-align: left;">NSString</td>
<td>dn码</td>
</tr>
<tr>
<td style="text-align: left;">nameEnglish</td>
<td style="text-align: left;">NSString</td>
<td>英文姓名</td>
</tr>
<tr>
<td style="text-align: left;">nameChinese</td>
<td style="text-align: left;">NSString</td>
<td>中文姓名</td>
</tr>
<tr>
<td style="text-align: left;">renewalNumber</td>
<td style="text-align: left;">NSString</td>
<td>换证次数</td>
</tr>
<tr>
<td style="text-align: left;">cardVersion</td>
<td style="text-align: left;">NSString</td>
<td>卡版本号</td>
</tr>
</tbody>
</table>
<h3>识别身份证并模拟生成身份证图片成功回调</h3>
<pre><code>typedef void(^ZRGKOnReadIDCardToImageSuccess)(UIImage * _Nonnull idCardFront, UIImage * _Nonnull idCardBack);</code></pre>
<p>其中：idCardFront 为正面图片，idCardBack 为背面图片</p>
<h3>识别失败回调</h3>
<pre><code>typedef void(^ZRGKOnReadIDCardFail)(ZRGKSDKStateCode reasonCode, NSString * _Nullable erroMsg);</code></pre>
<h3>识别失败错误码说明</h3>
<h4>错误码定义为 ZRGKSDKStateCode 枚举类型，主要包括以下这些:</h4>
<pre><code> /// 缺少 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,</code></pre>
<h1>SDK Demo文件</h1>
<p>参见具体附带 demo 代码文件</p>