iOS SDK_全域采集与增长分析(Quick Tracking)-阿里云帮助中心

使用QuickTracking iOS（A/B Testing）必备操作。

SDK基本信息

文件名称

版本号

md5

文件大小

QuickTracking ABTest SDK

1.2.1

更新日志：iOS/macOS SDK更新日志

0527d565add41055717116ed496153fd

905 KB

1.集成代码明细

A/B Testing SDK 依赖iOS SDKv1.6.0及以上版本，在使用前请确保已经成功集成QuickTracking 统计SDK，并进行了SDK初始化，详情可参考引入&配置SDK。

2.编程实验

2.1集成与初始化SDK

首先您需要使用同步方式初始化QuickTracking 统计SDK。初始化QuickTracking 统计SDK 完成之后，再初始化QuickTracking A/B Testing SDK。在QuickTracking A/B Testing SDK 初始化时需要传入请求分流试验的地址，请联系运营人员获取。

集成QuickTracking SDK

CocoaPods 方式（推荐）

在Podfile 文件中添加
```
pod 'QTABTest'
```
打开终端，切换到项目目录
执行 pod install 或者 pod update
如果拉取不到最新版本，先执行 pod repo update，再执行pod install 或者 pod update

手动集成

请联系QuickTracking产品运营同学获取QTABTest SDK离线包：QTABTestSDK.xcframework文件。

工程配置

添加QTABTestSDK.xcframework文件到应用工程

SDK初始化

/** 初始化QuickTracking ABTest iOS SDK
 @param configOptions 初始化配置
 */
+ (void)startWithConfigOptions:(QTABTestConfigOptions *)configOptions;

QTABTestConfigOptions类

#import <Foundation/Foundation.h>

typedef void (^OnABTestPropertyChangedBlock)(NSArray * _Nonnull result);

NS_ASSUME_NONNULL_BEGIN

@interface QTABTestConfigOptions : NSObject

/// 获取实验结果 url
@property (nonatomic, copy) NSURL *baseURL;

/// SDK 主动轮询最新实验结果间隔时间（单位：秒），默认10分钟，最小支持10秒，最大支持30分钟，超出使用默认值
@property (nonatomic) NSTimeInterval updateInterval;

/// 本地缓存实验结果数据变化回调
@property (nonatomic, copy) OnABTestPropertyChangedBlock onABTestPropertyChangedBlock;

- (instancetype)init NS_UNAVAILABLE;

/** 初始化方法
 @param urlString 地址链接URL
 @return 实例对象
 */
- (instancetype)initWithURL:(NSString *)urlString NS_DESIGNATED_INITIALIZER;

@end

NS_ASSUME_NONNULL_END

示例：

#import <QTABTestSDK/QTABTestSDK.h>

QTABTestConfigOptions *configOptions = [[QTABTestConfigOptions alloc] initWithURL:@"您的收数服务地址/abtest_results?appkey=xxxxx"];
// 主动每30秒轮询最新实验结果
configOptions.updateInterval = 30;
// 本地缓存实验结果数据变化回调
// 方式1：初始化配置中设置
configOptions.onABTestPropertyChangedBlock = ^(NSArray * _Nonnull result) {
    NSLog(@"---------result: %@",result);
    /** 返回结果数据示例
        [
          {"gid": xxx, "expid": xxx,}, 
          {"gid": xxx, "expid": xxx,},
          ...
        ]
    **/
};
[QTABTest startWithConfigOptions:configOptions];

开启日志

/// 设置是否在console输出SDK的日志信息
/// @param enable 开启/关闭调试日志输出； YES：开启， NO：关闭，默认为 NO
+ (void)setLogEnabled:(BOOL)enable;

示例：

 [QTABTest setLogEnabled:YES];

2.1.1 主动设置本地缓存实验结果数据变化回调API

API 名称	场景说明
setAbPropertyChangedBlock	开发者设置AB SDK本地缓存实验结果数据变化监听回调

使用示例

#import <QTABTestSDK/QTABTestSDK.h>

