IOS安全SDK使用文档
更新时间：2020-05-12
1. 背景
为了使业务方移动端iOS应用能更便捷的整合端上安全能力，确保服务端接入安全业务的质量，业务方需要集成iOS安全SDK。
2. 项目工程集成SDK方式
安全SDK以静态库的形式分发，解压后按照以下步骤集成到项目工程中:
- 将libSSDKLib.a、SSDKLib.h添加进工程。
- 设置【Other Linker Flags】选项为-ObjC标识
- 在【Build Phases】的【Link Binary With Libraries】中添加1个系统库libz.tbd
注意事项
iOS安全SDK静态库只包含ARMv7/ARMv7s/ARM64架构，不支持模拟器x86架构。如果宿主集成安全SDK后需要生成x86架构程序，可在调用安全SDK接口前加入以下预编译宏，避免在模拟器x86架构中引入安全SDK:
// Objective-C 使用
#if !(TARGET_OS_SIMULATOR)
// 调用安全SDK接口
#endif
// Swift 使用
#if !(arch(i386) || arch(x86_64))
// 调用安全SDK接口
#endif3. 业务方调用安全SDK流程
3.1 申请产品信息
调用前，业务方必须申请AppKey和SecretKey，用于初始化接口。
- (void)startSDKEngineWithDeviceID:(NSString *)deviceID
appKey:(NSString *)appKey
secretKey:(NSString *)secretKey
ZInfoReadyHandler:(void (^)(NSError *error))ZInfoReadyHandler;3.2 启动SDK
在AppDelegate文件中的didFinishLaunchingWithOptions方法中，尽可能靠前启动安全SDK，传入申请的产品信息，同时注册callback block。安全SDK初始化完成后，会调用callback block。
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
...
SSDKLightLib *lib = [SSDKLightLib sharedInstance];
[lib startSDKEngineWithDeviceID:@"device_id_example"
appKey:@"app_key_example"
secretKey:@"secrite_key_example"
ZInfoReadyHandler:^(NSError *error) {
}];
...
return YES;
}3.3 获取ztoken
业务线App需要调用获取ztoken接口得到ztoken，同时接口中需要传入EventID和AccountID。AccountID代表业务线的用户ID，用于后续业务线和安全服务打通使用。
4. 主要接口说明
4.1 获取SDK实例对象接口
接口描述
+ (id)sharedInstance;用于获取安全SDK的单一实例对象，后续接口通过该实例对象调用。
参数说明
无
返回值说明
安全SDK单一实例对象
4.2 初始化安全SDK接口
安全SDK进行初始化时，请直接调用此接口。
接口描述：
- (void)startSDKEngineWithDeviceID:(NSString *)deviceID
appKey:(NSString *)appKey
secretKey:(NSString *)secretKey
ZInfoReadyHandler:(void (^)(NSError *error))ZInfoReadyHandler;参数说明
- deviceID: 业务方使用的唯一设备标识（业务方对该设备的描述）；
- appKey: 宿主App申请的5位appKey；
- secretKey: 宿主App申请的32位secretKey；
- ZInfoReadyHandler: 业务方为安全SDK提供的回调函数，该函数被调用时，如果error为nil则意味着获取ztoken接口可以正确返回。如果error为非nil（出现概率极低），则意味着后续获取ztoken接口接口会返回默认错误值。
注意事项
- appKey与secretKey需要在接入前向安全SDK申请，否则相关服务不可用；
- 回调函数只会至多被调用一次；
- 为确保打通服务的ztoken质量，安全SDK会在状态就绪后第一时间回调ZInfoReadyHandler ；网络异常等特殊情况下，该回调函数会被延迟调起。
4.3 获取ztoken接口
接口描述
- (NSDictionary *)getZInfoWithEvent:(NSDictionary *)eventInfo在业务方特定事件／场景（如支付、登录、参加运营活动等事件）发生时，通过此接口获取当前有效ztoken，立即上传至服务端，服务端利用ztoken接入安全SDK服务对该设备风险进行评估。
参数说明
eventInfo字典用于区分业务方不同的事件或场景，“Key-Value”遵循以下格式:
| Key | Value Type | 示例 | 说明 |
|---|---|---|---|
| kSSDKEventIdentifier | NSString* | @"3048" | 预先申请的eventID，对应当前获取ztoken的场景 |
| kSSDKAccountIdentifier | NSString* | @"10538532" | 当前登陆用户的唯一标识 |
示例代码如下：
- (void)onUserPaymentEvent() { // 特定事件触发
/* 准备参数 */
NSString *eventID = @"3048"; //事先申请的事件标识字符串
NSString *accountID = @"10538532"; //当前用户的唯一标识
NSDictionary *eventInfo = @{
kSSDKEventIdentifier: eventID,
kSSDKAccountIdentifier: accountID
};
/* 获取ztoken */
SSDKLightLib ssdk = [SSDKLightLib sharedInstance];
NSDictionary *ZInfo = [ssdk getZInfoWithEvent:eventInfo];
NSString *ztoken = [ZInfo valueForKey:kSSDKZToken];
/*
* 正常情况下ztoken为BASE64字符串，例如：
* uSLPqWj2s-8QZ3auiig1MDK4pdPdg5YAkvGdclfynhUqAFGtV7hlXfKeZ2uZswTeXSqQqv4dErXyvCpbcKU8ufw
*/
...
}返回值说明
调用返回ZInfo字典，ZInfo中kSSDKZToken对应的value为ztoken。ZInfo的格式如下图所示，可能的返回值见示例代码。
| Key | Value Type | 示例 | 说明 |
|---|---|---|---|
| kSSDKZToken | NSString* | 见示例代码 | ztoken |