Tracking API

1. Tracking plan

Before you begin tracking, you need to define where and what to track. In the Quick Tracking platform, these defined requirements are documented in a standardized template called a tracking plan.

A tracking plan specifies the following required components:

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

• Device ID: For macOS, the default device ID is a unique identifier at the application level, which is either generated automatically by the Quick Tracking SDK or set by calling the setCustomDeviceId API function.

• Account ID: The identifier from your client-side user sign-in system. The device ID changes when a user signs in on different devices, but the account ID remains the same. For example, a user signs in from two different computers.

2. User property: An attribute associated with an account ID. For example, for a user with the account ID "testdemo@111", the "birthday" might be "1999-02-13" and the "membership_level" might be "platinum." Here, "birthday" and "membership_level" are user properties.

3. Global property: An attribute that is set once and then included with every subsequent event.

4. Page view event: An event that is tracked when a page loads. In the tracking plan, this corresponds to an event where the page code and event code are identical, and is highlighted in blue.

5. Click, impression, and custom events: Events that are tracked when a user interacts with the client application in any way.

Tracking guidelines

• Parameter size limits

2. Predefined application events

2.1 Manually track the application start event

API function

// Manually track the application start event.
-(void)trackAppStart:(NSDictionary *_Nullable)properties;

Parameters

Example

NSDictionary *appStartProperties = @{
    @"appStartTest": @"appStartTest",
    @"times": @1024,
    @"subContents": @[@"test1", @"test2", @"test3"]
};
[[QuickTrackingSDK sharedInstance] trackAppStart:appStartProperties];

2.2 Manually track the application end event

API function

// Manually track the application end event.
-(void)trackAppEnd:(NSDictionary *_Nullable)properties;

Parameters

Example

NSDictionary *appEndProperties = @{
    @"appEndTest": @"appEndTest"
};
[[QuickTrackingSDK sharedInstance] trackAppEnd:appEndProperties];

3. Device ID

The SDK allows you to set a custom device ID. To use a custom device ID, you must call the setCustomDeviceId API function with a non-empty value. By default, the device ID is an encrypted version of the device's unique identifier.

3.1 Set a custom device ID

API function

// Set a custom device ID.
-(void)setCustomDeviceId:(NSString *_Nonnull)customDeviceID;

Parameters

Example

[[QuickTrackingSDK sharedInstance] setCustomDeviceId:@"your_deviceId"];

3.2 Get the device ID

API function

// Get the device ID.
-(NSString *_Nullable)getDeviceID;

Example

NSString *deviceID = [[QuickTrackingSDK sharedInstance] getDeviceID];

Usage notes

This method may return nil if the SDK is not fully initialized.

4. Account ID

4.1 User sign-in

To associate tracking data with your account system, call the onProfileSignIn method.

API function

// Sign in a user.
- (void)onProfileSignIn:(NSString *_Nonnull)userId;

Parameters

Example

[[QuickTrackingSDK sharedInstance] onProfileSignIn:@"your_userId"];

4.2 User sign-out

To stop associating data with a user account, call onProfieSignOff. After this call, the SDK stops including the account ID in events.

API function

// Sign out a user.
- (void)onProfieSignOff;

Example

[[QuickTrackingSDK sharedInstance] onProfieSignOff];

5. Set user properties

To set user properties, call the uploadUserProfile method. The properties you pass are then stored as user properties for the currently signed-in user.

API function

// Set user properties.
- (void)uploadUserProfile:(NSDictionary *_Nullable)properties;

Parameters

Example

NSDictionary *userProfile = @{
  @"name": @"your_name",
  @"email": @"example@example.com"
};
[[QuickTrackingSDK sharedInstance] uploadUserProfile:userProfile];

Usage notes

The SDK does not cache user properties. You must call onProfileSignIn to set the account ID before you set any user properties.

6. Global properties

6.1 Register global properties

API function

// Register global properties.
-(void)registerGlobalProperties:(NSDictionary * _Nonnull)properties;

Parameters

Data types

Note

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

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

3. If a key matches an existing global property key, the existing value is updated. If a key does not match an existing key, a new global property is created.

Example

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]
  };
[[QuickTrackingSDK sharedInstance] registerGlobalProperties:dict];

Usage notes

6.2 Unregister a global property

API function

// Unregister a global property by its key.
-(void)unregisterGlobalProperty:(NSString *_Nonnull)propertyName;

Parameters

Example

[[QuickTrackingSDK sharedInstance] unregisterGlobalProperty:@"your_key"];

