iOS SDK

SDK information

File name	Version	MD5	File size
QuickTracking A/B Testing SDK	1.4.4 Changelog: iOS/macOS SDK Changelog	6548cfd35ff168c2317835305e0a69cd	1.7 MB

1. Integration

The QuickTracking A/B Testing SDK does not collect personal information directly. It relies on behavioral data from the QuickTracking Analytics SDK. Before you begin, integrate the QuickTracking Analytics SDK for iOS v1.6.0 or later and initialize it. For more information, see Import & Configure the SDK.

2. Programmatic experiment

2.1 Integrate and initialize the SDK

Initialize the QuickTracking Analytics SDK synchronously first, then initialize the QuickTracking A/B Testing SDK with the traffic-splitting experiment URL. Obtain this URL from your operations team.

2.1.1 Use CocoaPods (recommended)

1. Add the following to your Podfile:

   pod 'QTABTest'

2. Open a terminal and navigate to your project directory.

3. Run pod install or pod update.

4. If you fail to pull the latest version, run pod repo update before running pod install or pod update.

2.1.2 Manual integration

Contact the QuickTracking product operations team to get the QTABTest SDK offline package, the QTABTestSDK.xcframework file.

Project configuration

1. Add the QTABTestSDK.xcframework file to your application project.

2.1.3 Initialize the SDK

/** Initializes the QuickTracking A/B Testing SDK for iOS.
 @param configOptions The initialization configurations.
 */
+ (void)startWithConfigOptions:(QTABTestConfigOptions *)configOptions;

QTABTestConfigOptions class

#import <Foundation/Foundation.h>

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

NS_ASSUME_NONNULL_BEGIN

@interface QTABTestConfigOptions : NSObject

/// The URL to fetch experiment results.
@property (nonatomic, copy) NSURL *baseURL;

/// The interval in seconds at which the SDK polls for the latest experiment results. The default value is 10 minutes (600 seconds). The minimum supported value is 10 seconds, and the maximum is 30 minutes (1800 seconds). If the value is outside this range, the default is used.
@property (nonatomic) NSTimeInterval updateInterval;

/// A callback that is triggered when the experiment results in the local cache change.
@property (nonatomic, copy) OnABTestPropertyChangedBlock onABTestPropertyChangedBlock;

- (instancetype)init NS_UNAVAILABLE;

/** Initializes the instance.
 @param urlString The URL string.
 @return An instance of the class.
 */
- (instancetype)initWithURL:(NSString *)urlString NS_DESIGNATED_INITIALIZER;

@end

NS_ASSUME_NONNULL_END

Parameters:

Parameter	Type	Default	Description	Notes
urlString	String	undefined	Experiment URL.	Required parameter. Must be a non-empty string.
updateInterval	Integer	600	Cache update interval in seconds. Maximum: 1800 Minimum: 10	Optional
onABTestPropertyChangedBlock	Block	undefined	A callback for A/B parameter changes.	Optional

Example:

#import <QTABTestSDK/QTABTestSDK.h>

QTABTestConfigOptions *configOptions = [[QTABTestConfigOptions alloc] initWithURL:@"YOUR_DATA_SERVICE_ADDRESS/abtest_results?appkey=xxxxx"];
// Poll for the latest experiment results every 30 seconds.
configOptions.updateInterval = 30;
// Callback for changes in the locally cached experiment results.
// Method 1: Set during initialization.
configOptions.onABTestPropertyChangedBlock = ^(NSArray * _Nonnull result) {
    NSLog(@"---------result: %@",result);
    /** Sample returned data
        [
          {"gid": xxx, "expid": xxx,}, 
          {"gid": xxx, "expid": xxx,},
          ...
        ]
    **/
};
[QTABTest startWithConfigOptions:configOptions];

2.1.4 Enable logging

/// Specifies whether to print SDK logs to the console.
/// @param enable YES to enable debug logging, NO to disable it. The default value is NO.
+ (void)setLogEnabled:(BOOL)enable;

Example:

 [QTABTest setLogEnabled:YES];

2.1.5 Set local cache change callback

API name	Use case
setAbPropertyChangedBlock	Sets a callback for changes to locally cached A/B testing results.

Usage example

#import <QTABTestSDK/QTABTestSDK.h>

// Callback for changes in the locally cached experiment results.
// Method 2: Set explicitly by the developer.
[[QTABTest sharedInstance] setAbPropertyChangedBlock:^(NSArray * _Nonnull result) {
    NSLog(@"---------result: %@",result);
    /** Sample returned data
        [
          {"gid": xxx, "expid": xxx,}, 
          {"gid": xxx, "expid": xxx,},
          ...
        ]
    **/
}];

2.2 Get experiment variables

After initializing the QuickTracking A/B Testing SDK, use the following APIs to get experiment variables. Three fetching strategies are available:

• fetchABTestFromCache: Reads from the local cache. If the cache is empty, it returns the default value.

• fetchABTestFromServer: Ignores the local cache and fetches data from the server.

• fetchABTestFromCacheThenServer: Reads from the local cache first. If the cache is empty, it fetches data from the server.

2.2.1 Use cases

API name	Use case
fetchABTestFromCache	If query performance is critical, use fetchABTestFromCache to get variables from the local cache only. The trade-off is that results may not be up to date.
fetchABTestFromServer	For time-sensitive experiments that require immediate results, use fetchABTestFromServer. The trade-off is potential network latency.
fetchABTestFromCacheThenServer	Recommended for most scenarios. Balances performance and timeliness by reading from the local cache first and falling back to the A/B testing server when no cached results are available.

2.3 API reference

Return value (New in v1.4.0)

An API request returns an object containing the experiment data. For example:

result = 
{
    "expid" = "114"; // experiment ID
    "gid" = "201"; // experiment group ID
    "value" = ""; // return value
}

