CLNFCAuthSDK 集成文档

目录

• 1. 概述
• 2. 环境要求
• 3. 集成方式
• 4. 工程配置
• 5. 初始化与使用
• 6. API 参考
• 7. 数据模型
• 8. 错误码
• 9. 常见问题

---

1. 概述

CLNFCAuthSDK 是一个基于 NFC 技术的证件读取 SDK，支持通过 iPhone NFC 功能读取身份证证件信息。

SDK 采用 静态库（Static Framework） 形式分发。

功能一览

---

2. 环境要求

重要：NFC 读取功能仅支持真机运行，模拟器不支持。

---

3. 集成方式

3.1 添加 SDK 文件

将以下文件/文件夹拷贝到宿主工程目录下：

复制成功⧉
CLNFCAuthSDK/
├── CLNFCAuthSDK.xcodeproj      # SDK 工程文件
└── CLNFCAuthSDK/
    ├── CLNFCAuthSDK.h           # 伞头文件
    ├── CLNFCReaderOC/           # 核心管理器
    ├── Config/                  # 配置类
    ├── Errors/                  # 错误定义
    ├── Models/                  # 数据模型
    ├── Utils/                   # 工具类
    └── ZRGKReadCardSDK.framework  # 底层静态库（必须一起携带）

3.2 Xcode 工程配置

步骤 1：添加工程引用

1. 在 Xcode 中，右键点击项目导航器中的根节点 → Add Files to "你的工程"...
2. 选择 CLNFCAuthSDK.xcodeproj，点击 Add

步骤 2：链接 Framework

在宿主 App Target → General → Frameworks, Libraries, and Embedded Content 中添加：

步骤 3：配置 Framework 搜索路径

在宿主 App Target → Build Settings → Framework Search Paths 中添加：

复制成功⧉
$(inherited)
$(PROJECT_DIR)/CLNFCAuthSDK/CLNFCAuthSDK

确保 ZRGKReadCardSDK.framework 所在目录被正确引用。

步骤 4：配置链接器标志（关键）

在宿主 App Target → Build Settings → Other Linker Flags 中添加：

复制成功⧉
-ObjC

必须添加：-ObjC 标志确保链接器加载静态库中所有 Objective-C 代码（包括 Category 方法）。缺少此标志会导致运行时崩溃（unrecognized selector sent to instance）。

---

4. 工程配置

4.1 NFC 能力配置

4.1.1 添加 Entitlements

在 Target → Signing & Capabilities → + Capability 中添加 NFC Tag Reading。

或手动编辑 .entitlements 文件：

复制成功⧉
<key>com.apple.developer.nfc.readersession.formats</key>
<array>
    <string>TAG</string>
</array>

4.1.2 Info.plist 配置

在 Info.plist 中添加以下配置项：

NFC 使用描述（必须）：

复制成功⧉
<key>NFCReaderUsageDescription</key>
<string>需要使用NFC读取证件信息</string>

ISO 7816 AID 标识（必须）：

复制成功⧉
<key>com.apple.developer.nfc.readersession.iso7816.select-identifiers</key>
<array>
    <string>F049442E43484E</string>
    <string>A0000002471001</string>
</array>

网络传输安全（如需 HTTP 通信）：

复制成功⧉
<key>NSAppTransportSecurity</key>
<dict>
    <key>NSAllowsArbitraryLoads</key>
    <true/>
</dict>

4.2 配置汇总清单

---

5. 初始化与使用

5.1 获取 Token

在调用 SDK 之前，需要先通过服务端接口获取 Token：

复制成功⧉
// 请求参数
NSString *appId = @"你的AppId";
NSString *appKey = @"你的AppKey";

// 生成32位随机请求ID
NSString *requestId = [self generateRandomString:32];

// 请求Token
NSString *url = @"https://wsapi.253.com/identity_auth/nfc/getToken";
NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:url]];
request.HTTPMethod = @"POST";
[request setValue:@"application/json" forHTTPHeaderField:@"Content-Type"];

NSDictionary *body = @{
    @"appId": appId,
    @"appKey": appKey,
    @"requestId": requestId
};
request.HTTPBody = [NSJSONSerialization dataWithJSONObject:body options:0 error:nil];

// 发送请求，解析 response[@"data"][@"token"]

5.2 初始化 SDK

