业务安全风控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文档