IOS安全SDK使用文档
1. 背景
为了使企业移动端iOS应用能更便捷的整合端上安全能力,确保服务端接入安全业务的质量,企业需要集成iOS安全SDK。
此文档用于Haotian版本。
2. 项目工程集成SDK方式
2.1 集成SDK
安全SDK以静态库的形式分发,解压后按照以下步骤集成到项目工程中:
- 将libSSDKLib_Haotian.a、HSDKLib.h添加进工程。
- 设置【Other Linker Flags】选项为-ObjC标识
-
在【Build Phases】的【Link Binary With Libraries】中添加系统库:
- libz.tbd
- libc++.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接口
#endif
3. 业务方调用安全SDK流程
3.1 申请产品信息
调用前,企业可通过百度智能云-昊天镜业务安全风控AFD控制台中,上传应用,申请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 {
...
HSDKLib *lib = [HSDKLib 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,但是建议优先调用startSDKEngineWithDeviceID接口进行SDK启动。
同时接口中需要传入EventID和AccountID。AccountID代表企业的用户ID,用于后续企业和安全服务打通使用。EventID请参考下面3.4。
获取ztoken接口结合接入的服务和场景来选择接口获取ztoken:
- H5页面获取ztoken需要通过bridge调用native接口getZInfoWithBridgeEvent 获取。
- Native直接获取ztoken需要调用getZInfoWithEvent接口,获取后需要立即向服务端发起请求。
注意事项
- 确保获取ztoken接口调用之前,已经调用了初始化安全SDK接口;
- ztoken具有时效性,业务方客户端每次上报前务必重新调用获取ztoken接口, 获取当前最新的ztoken,业务方避免将ztoken写入Cookie;
- 避免将ztoken发送到和使用ztoken无关的服务流量中。
3.4 确认EventID使用场景
EventID代表事件行为标识,用于调用获取ztoken接口获取ztoken信息时的必传参数,放在参数NSDictionary中,key为kSSDKEventIdentifier_HS,value为字符串3300~3400,根据业务可自行选择传入。
4. 使用SDK注意事项(非常重要)
为确保安全SDK相关接口使用正确,能够正确获取有效ztoken,以及提高后续进行风控接口查询结果的准确性,需要注意以下几点。
4.1 确保第一时间启动SDK
企业App集成安全SDK后,在启动过程中,需要将安全SDK的启动接口调用尽可能前置。
安全SDK启动接口被调用后,SDK的启动过程不会block当前线程,SDK启动完毕后通过callback回调通知业务逻辑初始化完毕,此时可以获取到当前最新的有效ztoken。
错误使用案例:
- 启动安全SDK的逻辑依赖业务其他逻辑配置,由于业务逻辑配置(受环境或其他影响)无法正常运转导致部分场景没有启动安全SDK,大量设备获取到错误token;
- 没有及时启动安全SDK,并且不等启动SDK的方法callback回调完成,就开始调用获取ztoken接口,此时可能大量获取到错误状态的ztoken
4.2 ztoken禁止缓存处理
因为ztoken有时效性,而且可能会因为客户端某些状态的变化实时发生变化,使用时必须确保“每次发送给服务端前,立即调用一次接口获取最新ztoken,不要使用缓存的ztoken”
如果有接入H5活动页面需要使用ztoken接入风控系统,需要在本地建立JSBridge,结合JSSDK实时获取Native的安全SDK中的ztoken。
错误使用案例:
- 启动后获取一次ztoken缓存起来,后续不再获取,只用这一个,没有每次发送前重新获取;
- H5活动页使用时,依赖Native之前获取到放到cookie中的ztoken,没有每次发送前重新获取。
4.3 ztoken使用场景
只有当企业App进行关键活动和行为时才获取ztoken,并且只有关键活动和行为触发的客户端请求才能携带ztoken,业务方服务端在收到ztoken后,用此ztoken进行风控查询。
注意事项
- 业务方避免将ztoken写入Cookie;
- 避免将ztoken发送到和使用ztoken无关的服务流量中。
5. 主要接口说明
5.1 获取SDK实例对象接口
接口描述
+ (id)sharedInstance;
用于获取安全SDK的单一实例对象,后续接口通过该实例对象调用。
参数说明
无
返回值说明
安全SDK单一实例对象
5.2 初始化安全SDK接口
安全SDK进行初始化时,请直接调用此接口。
接口描述:
- (void)startSDKEngineWithDeviceID:(NSString *)deviceID
appKey:(NSString *)appKey
secretKey:(NSString *)secKey
ZInfoReadyHandler:(void (^)(NSError *error))ZInfoReadyHandler;
参数说明
- deviceID: 业务方使用的唯一设备标识(业务方对该设备的描述);
- appKey: 宿主App申请的5位appKey;
- secretKey: 宿主App申请的32位secretKey;
- ZInfoReadyHandler: 业务方为安全SDK提供的回调函数,该函数被调用时,如果error为nil则意味着获取ztoken接口可以正确返回。如果error为非nil(出现概率极低),则意味着后续获取ztoken接口接口会返回默认错误值。
关于回调函数 ZInfoReadyHandler
初始化安全SDK接口为非阻塞操作,调用后会立即返回;安全SDK通过异步回调的机制(ZInfoReadyHandler)通知业务方,安全SDK内部状态准备就绪,业务方可以开始调用获取ztoken接口。”
注意事项
- appKey与secretKey需要在接入前向安全SDK申请,否则相关服务不可用;
- 回调函数只会至多被调用一次;
- 为确保打通服务的ztoken质量,安全SDK会在状态就绪后第一时间回调ZInfoReadyHandler ;网络异常等特殊情况下,该回调函数会被延迟调起。
5.3 Native获取ztoken接口
业务方Native需要获取ztoken接口时使用。
接口描述
- (NSDictionary *)getZInfoWithEvent:(NSDictionary *)eventInfo
在业务方特定事件/场景(如支付、登录、参加运营活动等事件)发生时,通过此接口获取当前有效ztoken,立即上传至服务端,服务端利用ztoken接入安全SDK服务对该设备风险进行评估。
参数说明
eventInfo字典用于区分业务方不同的事件或场景,“Key-Value”遵循以下格式:
Key | Value Type | 示例 | 说明 |
---|---|---|---|
kSSDKEventIdentifier_HS | NSString* | @"3348" | 预先申请的eventID,对应当前获取ztoken的场景 |
kSSDKAccountIdentifier_HS | NSString* | @"10538532" | 当前登录用户的唯一标识 |
示例代码如下:
- (void)onUserPaymentEvent() { // 特定事件触发
/* 准备参数 */
NSString *eventID = @"3348"; //事先申请的事件标识字符串
NSString *accountID = @"10538532"; //当前用户的唯一标识
NSDictionary *eventInfo = @{
kSSDKEventIdentifier_HS: eventID,
kSSDKAccountIdentifier_HS: accountID
};
/* 获取ztoken */
id ssdk = [SSDKLib sharedInstance];
NSDictionary *ZInfo = [ssdk getZInfoWithEvent:eventInfo];
NSString *ztoken = [ZInfo valueForKey:kSSDKZToken_HS];
/*
* 正常情况下ztoken为BASE64字符串,例如:
* uSLPqWj2s-8QZ3auiig1MDK4pdPdg5YAkvGdclfynhUqAFGtV7hlXfKeZ2uZswTeXSqQqv4dErXyvCpbcKU8ufw
*/
...
}
返回值说明
调用返回ZInfo字典,ZInfo中kSSDKZToken_HS对应的value为ztoken。ZInfo的格式如下图所示,可能的返回值见示例代码。
Key | Value Type | 示例 | 说明 |
---|---|---|---|
kSSDKZToken_HS | NSString* | 见示例代码 | ztoken |
正常返回值为base64 code string (长度小于100字节)
5.4 JS获取ztoken接口
企业的H5活动页通过JS获取ztoken时需要调用此接口。
接口描述
- (NSDictionary *)getZInfoWithBridgeEvent:(NSDictionary *)paramDict;
当企业在HTML5页面发生特定事件/场景(如支付、登录、参加运营活动等事件)时,页面中的JS通过宿主实现的Wrapper调用此接口获取当前有效ztoken,服务端利用ztoken接入安全SDK服务对该设备风险进行评估。
参数说明
paramDict字典必须满足以下Key-Value组合:
Key | Value Type | 说明 |
---|---|---|
@"js" | json string | H5活动页JS传入的参数 |
@"url" | string | native获取活动页面的URL |
@"c" | string | native获取的CUID |
@"a" | string | native获取的UID |
返回值说明
返回值为NSDictionary,包含以下Key-Value组合:
Key | Value Type | 说明 |
---|---|---|
z | NSString* | ztoken |