Parameters

Parameter	Type	Default	Description	Notes
value	NSString | BOOL | Int | Object	undefined	The value of the experiment parameter.	The data type of the return value must match the experiment's parameter type. Otherwise, the SDK considers the value invalid. Ensure that your business logic correctly handles the returned value.
expid	NSString	""	The experiment ID.
gid	NSString	""	The experiment group ID.

fetchABTestFromCache

// Fetches an experiment from the local cache. If no value is found, it returns the default value.
/// @param paramName The name of the experiment parameter.
/// @param defaultValue The default value to return if no value is found in the cache.
/// @return The experiment value (NSDictionary).
- (nullable id)fetchABTestFromCacheWithParamName:(NSString*)paramName
                                   defaultValue:(id)defaultValue;

Request parameters

Parameter	Type	Description	Notes
paramName	NSString	The name of the experiment parameter.	Required parameter. Must be a non-empty string.
defaultValue	NSString | BOOL | NSNumber | NSDictionary	The default value for the experiment parameter.	Required parameter. The data type must match the experiment's value type. For example, if the experiment's value type is NUMBER, the defaultValue you provide must also be a number type, and the 'value' field in the returned object will also be a number.

Return value

Parameter	Type	Default	Description	Notes
<T> T	NSString | BOOL | NSNumber | NSDictionary	nil	The value of the experiment parameter.	The data type of the return value must match the experiment's value type. Otherwise, the SDK considers the value invalid. Ensure that your business logic correctly handles the returned value.

Usage example

#import "QTABTest.h"

// Request a parameter of type NSDictionary.
NSDictionary *dict = @{
    @"param1" : @"1"
    };
NSDictionary *result = [[QTABTest sharedInstance] fetchABTestFromCacheWithParamName:@"ios_test_json" defaultValue:dict];

fetchABTestFromServer

// Ignores the local cache and asynchronously fetches the latest experiment results from the server.
/// @param paramName The name of the experiment parameter.
/// @param defaultValue The default value.
/// @param timeoutInterval The timeout interval in seconds.
/// @param completionHandler A callback on the main thread that returns the experiment result.
- (void)fetchABTestFromServerWithParamName:(NSString*)paramName
                             defaultValue:(id)defaultValue
                          timeoutInterval:(NSTimeInterval)timeoutInterval
                        completionHandler:(void (^)(id _Nullable result))completionHandler;

Request parameters

Parameter	Type	Default	Description	Notes
paramName	NSString	nil	The name of the experiment parameter.	Required parameter. Must be a non-empty string.
timeoutInterval	NSTimeInterval	600	The server request timeout.	Optional parameter.
defaultValue	NSString | BOOL | NSNumber | NSDictionary	nil	The default value for the experiment parameter.	Required parameter. The data type must match the experiment's value type. For example, if the experiment's value type is NUMBER, the defaultValue you provide must also be a number type, and the 'value' field in the returned object will also be a number.
<T> T	NSString | BOOL | NSNumber | NSDictionary	nil	The value of the experiment parameter.	The data type of the return value must match the experiment's value type. Otherwise, the SDK considers the value invalid. Ensure that your business logic correctly handles the returned value.
completionHandler	callback	n/a	A callback for the experiment result.	Required parameter.

Callback description:

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

Callback parameter:

Parameter	Type	Default	Description	Notes
<T> T	NSString | BOOL | NSNumber | NSDictionary	nil	The value of the experiment parameter.	The data type of the return value must match the experiment's value type. Otherwise, the SDK considers the value invalid. Ensure that your business logic correctly handles the returned value.

Result (in callback)

Parameter	Type	Default	Description	Notes
result	NSString | BOOL | NSNumber | NSDictionary	nil	The value of the experiment parameter.	The data type of the return value must match the experiment's value type. Otherwise, the SDK considers the value invalid. Ensure that your business logic correctly handles the returned value.

Usage example

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

// Reads from the local cache first. If no value is found, it fetches data from the server.
/// @param paramName The name of the experiment parameter.
/// @param defaultValue The default value.
/// @param timeoutInterval The timeout interval in seconds.
/// @param completionHandler A callback on the main thread that returns the experiment result.
- (void)fetchABTestFromCacheThenServerWithParamName:(NSString*)paramName
                                      defaultValue:(id)defaultValue
                                   timeoutInterval:(NSTimeInterval)timeoutInterval
                                 completionHandler:(void (^)(id _Nullable result))completionHandler;

Request parameters

Parameter	Type	Default	Description	Notes
paramName	NSString	nil	The name of the experiment parameter.	Required parameter. Must be a non-empty string.
timeoutInterval	NSTimeInterval	600	The server request timeout.	Optional parameter.
defaultValue	NSString | BOOL | NSNumber | NSDictionary	nil	The default value for the experiment parameter.	Required parameter. The data type must match the experiment's value type. For example, if the experiment's value type is NUMBER, the defaultValue you provide must also be a number type, and the 'value' field in the returned object will also be a number.
<T> T	NSString | BOOL | NSNumber | NSDictionary	nil	The value of the experiment parameter.	The data type of the return value must match the experiment's value type. Otherwise, the SDK considers the value invalid. Ensure that your business logic correctly handles the returned value.
completionHandler	callback	n/a	A callback for the experiment result.	Required parameter.

Result (in callback)

Parameter	Type	Default	Description	Notes
result	NSString | BOOL | NSNumber | NSDictionary		The value of the experiment parameter.	The data type of the return value must match the experiment's value type. Otherwise, the SDK considers the value invalid. Ensure that your business logic correctly handles the returned value.

Usage example

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. Debugging an experiment

After starting the experiment:

When logging is enabled, the SDK prints your list of experiments to the console.