Tracking API

1. How to view the instrumentation plan

Before you begin instrumentation, you must determine where to place tracking points and which events to track. This requires a clear and well-defined set of instrumentation requirements. The QuickTracking platform organizes these requirements into a standardized template called an instrumentation plan. An example is shown below.

An instrumentation plan specifies the following required information:

1. Event entity: This identifies who triggered the event. This can be a device ID or an account ID. Every reported event must include at least one of these identifiers.

• Device ID: For Android and iOS devices, the default device ID is unique at the application level and is automatically generated by QuickTracking.

  • For devices running Android 9 and earlier, the SDK automatically collects the IMEI, Wi-Fi MAC address, Android ID, and serial number (SN) to generate a device ID. This ID is then stored locally. A new device ID is generated only when the user uninstalls the application or clears its data.

  • For devices running Android 10 and later, the SDK automatically collects the OAID, GAID, Android ID, and SN to generate a device ID. This ID is then stored locally. A new device ID is generated only when the user uninstalls the application or clears its data.

  • For iOS devices, the SDK automatically collects the OpenUDID to generate a device ID. This ID is then stored in the keychain. A new device ID is generated only when the user performs a factory reset or clears the application data.

  • The QuickTracking SDK collects the IDFA and OAID only if the application's end user consents to the collection. Only the QuickTracking app SDK can collect the OAID, GAID, IMEI, Wi-Fi MAC address, Android ID, SN, IDFA, and IDFV.

• Account ID: This is the identifier for a user's account after they log on to the application. When a user logs on from different devices, the device ID changes, but the account ID remains the same. For example, a user might log on from both a mobile phone and a tablet.

2. User properties: These are properties associated with an account ID. For example, for a user with the account ID "testdemo@111", the "birthday" could be "1999-02-13" and the "membership level" could be "Platinum". In this case, "birthday" and "membership level" are user properties.

3. Channel properties: These are properties related to advertising campaigns, such as the advertising channel, delivery method, and ad content.

4. Global properties: These are properties that are set once globally and are then included with every event.

5. Page view events: These are events reported when a page loads. In the instrumentation plan, these are events where the page code and event code are the same, and they are marked in blue.

6. Click, exposure, and custom events: These are events reported whenever a user interacts with the application.

2. Set device ID & account ID

2.1 Set device ID

By default, the SDK collects the following parameters.

If you want to control the collection behavior for some of the device identifiers in the table, for example, by not collecting them or by implementing your own collection method, you can provide a custom implementation in the corresponding block callback. If you return an empty value, the SDK will collect the identifier. The following code shows an example.

[QTConfigure customSetMncBlock:^NSString *{
  return @"";
}];
[QTConfigure customSetDeviceModelBlock:^NSString *{
  return @"custom-device-model";
}];
[QTConfigure customSetOSVersionBlock:^NSString *{
  return @"custom-osversion";
}];
[QTConfigure customSetScreenResolutionBlock:^NSString *{
  return @"2880*1308";
}];

Note: Decide carefully whether to implement the corresponding method. If you choose to implement your own collection method, you are fully responsible for collecting the device identifier. The SDK will no longer attempt to collect it. The fewer device identifiers the SDK collects, the greater the negative impact on the accuracy and stability of your statistics.

// Before setting the data collection domain name and before calling the SDK pre-initializer function, call the collection utility registration function.
// If you do not need to control the device identifier collection behavior, you do not need to implement and register a custom utility class.
[QTConfigure customSetIdfvBlock:^NSString *{
    return [[UIDevice currentDevice].identifierForVendor UUIDString];
}];
[QTConfigure setCustomDomain:@"Your data collection domain name" standbyDomain:nil];
[QTConfigure initWithAppKey:@"Your AppKey" channel:@"App Store"];

The SDK supports custom device IDs. To use a custom device ID, you must call the `setCustomDeviceId:` interface with a valid (non-empty) value before initialization (before calling `init`).

+ (void)setCustomDeviceId:(NSString *)devID;

