macOS SDK - Quick Tracking - Alibaba Cloud Documentation Center

A prerequisite for using QuickTracking macOS(A/B Testing).

Basic SDK information

The file name.

Version

md5

File size

QuickTracking macOS SDK

1.0.0

Update logs: iOS/macOS SDK update logs

48db48d7f2c95d97e8adc55540c46091

3.2 MB

QTABTestSDK

1.3.0

Update logs: iOS and macOS SDK update logs

e58ab6280a42c01c5243a2bc7784cbf0

2.8 MB

Integrate the SDK

The A/B Testing SDK depends on the macOS SDK. Before you use the /B Testing SDK, make sure that you have successfully integrated the QuickTracking Statistics SDK and initialized the SDK. For more information, see.

CocoaPods (recommend)

Add in Podfile

pod 'QuickTrackingSDK'
pod 'QTABTest'

Open a terminal and switch to the project directory
Run the pod install or pod update command
If the latest version cannot be pulled, run the pod repo update first, and then run the pod install or pod update

Overview

Obtain the SDK offline package from the QuickTracking product operation classmate

Configure the project

Add the following file to the application project
1. QuickTrackingSDK.xcframework
2. QTABTestSDK.xcframework

Under the "Build Phase" option of the Xcode project, add the dependency library to the "Link Binary With Libraries":
1. QuickTrackingSDK.xcframework
2. QTABTestSDK.xcframework
3. libsqlite3.tbd
4. libz.tbd

Programming Experiment

SDK initialization

Complete sample code

#import <QuickTrackingSDK/QuickTrackingSDK.h>

- (void)applicationDidFinishLaunching:(NSNotification *)aNotification {
    QTSDKConfig *sdkConfig;
    // Initialize the SDK configuration.
    sdkConfig = [[QTSDKConfig alloc] initWithAppkey:@"The unique identifier of your application"
                                        trackDomain:@"https:// Your domain name"
                                      launchOptions:nil];
    // Specify the channel in which the application is published. Example: appstore.
    sdkConfig.channel = @"Your application release channel";
    
    // Initialize the SDK.
    [QuickTrackingSDK initWithConfig:sdkConfig];
    
    // Initialize the ABTest configuration.
    QTABTestConfigOptions *configOptions;
    configOptions = [[QTABTestConfigOptions alloc] initWithURL:@"https:// Your domain name /abtest_results?appkey=The unique identifier of your application"];
    
    // The SDK proactively polls the latest experiment result gap, in seconds.
    // Default value: 600s, which is 10 minutes.
    // The minimum interval is 10s and the maximum interval is 1800s (that is, 30 minutes). If the interval exceeds the range, the default gap is used.
    //configOptions.updateInterval = 300;
    
    // The ABTest log switch. By default, the switch is turned off, that is, NO.
    configOptions.enableLog = YES;
    
    // The ABTest property change callback, 
    configOptions.onABTestPropertyChangedBlock = ^(NSArray * _Nonnull result) {
       /**Output example
        [
          {"gid": xxx, "expid": xxx}, 
          {"gid": xxx, "expid": xxx}
        ]
        **/
        NSLog(@"-----%@", result);
    };
    
    // Initialize the ABTest SDK.
    [QTABTest startWithConfigOptions:configOptions];
}

QTABTestConfigOptions description

Parameter	type	Description
URL	NSString	Obtain the url of the experiment result. You need to set this to a valid experiment result acquisition address. For example, https:// your domain name /abtest_results?appkey=the unique identifier of your application.
updateInterval	NSTimeInterval	The interval at which the SDK actively polls the latest experiment results. Unit: seconds. The default value is 600 seconds. The minimum value is 10 seconds and the maximum value is 1800 seconds. If the default value is exceeded, use the default value.
enableLog	BOOL	Whether to enable log entry. Default value: NO. Set to YES to enable the log entry feature.
onABTestPropertyChangedBlock	OnABTestPropertyChangedBlock	The callback block when the /B test property changes. It contains a parameter result of type NSArray.

Enable Log Collection

Interface functions

/// Set whether to output the SDK log in the console.
/// @param enable Enable /Disable debug log output; YES: Enable. NO: Disable. The default value is NO.
+ (void)setLogEnabled:(BOOL)enable;

Complete sample code

 [QTABTest setLogEnabled:YES];

Obtain experiment variables

After the initialization QuickTracking ABTest SDK, the variable value of the specific test is obtained through the API, which can be divided into the following three strategies according to the method of obtaining the value of the test variable:

fetchABTestFromCache: Read the local cache. If the cache does not exist, the default value is used.
fetchABTestFromServer: Ignore local cache and get data from server
fetchABTestFromCacheThenServer: Read the local cache first, and obtain data from the server when the cache does not exist.

Description

API parameter value	Scenarios
fetchABTestFromCache	If you have requirements on query performance, you can use fetchABTestFromCache API to obtain variable values only from the local cache. The disadvantage is that the latest experimental results cannot be hit in time.
fetchABTestFromServer	If you want to perform a time slice rotation experiment and have requirements on the timeliness of the experiment, you can use fetchABTestFromServer API to obtain the experimental variable values. The disadvantage is that there may be a certain network latency.
fetchABTestFromCacheThenServer	By default, we recommend that you use this API to take into account the query performance and timeliness. This API preferentially obtains variable values from the local cache. If the local cache does not hit the result, the latest data of the AB experiment server is queried.

API introduction

fetchABTestFromCache

Interface functions

// Read the local cache to obtain the experiment. If the cache does not exist, the default value is used.
/// @param paramName The name of the experiment parameter.
/// @param defaultValue The default result.
/// @return Experimental value
- (nullable id)fetchABTestFromCacheWithParamName:(NSString*)paramName
                                   defaultValue:(id)defaultValue;

