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

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

SDK基本信息

文件名称

版本号

md5

文件大小

QuickTracking macOS SDK

1.0.0

更新日志: macOS SDK 更新日志

48db48d7f2c95d97e8adc55540c46091

3.2 MB

QTABTestSDK

1.3.0

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

e58ab6280a42c01c5243a2bc7784cbf0

2.8 MB

集成SDK

A/B Testing SDK 依赖macOS SDK，在使用前请确保已经成功集成QuickTracking 统计SDK，并进行了SDK初始化，详情可参考。

CocoaPods方式（推荐）

在Podfile文件中添加

pod 'QuickTrackingSDK'
pod 'QTABTest'

打开终端，切换到项目目录
执行 pod install 或者 pod update
如果拉取不到最新版本，先执行 pod repo update，再执行pod install 或者 pod update

离线集成

向QuickTracking产品运营同学获取SDK离线包

工程配置

添加如下文件到应用工程
1. QuickTrackingSDK.xcframework
2. QTABTestSDK.xcframework

在Xcode工程 “Build Phase” 选项下，“Link Binary With Libraries” 中添加依赖库：
1. QuickTrackingSDK.xcframework
2. QTABTestSDK.xcframework
3. libsqlite3.tbd
4. libz.tbd

编程实验

SDK初始化

完整示例

#import <QuickTrackingSDK/QuickTrackingSDK.h>

- (void)applicationDidFinishLaunching:(NSNotification *)aNotification {
    QTSDKConfig *sdkConfig;
    // 初始化SDK配置
    sdkConfig = [[QTSDKConfig alloc] initWithAppkey:@"您的应用唯一标识"
                                        trackDomain:@"https://您的收数域名"
                                      launchOptions:nil];
    // 设置应用发布渠道，例如:appstore
    sdkConfig.channel = @"您的应用发布渠道";
    
    // 初始化 SDK
    [QuickTrackingSDK initWithConfig:sdkConfig];
    
    //初始化ABTest配置
    QTABTestConfigOptions *configOptions;
    configOptions = [[QTABTestConfigOptions alloc] initWithURL:@"https://您的收数域名/abtest_results?appkey=您的应用唯一标识"];
    
    // SDK主动轮询最新实验结果间隔时间，单位秒
    // 默认600s，即10分钟
    // 最小间隔 10s，最大间隔 1800s（即30分钟），超过范围使用默认间隔时间
    //configOptions.updateInterval = 300;
    
    // ABTest 日志开关，默认关闭，即 NO
    configOptions.enableLog = YES;
    
    // ABTest 属性变更回调，
    configOptions.onABTestPropertyChangedBlock = ^(NSArray * _Nonnull result) {
       /** 输出示例
        [
          {"gid": xxx, "expid": xxx}, 
          {"gid": xxx, "expid": xxx}
        ]
        **/
        NSLog(@"-----%@", result);
    };
    
    // ABTest SDK 初始化
    [QTABTest startWithConfigOptions:configOptions];
}

QTABTestConfigOptions说明

名称	类型	描述
URL	NSString	获取实验结果的url。需要设置为有效的实验结果获取地址。形如：https://您的收数域名/abtest_results?appkey=您的应用唯一标识
updateInterval	NSTimeInterval	SDK 主动轮询最新实验结果的时间间隔（单位：秒）。默认值为 600 秒，最小支持 10 秒，最大支持 1800 秒，超出范围使用默认值。
enableLog	BOOL	是否启用日志记录，默认为NO。设置为 YES 启用日志记录功能。
onABTestPropertyChangedBlock	OnABTestPropertyChangedBlock	A/B 测试属性更改时的回调块，包含一个 NSArray 类型的参数 result。

开启日志

接口函数

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

完整示例

 [QTABTest setLogEnabled:YES];

获取实验变量

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

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

使用场景说明

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

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类型

返回值说明

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

完整示例

#import "QTABTest.h"

// 请求返回NSString参数 
NSString *result = [[QTABTest sharedInstance] fetchABTestFromCacheWithParamName:@"test_string" defaultValue:@"111"];

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

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

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

使用注意：

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

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返回的结果在业务中都做了正常的业务逻辑判断

完整示例

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

[[QTABTest sharedInstance] fetchABTestFromServerWithParamName:paramName defaultValue:dict timeoutInterval:10 completionHandler:^(id  _Nullable result) {
    if (result) {
        NSLog(@"======result:%@", result);
    }
}];

使用注意：

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

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	无	分流实验结果值回调函数	必传参数

返回值说明

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

完整示例

NSString *defaultValue = @"111";
NSString *paramName = @"test_string";
[[QTABTest sharedInstance] fetchABTestFromCacheThenServerWithParamName:paramName defaultValue:defaultValue timeoutInterval:10 completionHandler:^(id  _Nullable result) {
    if (result) {
        NSLog(@"======result:%@", result);
    }
}];

使用注意：

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

3.调试试验

开启实验后