IOS安全SDK使用文档
所有文档

          业务安全风控 AFD

          IOS安全SDK使用文档

          1. 背景

          为了使业务方移动端iOS应用能更便捷的整合端上安全能力,确保服务端接入安全业务的质量,业务方需要集成iOS安全SDK。

          2. 项目工程集成SDK方式

          安全SDK以静态库的形式分发,解压后按照以下步骤集成到项目工程中:

          1. 将libSSDKLib.a、SSDKLib.h添加进工程。
          2. 设置【Other Linker Flags】选项为-ObjC标识
          3. 在【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接口
          #endif

          3. 业务方调用安全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;

          参数说明

          1. deviceID: 业务方使用的唯一设备标识(业务方对该设备的描述);
          2. appKey: 宿主App申请的5位appKey;
          3. secretKey: 宿主App申请的32位secretKey;
          4. ZInfoReadyHandler: 业务方为安全SDK提供的回调函数,该函数被调用时,如果error为nil则意味着获取ztoken接口可以正确返回。如果error为非nil(出现概率极低),则意味着后续获取ztoken接口接口会返回默认错误值。

          注意事项

          1. appKey与secretKey需要在接入前向安全SDK申请,否则相关服务不可用;
          2. 回调函数只会至多被调用一次;
          3. 为确保打通服务的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
          上一篇
          反爬服务JS-SDK使用文档
          下一篇
          Android安全SDK文档