复制成功⧉
#import <CLNFCAuthSDK/CLNFCAuthSDK.h>

// 初始化（在读取证件前调用）
NSError *error = [CLNFCReaderManager setupWithAppId:appId token:token];
if (error) {
    NSLog(@"SDK初始化失败：%@", error.localizedDescription);
    // 处理错误
}

// 可选：开启日志
[CLNFCReaderManager setLogEnabled:YES];

注意：appId 和 token 均不能为空字符串，否则初始化将失败。

5.3 检查 NFC 可用性

复制成功⧉
if (![CLNFCReaderManager isNFCAvailable]) {
    // 当前设备不支持 NFC
    UIAlertController *alert = [UIAlertController
        alertControllerWithTitle:@"提示"
                         message:@"该机型或当前系统不支持NFC读取功能"
                  preferredStyle:UIAlertControllerStyleAlert];
    [self presentViewController:alert animated:YES completion:nil];
    return;
}

5.4 读取身份证（含照片数据）

复制成功⧉
[CLNFCReaderManager readIDCardWithSuccess:^(CLNFCIDCardInfo *cardInfo) {
    NSLog(@"姓名：%@", cardInfo.name);
    NSLog(@"身份证号：%@", cardInfo.idNumber);
    NSLog(@"性别：%@", cardInfo.gender);
    NSLog(@"民族：%@", cardInfo.ethnicity);
    NSLog(@"出生日期：%@", cardInfo.birthday);
    NSLog(@"地址：%@", cardInfo.address);
    NSLog(@"签发机关：%@", cardInfo.issueAuthority);
    NSLog(@"有效期起：%@", cardInfo.validFrom);
    NSLog(@"有效期止：%@", cardInfo.validTo);

    // 照片原始数据
    if (cardInfo.photoData) {
        UIImage *photo = [UIImage imageWithData:cardInfo.photoData];
    }
} fail:^(NSError *error) {
    NSLog(@"读取失败：%@", error.localizedDescription);
}];

5.5 读取身份证（无照片，更快）

复制成功⧉
[CLNFCReaderManager readIDCardWithoutPhotoWithSuccess:^(CLNFCIDCardInfo *cardInfo) {
    NSLog(@"姓名：%@", cardInfo.name);
    NSLog(@"身份证号：%@", cardInfo.idNumber);
} fail:^(NSError *error) {
    NSLog(@"读取失败：%@", error.localizedDescription);
}];

5.6 读取身份证（生成正反面图片）

复制成功⧉
[CLNFCReaderManager readIDCardWithImagesSuccess:^(UIImage *frontImage, UIImage *backImage, CLNFCIDCardInfo *cardInfo) {
    // frontImage - 身份证正面图片
    // backImage  - 身份证背面图片

    // 保存图片到本地
    NSString *docsPath = [NSSearchPathForDirectoriesInDomains(NSDocumentDirectory, NSUserDomainMask, YES) firstObject];
    [UIImageJPEGRepresentation(frontImage, 0.9) writeToFile:[docsPath stringByAppendingPathComponent:@"IDCardFront.jpg"] atomically:YES];
    [UIImageJPEGRepresentation(backImage, 0.9) writeToFile:[docsPath stringByAppendingPathComponent:@"IDCardBack.jpg"] atomically:YES];
} fail:^(NSError *error) {
    NSLog(@"读取失败：%@", error.localizedDescription);
}];

5.7 停止读取

复制成功⧉
// 主动停止当前读取操作
[CLNFCReaderManager stopReading];

5.8 完整调用示例

复制成功⧉
#import <CLNFCAuthSDK/CLNFCAuthSDK.h>

@interface IDCardViewController ()
@property (nonatomic, copy) NSString *appId;
@property (nonatomic, copy) NSString *token;
@end

@implementation IDCardViewController

- (void)viewDidLoad {
    [super viewDidLoad];

    // 1. 开启日志（可选）
    [CLNFCReaderManager setLogEnabled:YES];

    // 2. 初始化 SDK
    NSError *error = [CLNFCReaderManager setupWithAppId:self.appId token:self.token];
    if (error) {
        [self showAlert:@"初始化失败" message:error.localizedDescription];
        return;
    }

    // 3. 检查 NFC 可用性
    if (![CLNFCReaderManager isNFCAvailable]) {
        [self showAlert:@"提示" message:@"该机型不支持NFC读取功能"];
        return;
    }
}