// 本地缓存实验结果数据变化回调
// 方式2：开发者设置
[[QTABTest sharedInstance] setAbPropertyChangedBlock:^(NSArray * _Nonnull result) {
    NSLog(@"---------result: %@",result);
    /** 返回结果数据示例
        [
          {"gid": xxx, "expid": xxx,}, 
          {"gid": xxx, "expid": xxx,},
          ...
        ]
    **/
}];

2.2获取实验变量

初始化QuickTracking ABTest SDK 之后，通过 API 获取具体试验的变量值，根据获取试验变量值的方式，可分为下面三种策略：

fetchABTestFromCache ：读取本地缓存，缓存不存在时使用默认值
fetchABTestFromServer ：忽略本地缓存，从服务端获取数据
fetchABTestFromCacheThenServer ：优先读取本地缓存，缓存不存在时从服务端获取数据

使用场景说明

API名称	场景说明
fetchABTestFromCache	如果对查询性能有要求，可以使用fetchABTestFromCache API 只从本地缓存获取变量值，缺点是无法及时命中最新的实验结果
fetchABTestFromServer	如果您进行时间片轮转实验，且对实验的时效性有要求，可以使用fetchABTestFromServer API 获取实验变量值，缺点是可能会存在一定的网络延迟
fetchABTestFromCacheThenServer	默认情况下，建议使用此API，兼顾查询性能和时效性考虑，该API会优先从本地缓存获取变量值，如果本地缓存不命中结果，则查询AB实验服务端最新数据

2.3 API 介绍

fetchABTestFromCache

//读取本地缓存获取实验，缓存不存在时使用默认值
/// @param paramName 实验参数名
/// @param defaultValue 默认结果
/// @return 实验值
- (nullable id)fetchABTestFromCacheWithParamName:(NSString*)paramName
                                   defaultValue:(id)defaultValue;

请求参数

参数

类型

含义

备注

paramName

NSString

实验参数名

必传参数，需设置非空字符串。

defaultValue

NSString | BOOL | NSNumber | NSDictionary

实验参数默认结果值

必传参数，需和当前实验值结果类型保持一致。

如参数对应的实验值类型为NUMBER类型，则传入的defaultValue也必须是number类型，同时返回的result实验结果也是number类型

重要

注意：请确保对A/B分流接口中使用的默认值，都做了正常的业务逻辑处理！

返回结果

参数	类型	默认值	含义	备注
<T> T	NSString \| BOOL \| NSNumber \| NSDictionary	nil	实验参数结果值	设置的实验结果值必须要和实验值类型一致，否则sdk会认为是异常实验结果。同时请注意result返回的结果在业务中都做了正常的业务逻辑判断

使用示例

#import "QTABTest.h"

// 请求返回String参数 
id result = [[QTABTest sharedInstance] fetchABTestFromCacheWithParamName:@"ios_test_string" defaultValue:@"111"];

// 请求返回Boolean参数 
id result = [[QTABTest sharedInstance] fetchABTestFromCacheWithParamName:@"ios_test_bool" defaultValue:@(YES)];

// 请求返回Number参数 
id result = [[QTABTest sharedInstance] fetchABTestFromCacheWithParamName:@"ios_test_number" defaultValue:@1];

//请求返回JSONObject参数
NSDictionary *dict = @{
    @"param1" : @"1"
    };
id result = [[QTABTest sharedInstance] fetchABTestFromCacheWithParamName:@"ios_test_json" defaultValue:dict];

fetchABTestFromServer

//忽略本地缓存，从服务端获取数据，异步从服务端获取最新实验结果
/// @param paramName 实验参数名
/// @param defaultValue 默认结果
/// @param timeoutInterval 超时时间，单位为秒
/// @param completionHandler 主线程回调，返回实验结果
- (void)fetchABTestFromServerWithParamName:(NSString*)paramName
                             defaultValue:(id)defaultValue
                          timeoutInterval:(NSTimeInterval)timeoutInterval
                        completionHandler:(void (^)(id _Nullable result))completionHandler;

请求参数