6.3 Get a global property by key

API function

// Get a global property by its key.
-(id _Nullable)getGlobalProperty:(NSString *_Nonnull)propertyName;

Parameters

Return value

Example

id value = [[QuickTrackingSDK sharedInstance] getGlobalProperty:@"your_key"];

6.4 Get all global properties

API function

// Get all global properties.
-(NSDictionary *_Nullable)getGlobalProperties;

Return value

Example

NSDictionary *globalProperties = [[QuickTrackingSDK sharedInstance] getGlobalProperties];

6.5 Clear all global properties

API function

// Clear all global properties.
-(void)clearGlobalProperties;

Example

[[QuickTrackingSDK sharedInstance] clearGlobalProperties];

7. Page view events

Before you start, go to the Quick Tracking platform and navigate to Data Collection > Tracking Management > Event Management to create the necessary page events. Then, use the corresponding page code as the 'page_name' parameter in your project.

7.1 Track page entry

API function

// Track a page entry event.
+(void)onPageStart:(id _Nonnull)pageContext page_name:(NSString * _Nonnull)page_name options:(NSDictionary *_Nullable)options;

Parameters

Example

NSDictionary *pageOptions = @{
    @"url": @"your_url",
    @"page_title": @"your_page_title"
};
[QuickTrackingSDK onPageStart:self page_name:@"your_page_name" options:pageOptions];

7.2 Track page exit

API function

// Track a page exit event.
+(void)onPageEnd:(id _Nonnull)pageContext page_name:(NSString * _Nonnull)page_name;

Parameters

Example

[QuickTrackingSDK onPageEnd:self page_name:@"your_page_name"];

7.3 Update page properties

API function

// Update page properties.
+(void)updatePageProperties:(id _Nonnull)pageContext page_name:(NSString *_Nonnull)page_name properties:(NSDictionary *_Nonnull)properties;

Parameters

Example

NSDictionary *pageProperties = @{
    @"page_type": @"main",
    @"user_role": @"admin"
};
[QuickTrackingSDK updatePageProperties:self page_name:@"your_name" properties:pageProperties];

8. Track custom events

You can use custom events to track specific user behaviors and record details about those actions.

Before tracking events, create them on the Quick Tracking platform under Data Collection > Tracking Management > Event Management. Then, use the corresponding event code when calling the API.

API functions

// Track an event.
- (void)event:(NSString *_Nonnull)eventCode;
// Track an event with properties.
- (void)event:(NSString *_Nonnull)eventCode properties:(NSDictionary *_Nullable)properties;
// Track an event with a page code.
- (void)event:(NSString *_Nonnull)eventCode page_name:(NSString *_Nonnull)page_name;
// Track an event with a page code and properties.
- (void)event:(NSString *_Nonnull)eventCode page_name:(NSString *_Nonnull)page_name properties:(NSDictionary *_Nullable)properties;

Parameters

Data types

Note

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

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

Example 1

// Track an event.
NSString *eventCodeSimple = @"your_event_code";
[[QuickTrackingSDK sharedInstance] event:eventCodeSimple];

// Track an event with properties.
NSString *eventCodeWithProperties = @"your_event_code";
NSDictionary *yourProperties = @{
    @"item_name": @"your_item_name",
    @"item_price": @20
};
[[QuickTrackingSDK sharedInstance] event:eventCodeWithProperties properties:yourProperties];

// Track an event with a page code.
NSString *eventCodeWithPage = @"your_event_code";
NSString *page_name = @"homepage";
[[QuickTrackingSDK sharedInstance] event:eventCodeWithPage page_name:page_name];

// Track an event with a page code and properties.
NSString *eventCodeWithPageWithProperties = @"your_event_code";
NSString *page_name = @"settings_page";
NSDictionary *properties = @{
    @"button_name": @"save_settings",
    @"user_id": @"test"
};
[[QuickTrackingSDK sharedInstance] event:eventCodeWithPageWithProperties page_name:page_name properties:properties];

Example 2

// Custom data type properties.
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]
  };
[[QuickTrackingSDK sharedInstance] event:@"date_test" properties:dict];

9. Managing the SDK

9.1 Disable the SDK

After this method is called, the SDK stops collecting events and sending network requests.

API function

// Disable the SDK.
+(void)disableSDK;

Example

[QuickTrackingSDK disableSDK];

9.2 Enable the SDK

If the SDK was previously disabled, calling this method resumes data collection.

API function

// Enable the SDK.
+(void)enableSDK;

Example

[QuickTrackingSDK enableSDK];