- (void)startReading {
    [CLNFCReaderManager readIDCardWithSuccess:^(CLNFCIDCardInfo *cardInfo) {
        dispatch_async(dispatch_get_main_queue(), ^{
            [self displayCardInfo:cardInfo];
        });
    } fail:^(NSError *error) {
        dispatch_async(dispatch_get_main_queue(), ^{
            [self handleError:error];
        });
    }];
}

- (void)handleError:(NSError *)error {
    NSString *message;
    switch (error.code) {
        case CLNFCReaderErrorCodeNetworkUnavailable:
            message = @"网络不可用，请检查网络连接";
            break;
        case CLNFCReaderErrorCodeNotSupported:
            message = @"当前设备不支持NFC";
            break;
        case CLNFCReaderErrorCodeUserCancelled:
            message = @"已取消读取";
            break;
        case CLNFCReaderErrorCodeTokenExpired:
            message = @"Token已失效，请重新获取";
            break;
        case CLNFCReaderErrorCodeImageTypeNotSupported:
            message = @"证件类型不支持，请使用身份证";
            break;
        default:
            message = error.localizedDescription;
            break;
    }
    [self showAlert:@"读取失败" message:message];
}

@end

---

6. API 参考

CLNFCReaderManager

SDK 核心管理类，所有方法均为类方法（无需实例化）。

初始化与配置

读取操作

回调类型定义

复制成功⧉
typedef void(^CLNFCReaderIDCardSuccess)(CLNFCIDCardInfo *cardInfo);
typedef void(^CLNFCReaderIDCardFail)(NSError *error);
typedef void(^CLNFCReaderIDCardImageSuccess)(UIImage *frontImage, UIImage *backImage, CLNFCIDCardInfo *cardInfo);

7. 错误码

错误域：com.nfcreaderkit.oc.error

错误处理示例

复制成功⧉
if (error.code == CLNFCReaderErrorCodeTokenExpired) {
    // Token 过期，需要重新从服务端获取
    [self refreshTokenAndRetry];
} else if (error.code == CLNFCReaderErrorCodeNetworkUnavailable) {
    // 提示用户检查网络
    [self showNetworkAlert];
} else if (error.code == CLNFCReaderErrorCodeUserCancelled) {
    // 用户主动取消，通常无需处理
}

---

9. 常见问题

Q1：运行时崩溃 unrecognized selector sent to instance

原因：缺少 -ObjC 链接器标志。静态库中的 Objective-C Category 方法不会被链接器自动加载。

解决：在宿主 App Target → Build Settings → Other Linker Flags 中添加 -ObjC。

Q2：编译通过但运行提示"该机型不支持NFC"

原因：模拟器不支持 NFC 功能。

解决：使用支持 NFC 的真机（iPhone 7 及以上）进行调试。

Q3：初始化返回 "appId 不能为空" 或 "token 不能为空"

原因：setupWithAppId:token: 的 appId 和 token 参数均不能为空字符串。

解决：确保传入有效的 appId 和 token。Token 需通过服务端接口获取。

Q4：读取时提示 "Token已失效"

原因：Token 具有时效性，过期后需要重新获取。

解决：捕获 CLNFCReaderErrorCodeTokenExpired 错误，重新请求 Token 后再次初始化。

Q5：包体积影响

使用静态库会将 SDK 代码编译进最终二进制文件，会一定程度增大包体积。-ObjC 标志会加载所有 ObjC 代码（包括未使用的 Category），这是保证功能正常的必要代价。

---

附录：工程配置快速检查表

集成完成后，请逐项确认以下配置：

• CLNFCAuthSDK.xcodeproj 已添加到工程
• 已链接 CLNFCAuthSDK.framework
• 已链接 ZRGKReadCardSDK.framework
• 已链接 libc++.tbd
• Framework Search Paths 包含 $(PROJECT_DIR)/CLNFCAuthSDK/CLNFCAuthSDK
• Other Linker Flags 包含 -ObjC
• 已开启 NFC Tag Reading Capability
• Info.plist 已配置 NFCReaderUsageDescription
• Info.plist 已配置 select-identifiers（F049442E43484E、A0000002471001）
• 使用真机调试（非模拟器）
• Deployment Target >= 12.0