Parameters

Parameter

Description

Remarks

paramName

NSString

Experiment Parameter Name

Required parameter. You must set a non-empty string.

defaultValue

NSString | BOOL | NSNumber | NSDictionary

Default result values for experiment parameters

Required parameters, which must be consistent with the current experimental value result type.

If the experiment value corresponding to the parameter is of the NUMBER type, the input defaultValue must also be of the number type, and the returned result experiment result must also be of the number type.

Response parameters

Parameter	Parameter	Default value	Description	Remarks
<T> T	NSString \| BOOL \| NSNumber \| NSDictionary	nil	Experimental parameter result value	the specified experiment result value must be of the same type as the experiment value. otherwise, the sdk considers the experiment result as abnormal. At the same time, please note that the results returned by result have made normal business logic judgment in the business.

Complete sample code

#import "QTABTest.h"

// The request returns the NSString parameter. 
NSString *result = [[QTABTest sharedInstance] fetchABTestFromCacheWithParamName:@"test_string" defaultValue:@"111"];

// The Boolean parameter returned for the request. 
BOOL result = [[QTABTest sharedInstance] fetchABTestFromCacheWithParamName:@"test_bool" defaultValue:@(YES)];

// The number parameter returned by the request. 
NSNumber result = [[QTABTest sharedInstance] fetchABTestFromCacheWithParamName:@"test_number" defaultValue:@1];

// The request returns the JSONObject parameter.
NSDictionary *dict = @{
    @"param1" : @"1"
};
NSDictionary *result = [[QTABTest sharedInstance] fetchABTestFromCacheWithParamName:@"test_json" defaultValue:dict];

Note:

Make sure that the default values used in the /B offload interface are handled in normal business logic!

fetchABTestFromServer

Interface functions

// Obtain the latest experiment results from the server asynchronously, ignoring the local cache.
/// @param paramName The name of the experiment parameter.
/// @param defaultValue The default result.
/// @param timeoutInterval the timeout period. Unit: seconds.
/// @param completionHandler the main thread callback to return the experiment result.
- (void)fetchABTestFromServerWithParamName:(NSString*)paramName
                             defaultValue:(id)defaultValue
                          timeoutInterval:(NSTimeInterval)timeoutInterval
                        completionHandler:(void (^)(id _Nullable result))completionHandler;

Parameters

Parameter	Parameter	Default value	Description	Remarks
paramName	NSString	nil	Experiment Parameter Name	Required parameter. You must set a non-empty string.
timeoutInterval	NSTimeInterval	600	The server request timeout period of the shunt experiment.	Required parameters
defaultValue	NSString \| BOOL \| NSNumber \| NSDictionary	nil	Default result values for experiment parameters	Required parameters, which must be consistent with the current experimental value result type. If the experiment value corresponding to the parameter is of the NUMBER type, the input defaultValue must also be of the number type, and the returned result experiment result must also be of the number type.
<T> T	NSString \| BOOL \| NSNumber \| NSDictionary	nil	Experimental parameter result value	the specified experiment result value must be of the same type as the experiment value. otherwise, the sdk considers the experiment result as abnormal. At the same time, please note that the results returned by result have made normal business logic judgment in the business.
callback	callback	None.	Shunt experiment result value callback function	Required parameter

Callback description

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

Response parameters

Parameter	Parameter	Default value	Description	Remarks
<T> T	NSString \| BOOL \| NSNumber \| NSDictionary	nil	Experimental parameter result value	the specified experiment result value must be of the same type as the experiment value. otherwise, the sdk considers the experiment result as abnormal. At the same time, please note that the results returned by result have made normal business logic judgment in the business.

Complete sample code

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);
    }
}];

Note:

Make sure that the default values used in the /B offload interface are handled in normal business logic!

fetchABTestFromCacheThenServer

Interface functions

// First read the local cache and obtain data from the server if the cache does not exist.
/// @param paramName The name of the experiment parameter.
/// @param defaultValue The default value.
/// @param timeoutInterval the timeout period. Unit: seconds.
/// @param completionHandler the main thread callback to return the experiment result.
- (void)fetchABTestFromCacheThenServerWithParamName:(NSString*)paramName
                                      defaultValue:(id)defaultValue
                                   timeoutInterval:(NSTimeInterval)timeoutInterval
                                 completionHandler:(void (^)(id _Nullable result))completionHandler;

Parameters

Parameter	Parameter	Default value	Description	Remarks
paramName	NSString	nil	Experiment Parameter Name	Required parameter. You must set a non-empty string.
timeoutInterval	NSTimeInterval	600	The server request timeout period of the shunt experiment.	Required parameters
defaultValue	NSString \| BOOL \| NSNumber \| NSDictionary	nil	Default result values for experiment parameters	Required parameters, which must be consistent with the current experimental value result type. If the experiment value corresponding to the parameter is of the NUMBER type, the input default_value must also be of the number type, and the returned result experiment result is also of the number type.
<T> T	NSString \| BOOL \| NSNumber \| NSDictionary	nil	Experimental parameter result value	the specified experiment result value must be of the same type as the experiment value. otherwise, the sdk considers the experiment result as abnormal. At the same time, please note that the results returned by result have made normal business logic judgment in the business.
callback	callback	None.	Shunt experiment result value callback function	Required parameter

Response parameters

Parameter	Parameter	Default value	Description	Remarks
result	NSString \| BOOL \| NSNumber \| NSDictionary		Experimental parameter result value	the specified experiment result value must be of the same type as the experiment value. otherwise, the sdk considers the experiment result as abnormal. At the same time, please note that the results returned by result have made normal business logic judgment in the business.

Complete sample code

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

Note:

Make sure that the default values used in the /B offload interface are handled in normal business logic!

3. Commissioning test

After opening the experiment