Example:

[QTConfigure setCustomDeviceId:@"xxxxxx"];

Note: This feature takes effect only when a device ID has not yet been retrieved. If a device ID already exists in local storage, this setting has no effect. To verify this feature when a local device ID exists, you must uninstall and reinstall the application.

2.2 Set account ID

1. QuickTracking (QT) uses the device as the standard for user statistics. To track accounts specific to your application, use the following interface:

Function:

+ (void)profileSignInWithPUID:(NSString *)puid;

Parameters:

Note: After an account ID is set, it is saved to local storage. The account ID becomes invalid only when the user uninstalls the app, clears the app data, or when you call the sign-off interface described below. Otherwise, every event will include the account ID.

Example:

[QTMobClick profileSignInWithPUID:@"UserID"];

If you no longer need to bind the user account, you can call the sign-off interface. After this call, account-related information will no longer be sent.

+ (void)profileSignOff;

Example:

[QTMobClick profileSignOff];

2.3 Get device ID

Function:

+ (NSString *)umidString;

Example:

NSString *deviceID = [QTConfigure umidString];

3. Upload user properties

1. You can upload user properties using a custom event with the fixed event code `$$_user_profile`. The properties of this event are treated as user properties and stored in the user table.

NSDictionary *dict = @{@"sex" : @"girl", @"age" : @"8"};
[QTMobClick event:@"$$_user_profile" attributes:dict];

Note: You must call the account tracking interface before you upload user properties.

4. Channel properties

After you set channel properties, all subsequent events automatically include them. These properties and their values are stored in the cache and are cleared when the app process ends. You can use these properties to view and filter data during analysis.

4.1 Launch the app from an H5 link

1. The URL Scheme used to launch the app must contain these channel properties. The property keys must start with `utm_` because `utm_` is the keyword that the SDK recognizes. For example: <URL scheme>?utm_channel=gzh

2. Add your URL Scheme to the project. The URL Scheme is located in Project Settings > Target > Info tab > URL Types. Enter the scheme. In `AppDelegate`, call the `[MobClick handleUrl:url]` function to receive the URL.

Call in AppDelegate:

