ios安全sdk使用文档 -奇异果体育app竞彩官网下载

1. 背景

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

此文档用于haotian版本。

2. 项目工程集成sdk方式

2.1 集成sdk

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

1. 将libssdklib_haotian.a、hsdklib.h添加进工程。
2. 设置【other linker flags】选项为-objc标识

3. 在【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接口，获取后需要立即向服务端发起请求。

注意事项

1. 确保获取ztoken接口调用之前，已经调用了初始化安全sdk接口；
2. ztoken具有时效性，业务方客户端每次上报前务必重新调用获取ztoken接口， 获取当前最新的ztoken，业务方避免将ztoken写入cookie；
3. 避免将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。

错误使用案例：

1. 启动安全sdk的逻辑依赖业务其他逻辑配置，由于业务逻辑配置（受环境或其他影响）无法正常运转导致部分场景没有启动安全sdk，大量设备获取到错误token；
2. 没有及时启动安全sdk，并且不等启动sdk的方法callback回调完成，就开始调用获取ztoken接口，此时可能大量获取到错误状态的ztoken

4.2 ztoken禁止缓存处理

因为ztoken有时效性，而且可能会因为客户端某些状态的变化实时发生变化，使用时必须确保“每次发送给服务端前，立即调用一次接口获取最新ztoken，不要使用缓存的ztoken”

如果有接入h5活动页面需要使用ztoken接入风控系统，需要在本地建立jsbridge，结合jssdk实时获取native的安全sdk中的ztoken。

错误使用案例：

1. 启动后获取一次ztoken缓存起来，后续不再获取，只用这一个，没有每次发送前重新获取；
2. h5活动页使用时，依赖native之前获取到放到cookie中的ztoken，没有每次发送前重新获取。

4.3 ztoken使用场景

只有当企业app进行关键活动和行为时才获取ztoken，并且只有关键活动和行为触发的客户端请求才能携带ztoken，业务方服务端在收到ztoken后，用此ztoken进行风控查询。

注意事项

1. 业务方避免将ztoken写入cookie；
2. 避免将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;

参数说明

1. deviceid: 业务方使用的唯一设备标识（业务方对该设备的描述）；
2. appkey: 宿主app申请的5位appkey；
3. secretkey: 宿主app申请的32位secretkey；
4. zinforeadyhandler: 业务方为安全sdk提供的回调函数，该函数被调用时，如果error为nil则意味着获取ztoken接口可以正确返回。如果error为非nil（出现概率极低），则意味着后续获取ztoken接口接口会返回默认错误值。

关于回调函数 zinforeadyhandler

初始化安全sdk接口为非阻塞操作，调用后会立即返回；安全sdk通过异步回调的机制（zinforeadyhandler）通知业务方，安全sdk内部状态准备就绪，业务方可以开始调用获取ztoken接口。”

注意事项

1. appkey与secretkey需要在接入前向安全sdk申请，否则相关服务不可用；
2. 回调函数只会至多被调用一次；
3. 为确保打通服务的ztoken质量，安全sdk会在状态就绪后第一时间回调zinforeadyhandler ；网络异常等特殊情况下，该回调函数会被延迟调起。

5.3 native获取ztoken接口

业务方native需要获取ztoken接口时使用。

接口描述

- (nsdictionary *)getzinfowithevent:(nsdictionary *)eventinfo

在业务方特定事件／场景（如支付、登录、参加运营活动等事件）发生时，通过此接口获取当前有效ztoken，立即上传至服务端，服务端利用ztoken接入安全sdk服务对该设备风险进行评估。

参数说明

eventinfo字典用于区分业务方不同的事件或场景，“key-value”遵循以下格式:

示例代码如下：

- (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的格式如下图所示，可能的返回值见示例代码。

正常返回值为base64 code string （长度小于100字节）

5.4 js获取ztoken接口

企业的h5活动页通过js获取ztoken时需要调用此接口。

接口描述

- (nsdictionary *)getzinfowithbridgeevent:(nsdictionary *)paramdict;

当企业在html5页面发生特定事件／场景（如支付、登录、参加运营活动等事件）时，页面中的js通过宿主实现的wrapper调用此接口获取当前有效ztoken，服务端利用ztoken接入安全sdk服务对该设备风险进行评估。

参数说明

paramdict字典必须满足以下key-value组合：

返回值说明

返回值为nsdictionary，包含以下key-value组合：