参数	类型	默认值	含义	备注
paramName	NSString	nil	实验参数名	必传参数，需设置非空字符串。
timeoutInterval	NSTimeInterval	600	分流实验服务端请求超时时间	非必传参数
defaultValue	NSString \| BOOL \| NSNumber \| NSDictionary	nil	实验参数默认结果值	必传参数，需和当前实验值结果类型保持一致。如参数对应的实验值类型为NUMBER类型，则传入的defaultValue也必须是number类型，同时返回的result实验结果也是number类型
<T> T	NSString \| BOOL \| NSNumber \| NSDictionary	nil	实验参数结果值	设置的实验结果值必须要和实验值类型一致，否则sdk会认为是异常实验结果。同时请注意result返回的结果在业务中都做了正常的业务逻辑判断
callback	callback	无	分流实验结果值回调函数	必传参数

Callback说明：

typedef void (^QTABCompletionHandler)(id _Nullable result);

返回参数：

参数	类型	默认值	含义	备注
<T> T	NSString \| BOOL \| NSNumber \| NSDictionary	nil	实验参数结果值	设置的实验结果值必须要和实验值类型一致，否则sdk会认为是异常实验结果。同时请注意result返回的结果在业务中都做了正常的业务逻辑判断

重要

注意：请确保对A/B分流接口中使用的默认值，都做了正常的业务逻辑处理！

返回结果

参数	类型	默认值	含义	备注
result	NSString \| BOOL \| NSNumber \| NSDictionary	nil	实验参数结果值	设置的实验结果值必须要和实验值类型一致，否则sdk会认为是异常实验结果。同时请注意result返回的结果在业务中都做了正常的业务逻辑判断

使用示例

NSDictionary *dict = @{
    @"param1" : @"1"
    };
NSString *paramName = @"ios_test_json";

[[QTABTest sharedInstance] fetchABTestFromServerWithParamName:paramName defaultValue:dict timeoutInterval:10 completionHandler:^(id  _Nullable result) {

    if (result) {

        NSLog(@"======result:%@", result);
    }
}];

fetchABTestFromCacheThenServer

//优先读取本地缓存，缓存不存在时从服务端获取数据
/// @param paramName 实验参数名
/// @param defaultValue 默认值
/// @param timeoutInterval 超时时间，单位为秒
/// @param completionHandler 主线程回调，返回实验结果
- (void)fetchABTestFromCacheThenServerWithParamName:(NSString*)paramName
                                      defaultValue:(id)defaultValue
                                   timeoutInterval:(NSTimeInterval)timeoutInterval
                                 completionHandler:(void (^)(id _Nullable result))completionHandler;

请求参数

参数	类型	默认值	含义	备注
paramName	NSString	nil	实验参数名	必传参数，需设置非空字符串。
timeoutInterval	NSTimeInterval	600	分流实验服务端请求超时时间	非必传参数
defaultValue	NSString \| BOOL \| NSNumber \| NSDictionary	nil	实验参数默认结果值	必传参数，需和当前实验值结果类型保持一致。如参数对应的实验值类型为NUMBER类型，则传入的default_value也必须是number类型，同时返回的result实验结果也是number类型
<T> T	NSString \| BOOL \| NSNumber \| NSDictionary	nil	实验参数结果值	设置的实验结果值必须要和实验值类型一致，否则sdk会认为是异常实验结果。同时请注意result返回的结果在业务中都做了正常的业务逻辑判断
callback	callback	无	分流实验结果值回调函数	必传参数

重要

注意：请确保对A/B分流接口中使用的默认值，都做了正常的业务逻辑处理！

返回结果

参数	类型	默认值	含义	备注
result	NSString \| BOOL \| NSNumber \| NSDictionary		实验参数结果值	设置的实验结果值必须要和实验值类型一致，否则sdk会认为是异常实验结果。同时请注意result返回的结果在业务中都做了正常的业务逻辑判断

使用示例

NSString *defaultValue = @"111";
NSString *paramName = @"ios_test_string";
[[QTABTest sharedInstance] fetchABTestFromCacheThenServerWithParamName:paramName defaultValue:defaultValue timeoutInterval:10 completionHandler:^(id  _Nullable result) {

    if (result) {

        NSLog(@"======result:%@", result);

    }
}];

3.调试试验

开启实验后

开启log时会打印出您对应的实验列表