- (BOOL)application:(UIApplication *)application openURL:(nonnull NSURL *)url options:(nonnull NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options
{
 if ([QTMobClick handleUrl:url]) {
 return YES;
 }

 return YES;
}

Call in SceneDelegate:

- (void)scene:(UIScene *)scene willConnectToSession:(UISceneSession *)session options:(UISceneConnectionOptions *)connectionOptions {

 for (UIOpenURLContext *context in connectionOptions.URLContexts) {
 [QTMobClick handleUrl:context.URL];
 }
}

- (void)scene:(UIScene *)scene openURLContexts:(NSSet<UIOpenURLContext *> *)URLContexts {

 [QTMobClick handleUrl:URLContexts.allObjects.firstObject.URL];
}

Note: If your channel properties are already integrated with third-party advertising platforms and cannot start with `utm_`, you can use the global properties API to report the channel properties. However, the property keys must still start with `utm_`.

4.2 Launch the app marketplace from an H5 link to download and start the app

In this scenario, including `utm_` parameters in the H5 link is not sufficient to ensure the `utm_` parameters are included in the app launch event after download. Therefore, you must perform a fuzzy match between the H5 launch event and the app activation event based on the IP address and browser User-Agent.

1. When a user clicks the Launch/Download App button on the H5 page, you must report an app link event (`$$_app_link`). This event must include the AppKey of the app to be launched and the channel properties.

//Example
aplus_queue.push({
  action:'aplus.recordAppLink',
  arguments:[{
    targetAppKey: 'AppKey of the app to launch',  // Required. AppKey of the app to launch.
    custom1: 'custom1', // Optional. Custom parameter.
    ...
  }]
})

2. The app install event (`$$_app_install`), which is the first launch event after the app is downloaded, is automatically collected and reported by the QT App SDK.

3. The QuickTracking system performs a fuzzy match between the app link event (`$$_app_link`) and the app install event (`$$_app_install`) based on the IP address and browser User-Agent. When you use this feature, you can directly analyze the channel properties of the App Activation (Preset) event in the app.

4.3 Statistics on active users from different app marketplaces

The second input parameter, `channel`, in the initializer function is used to set the app marketplace for the application: [QTConfigure initWithAppkey:@"Your AppKey" channel:@"App Store"];. In your analysis, you can view this information using System Properties > Upgrade Channel.

5. Global properties

After you register global properties, all subsequent events automatically include them. These properties and their values are stored in memory and are cleared when the app process ends. You can use these properties to view and filter data during analysis.

5.1 Register global properties

/**
 * Set global properties as key-value pairs.
 * If a key already exists as a global property, its value is updated.
 * If a key does not exist as a global property, a new global property is inserted.
 */
+(void) registerGlobalProperty:(NSDictionary *)property;

Data type description:

Note:

1. Property names and property values of type `NSString` can contain only uppercase letters, lowercase letters, numbers, and underscores.

2. Property values can be one of the following types: `NSString`, `NSNumber`, `BOOL`, or `NSArray`.

3. If a key already exists as a global property, its value is updated. If a key does not exist, a new global property is inserted.

Example:

NSDictionary *firstPropertyDict = @{
  @"a" : @"1",
  @"b" : @"2",
  @"testString" : @"abc",
  @"testNumber" : @(12),
  @"testTime" : [NSDate now],
  @"testTime1" : @"2025-09-26",
  @"testTime2" : @"2025-09-26 10:57:05",
  @"testTime3" : @"2023-10-25 12:34:56.789",
  @"testBool" : @YES,
  @"testBool1" : @NO,
  @"groupTest" : @[@"abc",@"2025-09-26", @YES]                                                
  };
// The current global properties are a:1, b:2, etc.
[QTMobClick registerGlobalProperty:firstPropertyDict];
    
NSDictionary *secondPropertyDict = @{
  @"b" : @"3",
  @"c" : @"4"
  @"testString" : @"abc",
  @"testNumber" : @(12),
  @"testTime" : [NSDate now],
  @"testTime1" : @"2025-09-26",
  @"testTime2" : @"2025-09-26 10:57:05",
  @"testTime3" : @"2023-10-25 12:34:56.789",
  @"testBool" : @YES,
  @"testBool1" : @NO,
  @"groupTest" : @[@"abc",@"2025-09-26", @YES]   
  };
// The current global properties are a:1, b:3, c:4, etc.
[QTMobClick registerGlobalProperty:secondPropertyDict];

5.2 Get a global property

/**
 * Get a global property. Returns empty if it does not exist.
 */
+(NSString *) getGlobalProperty:(NSString *)propertyName;

5.3 Delete a global property

Deletes a specific global property. After deletion, subsequent events no longer include this property.

/**
 *
 * Delete the specified global property.
 @param key
 */
+(void) unregisterGlobalProperty:(NSString *)propertyName;

5.4 Get all global properties

/**
 * Get all global properties. Returns empty if none exist.
 */
+(NSDictionary *)getGlobalProperties;

5.5 Clear all global properties

/**
 * Clear all global properties.
 */
+(void)clearGlobalProperties;

6. Page view event API

The SDK provides two ways to report page view events: automatic page tracking and manual page tracking. You can also use both methods together.

6.1 Automatic page tracking

Automatic page tracking is implemented by hooking the system's `viewWillAppear` and `viewWillDisappear` methods to retrieve the class name. The SDK does not enable automatic page tracking by default. To enable it, you must call the interface before initialization.

Function:

+ (void)setAutoPageEnabled:(BOOL)value;

Example:

//Enable automatic page tracking
[QTMobClick setAutoPageEnabled:YES];

6.1.1 Disable automatic reporting for a single page

If you have globally enabled automatic page tracking, you can use this interface to skip automatic tracking for a single page. Call this at the beginning of `viewWillAppear`. To skip tracking for only the current automatic page view, set the `pageName` parameter to `nil`.

Function:

+ (void)skipMe:(id)PageObject pageName:(NSString *)pageName;

Example:

#import <QTCommon/UMSpmHybrid.h>

- (void)viewWillAppear:(BOOL)animated
{
  
    [super viewWillAppear:animated];

    //Do not track the current class for automatic page views
    [UMSpmHybrid skipMe:[self class] pageName:nil];
}

6.2 Manual page tracking

Function:

/** Automatic page duration tracking. Start recording the display duration of a page.
 How to use: You must call beginLogPageView: and endLogPageView: in pairs to complete automatic tracking. Calling only one of these functions will not generate valid data.
 Call beginLogPageView: when the page is displayed, and call endLogPageView: when you exit the page.
 @param pageName The name of the page to track.
 @return void.
 */
+ (void)beginLogPageView:(NSString *)pageName;

/** Automatic page duration tracking. Stop recording the display duration of a page.
 How to use: You must call beginLogPageView: and endLogPageView: in pairs to complete automatic tracking. Calling only one of these functions will not generate valid data.
 Call beginLogPageView: when the page is displayed, and call endLogPageView: when you exit the page.
 @param pageName The name of the page to track.
 @return void.
 */
+ (void)endLogPageView:(NSString *)pageName;

Parameters:

Note:

• You must call `beginLogPageView:` and `endLogPageView:` in pairs to complete page tracking. If you call only one of these functions, valid data will not be generated.

• Call `beginLogPageView:` when the page is displayed, and call `endLogPageView:` when you exit the page.

Example:

Call the following methods in pairs in the `viewWillAppear:` and `viewWillDisappear:` methods of your ViewController class:

- (void)viewWillAppear:(BOOL)animated
{
 [super viewWillAppear:animated];
 [QTMobClick beginLogPageView:@"Pagename"]; //("Pagename" is the page name, which you can customize)
}

- (void)viewWillDisappear:(BOOL)animated 
{
 [super viewWillDisappear:animated];
 [QTMobClick endLogPageView:@"Pagename"];
}

You can also call `beginLogPageView:` and `endLogPageView:` in pairs in methods such as `viewDidAppear:` and `viewDidDisappear:` to complete page tracking based on your business scenario.

6.2.1 Set page properties

The `updatePageProperties` interface for iOS lets you attach custom properties to the current page. Interface:

/**
 * @brief Update page business parameters.
 *
 * @param pageName Page name, such as Page_Detail.
 * @param pProperties Business parameters, as key-value pairs.
 *
 * @warning How to call: Must be called before viewWillDisappear.
 *
 * Best practice: Call before viewWillDisappear.
 */
+(void) updatePageProperties:(NSString *)pageName properties:(NSDictionary *) pProperties;

Parameters:

Note: You must set page properties after you call `beginLogPageView`.

Import header file:

#import <QTCommon/UMSpm.h>

Example:

[UMSpm updatePageProperties:@"page_home" properties: @{@"page_home_key":@"page_home_val"}];

Note: Setting page properties is only supported for manual page instrumentation.

6.2.2 Pass-through page properties

In addition, the QuickTracking SDK provides the `updateNextPageProperties` interface for pass-through page property instrumentation, which lets you attach custom properties to the next page.

/**
 * @brief  Update business parameters for the next page.
 *
 * @param properties Business parameters to pass to the next page, as key-value pairs.
 *
 * @warning  How to call: Must be called before the next page's pageAppear, otherwise it will carry incorrect data.
 *
 * Best practice: Call before the next page's pageAppear.
 */
+(void) updateNextPageProperties:(NSDictionary *) properties;

Parameters:

Example:

You must call this before `beginLogPageView` is called for the next page.

[UMSpm updateNextPageProperties:@{@"news_next_key":@"news_next_val"}];

Note: Pass-through page properties are only supported for manual page instrumentation.

7. Event instrumentation

You can use custom events to track user behavior and record the specific details of their actions.

7.1 Event instrumentation

Interface:

+ (void)event:(NSString *)eventCode; 

+ (void)event:(NSString *)eventCode attributes:(NSDictionary *)attributes;

+ (void)event:(NSString *)eventId pageName:(NSString *)pageName attributes:(NSDictionary *)attributes;

Parameter description:

Event upload limits:

• Maximum length of a custom property key string: 1024

• Maximum length of a custom property value string: 1024 × 4

• Maximum number of custom properties: 100 key-value pairs

• Maximum length of a custom property array: 100 elements

• Total length limit for a single log message: 2 MB

Data type description:

Example 1:

To count the number of times the Forward event occurs in the application, call the following code in the forward function:

[QTMobClick event:@"Forward"];

Example 2:

To count purchase events and track the type and quantity of purchased items, call the following code in the purchase function:

NSDictionary *dict = @{@"type" : @"book", @"quantity" : @"3"};
[QTMobClick event:@"purchase" attributes:dict];

Example 3:

NSDictionary *dict = @{@"type" : @"book", @"quantity" : @"3"};
[QTMobClick event:@"purchase" pageName:@"ViewController" attributes:dict];

Example 4:

NSDictionary *dict = @{
  @"testString" : @"abc",
  @"testNumber" : @(12),
  @"testTime" : [NSDate now],
  @"testTime1" : @"2025-09-26",
  @"testTime2" : @"2025-09-26 10:57:05",
  @"testTime3" : @"2023-10-25 12:34:56.789",
  @"testBool" : @YES,
  @"testBool1" : @NO,
  @"groupTest" : @[@"abc",@"2025-09-26", @YES]
  };
[QTMobClick event:@"purchase" attributes:dict];

7.2.1 Start timer (eventTimerStart)

Call this method when the event starts. This method generates a unique ID and starts a background task to save the timer.

Example:

@property (nullable, copy) NSString *video_id;

self.video_id = [QTMobClick eventTimerStart:@"watch_video"];

7.2.2 Set properties (setTimerProperties)

Use this method to associate metadata with the event, such as a title, URL, or type. You can call this method at any time after the event starts and before it ends.

Event upload limits:

• Maximum length of a custom property key string: 1024

• Maximum length of a custom property value string: 1024 × 4

• Maximum number of custom properties: 100 key-value pairs

• Maximum length of a custom property array: 100 elements

Data type description:

Example:

NSDictionary *dic = @{
                        @"video_id":@"10086",
                        @"category":@"movie",
                        @"video_title":@"Movie"
                    };
[QTMobClick setTimer:self.video_id withProperties:dic];

7.2.3 Pause timer (eventTimerPause)

Call this method when the user pauses a video or when the video is buffering. If this method is called multiple times, only the first call is effective. Repeated calls do not accumulate additional pause time.

Example:

[QTMobClick eventTimerPause:self.video_id];

7.2.4 Resume timer (eventTimerResume)

Call this method when the user resumes playback or when buffering ends. If this method is called multiple times, only the first call is effective.

Example:

[QTMobClick eventTimerResume:self.video_id];

7.2.5 End and report (eventTimerEnd)

Call this method when video playback ends, the user closes the page, or the user switches videos.
This method performs the following actions:

1. Calculates the final effective playback duration in milliseconds.

2. Builds the JSON-formatted data for reporting.

3. Triggers the reporting callback. You must implement this callback based on your instrumentation plan.

4. Clears the task from local storage and memory.

[QTMobClick eventTimerEnd:self.video_id];

7.3.6 Set auto-save interval (setEventTimeInterval)

Configures the automatic save interval. The default is 15 s. The configurable range is 1 s to 300 s.

Interface:

/** Set the interval for saving event duration data.
 @param interval Milliseconds. The default is 15 seconds.
 */
+ (void)setEventTimeInterval:(NSInteger)interval;

Example:

[QTConfigure setEventTimeInterval:10 * 1000];

8. Auto-instrumentation

8.1 Scope of auto-instrumentation

The SDK is compatible with iOS 8.0 and later.

8.2 Auto-instrumentation API description

8.2.1 Automatic page tracking interface

/** Set whether to automatically track pages. Default is NO (do not automatically track).
 @param value Set to YES, and the QT SDK will automatically track page information.
 */
+ (void)setAutoPageEnabled:(BOOL)value;

Example:

 [QTMobClick setAutoPageEnabled:YES];
 //Set the domain name
 [QTConfigure setCustomDomain:@"Your data collection domain name" standbyDomain:nil]; 
 //Initialize the AppKey
 [QTConfigure initWithAppkey:@"Your AppKey" channel:@"App Store"];

Disable automatic page tracking for a specific page

/**
 * @brief                   Skip tracking for the current page.
 *
 * @param     PageObject    Container object (used for automatic page tracking, can be nil for manual).
 * @param     pageName      Page name (used for manual page setting, can be nil for automatic).
 * @warning                 Call this interface before setting the page. After calling, data for the set native page will not be sent.
 *                          
 */
+ (void)skipMe:(id)PageObject pageName:(NSString *)pageName;

Example:

[UMSpmHybrid skipMe:self pageName:nil];

8.2.2 Enable auto-instrumentation for control clicks

You must call this before initialization. This feature is disabled by default.

/** Set whether to automatically track click events. Default is NO (do not automatically track).
 @param value Set to YES, and the QT SDK will automatically track click events.
 */
+ (void)setAutoEventEnabled:(BOOL)value;

Example:

 [QTMobClick setAutoEventEnabled:YES];
 //Set the domain name
 [QTConfigure setCustomDomain:@"Your data collection domain name" standbyDomain:nil]; 
 //Initialize the AppKey
 [QTConfigure initWithAppkey:@"Your AppKey" channel:@"App Store"];

Supported controls:

Ignore click events for a specific container

/**
 * @abstract
 * Ignore clicks on a specific page.
 *
 * @param PageObject The corresponding container.
 */
+(void)ignorePageView:(id)PageObject;

Example:

// This method can be called multiple times to ignore a collection of views.    
[QTAutoTrack ignorePageView:self];

Ignore automatic tracking of click events for a specific type of control

Use the `ignoreViewType` method to ignore automatic tracking of click events for a specific type of control.

/**
 * @abstract
 * Ignore clicks for a specific type.
 *
 * @param aClass The Class corresponding to the View.
 */
+(void)ignoreViewType:(Class)aclass;

Example:

// This method can be called multiple times to ignore a collection of types.    
[QTAutoTrack ignoreViewType:[UIButton class]];    
[QTAutoTrack ignoreViewType:[UISwitch class]];

Ignore automatic tracking of click events for a specific control

Use the `UMAnalyticsIgnoreView` method to ignore automatic tracking of click events for a specific control.

button.UMAnalyticsIgnoreView=YES;

8.2.3 Set custom information for a page

Set a custom code for a page

Implement the `-(NSString *)getUMPageName` method to return a custom code.

-(NSString *)getUMPageName
{
   return @"testPageCode";
}

Set custom properties for a page

Implement the `-(NSDictionary *)getUMPageProperties` method to set custom properties for a page.

-(NSDictionary *)getUMPageProperties
{
   return @{@"key1":@"val1",@"key2":@"val2"};
}

Set referrer (page_referrer) information for a page

Implement the `-(NSString *) getUMScreenUrl` method to return custom referrer information.

- (NSString *)getUMScreenUrl {
    return @"um//um/page";
}

8.2.4 Set custom properties for control click events

Using this method, you can set custom properties for a specific control. You can set multiple key-value pairs. Both the key and the value must be of type string. The custom properties and values are included in the auto-instrumentation click event data for this control.

button.UMAnalyticsViewProperties=@{@"key11":@"val11"};

Set an event code for a control

Using this method, you can set an event code for a specific control.

button.UMAnalyticsEventCode=@"abcd123";