Quick Tracking:Tracking API

1. How do I view a tracking plan?

Before embedding points, it is necessary to determine where to track and which to track, that is, it is necessary to sort out the clear requirements for tracking. In the QuickTracking platform, the explicit requirements of the tracking are called the tracking plan, and a specification template is designed for the tracking plan. Examples:

In the tracking plan, the required tracking contents are as follows:

1. Event subject: the "who" triggered the event. The event can be divided into device ID and account ID. The event must have one of them.

• Device ID: Default device IDs of Android and iOS devices are app-level unique device IDs, which are automatically generated by Quicktracking.

  • Devices that use Android 9 or the following devices: The SDK automatically tracks imei, wifimac, androidid, and serial number to generate device IDs. After the device IDs are generated, the device IDs are stored locally. The device IDs are generated again only after the application is uninstalled or the application data is deleted.

  • Devices above the Android level 10 level: The SDK automatically tracks the oaid, gaid, androidid, and serial number to generate device IDs. After the device IDs are generated, the device IDs are stored locally. The device IDs are generated again only after the application is uninstalled or the application data is deleted.

  • iOS devices: The SDK automatically tracks openudid to generate a device ID. After the device ID is generated, it is placed in the keychain. The device ID is generated again only after factory settings are restored or application data is deleted.

  • The Quick Tracking SDK tracks IDFAs and OAIDs only if the C- terminal users of the application agree to track IDFAs and OAIDs. Only QuickTracking app SDK can track OAID, GAID, Imei, WiFIMAC, AndroIID, SN, IDFV.

• Account ID: the account ID of the client user after logging in. When a user logs in from different devices, the device ID changes, but the account ID does not change. For example, a user uses a mobile phone and a pad to log in separately.

2. User attribute: for the attribute of account ID, for example, the user with account ID of "testdemo@111", "birthday" of "1999-02-13", "member level" of "platinum", etc. The "birthday" and "membership" ratings are user attributes.

3. Channel attributes: attributes of advertisement delivery, such as delivery channel, delivery method, and delivery content.

4. Global attribute: the attribute carried by each event after global setting once

5. Page browsing events: events reported during page loading (events with equal page code and event code in the tracking plan are also events marked in blue)

6. Click, exposure, and custom events: events reported when the client user interacts with the client.

2. Set the device ID and account ID

2.1 Device ID Settings

The SDK tracks the following parameters by default.

If the developer wants to control the tracking of certain device identifiers in the preceding table, for example, the developer does not track the device identifiers or implements the tracking method by itself. You can implement the corresponding block callback, as shown in the following example:

[QTConfigure customSetIdfaBlock:^NSString *{
  return @"";
}];
[QTConfigure customSetIdfvBlock:^NSString *{
  return @"";
}];
[QTConfigure customSetOpenUdidBlock:^NSString *{
  return @"custom-openudid";
}];
[QTConfigure customSetUtdidBlock:^NSString *{
  return @"custom-utdid";
}];
[QTConfigure customSetMccBlock:^NSString *{
  return @"custom-mcc";
}];
[QTConfigure customSetMncBlock:^NSString *{
  return @"custom-mnc";
}];

Note: Exercise caution when you decide whether to implement the corresponding method. Once you choose to implement the method, you are in charge of tracking the device identifier. The SDK will not attempt to track the device identifier. The fewer device identifiers that can be tracked by the SDK, the greater the negative impact on the accuracy and stability of statistical data.

// Before you set the tracking domain name and call the SDK pre-initialization function, call the tracking tool class registration function.
// If you do not need to control the device identity tracking behavior, you do not need to implement a custom utility class and register it.
[QTConfigure customSetIdfvBlock:^NSString *{
    return [[UIDevice currentDevice].identifierForVendor UUIDString];
}];
[QTConfigure setCustomDomain:@"Your receipt domain name" standbyDomain:nil];
[QTConfigure initWithAppKey:@"Your appkey" channel:@"App Store"]; 

The SDK supports custom device IDs. If you want to use custom device IDs, you must set setCustomDeviceId to a valid value (not empty) before initialization (that is, before init).

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

Example:

[QTConfigure setCustomDeviceId:@"xxxxxx"];

Note: This function takes effect when no device ID is obtained. If a device ID already exists in the local device, the setting is invalid. If the device ID is obtained locally, you can uninstall and reinstall the device.

2.2 Account ID Settings

1. QT takes the device as the standard when counting users. If you need to count the account of the application itself, please use the following API:

API functions:

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

Parameter:

Note: After the account ID is set, it will be stored in the local storage. The account ID will become invalid only when the app is uninstalled, the application data is cleared, or the following logout interface is called. Otherwise, each event will carry the account ID.

Sample code:

[QTMobClick profileSignInWithPUID:@"UserID"];

If you no longer need to bind a user account, you can call the logout interface. After you call the logout interface, the account-related content is no longer sent.

+ (void)profileSignOff;

Sample code:

[QTMobClick profileSignOff];

2.3 device ID acquisition

Interface functions:

+ (NSString *)umidString;

Sample code:

NSString *deviceID = [QTConfigure umidString];

3 Upload user attributes

1. Upload a custom event whose event code is fixed as "$$_user_profile". The event attributes carried by the event are placed in the user table as user attributes.

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

Note: User attributes must be uploaded after the account statistics call

4 Channel attributes

After the channel attributes take effect, all subsequent events will automatically include these attributes, and these attributes and attribute values will be stored in the cache and cleared after the APP process ends. When analyzing data, you can view and filter based on this property.

4.1 H5 Link Evokes App

1. The URL plan of the app contains these channel attributes, and the attribute key must start with "utm_" because the keyword recognized by the SDK is "utm_". For example: <URL plan>? utm_channel=gzh

2. Add your URL plan to the project. The URL plan is located in the project settings target -> tab Info ->URL Types. The filled-in plan. Call function [MobClick handleUrl:url] in AppDelegate to receive URL

AppDelegate calls:

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

 return YES;
}

SceneDelegate calls:

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

PS: If you have cooperated with a channel delivery company on the market and cannot start with utm_, you can use the Global Attributes API to report the channel attributes. The attribute key must start with utm_.

4.2 The H5 link arouses the application market to download and launch the application

In this scenario, if only the utm_parameter is included in the H5 URL, the utm_parameter cannot be included in the startup event after the app is downloaded. Therefore, it is necessary to perform fuzzy matching between "H5 arousal event" and "application activation event" on "IP address and browser UserAgent ".

1. When a user clicks the "Call /Download App" button in H5, an "app call event ($$_app_link)" is reported. In the event, the appkey and channel attribute of the call app must be included.

// Sample code
aplus_queue.push({
  action:'aplus.recordAppLink',
  arguments:[{
    targetAppKey: 'Application appKey', // Required. The appKey of the application to be evoked.
    custom1: 'custom1', // Optional. The custom parameter.
    ...
  }]
})

2. The app activation event ($$_app_install) is automatically tracked and reported by the QT App SDK.

3. The QuickTracking system performs fuzzy matching between an application evocation event ($$_app_link) and an application activation event ($$_app_install) with respect to the IP address and browser UserAgent. When you use it, you can directly analyze the channel properties of "application activation (preset)" in the app application.

4.3 Active Data Statistics of App Market

The second input parameter in the initialization function is the Marketplace of the application: [QTConfigure initWithAppkey:@"Your appkey" channel:@"App Store"];. You can view the update channel in the System Properties section.

5 Global attributes

After global attributes are registered, all subsequent events will automatically include these attributes, and these attributes and attribute values will be stored in the cache and cleared after the APP process ends. When analyzing data, you can view and filter based on this property.

5.1 Register Global Attributes

/**
 * Set global property key-value pairs. 
 * If the key of an existing global attribute is the same as the key of the existing global attribute, the existing value is updated.
 * If the key of an existing global attribute is inconsistent with the key of an existing global attribute, a new global attribute is inserted.
 */
+(void) registerGlobalProperty:(NSDictionary *)property;

Example:

NSDictionary *firstPropertyDict = @{
     @"a" : @"1",
     @"b" : @"2"
};
[QTMobClick registerGlobalProperty:firstPropertyDict];// The current globalproperty is a:1 and b:2
    
NSDictionary *secondPropertyDict = @{
     @"b" : @"3",
     @"c" : @"4"
};
[QTMobClick registerGlobalProperty:secondPropertyDict];// The current globalproperty is a:1, b:3, and c:4 

5.2 Get a Global Property

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

5.3 delete a global attribute

Deletes a specific global property. After the property is deleted, all subsequent events that are triggered no longer carry the property.

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

5.4 Get All Global Properties

/**
 * Get all global properties; if they do not exist, return empty. 
 */
+(NSDictionary *)getGlobalProperties;

5.5 Clear All Global Attributes

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

6 Page Browsing Event API

The SDK provides two methods to report page browsing events: automatic page tracking and manual page tracking. The two methods can also be used together.

6.1 page automatic tracking

The automatic tracking of pages is implemented by hook system viewWillAppear and viewWillDisappear and get className. By default, automatic page tracking is disabled for the SDK. If you want to enable this feature, we recommend that you call this operation before initialization.

Interface functions:

+ (void)setAutoPageEnabled:(BOOL)value;

Sample code:

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

6.1.1 Disable automatic reporting of a single page

If you enable automatic page tracking globally, you can call this operation to skip automatic page tracking. We recommend that you call this operation at the beginning of the viewWillAppear operation. If you do not track statistics on the current automatic page tracking, you can set the pageName parameter to nil.

Interface functions:

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

Example

#import <QTCommon/UMSpmHybrid.h>

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

    // Automatic page tracking of the current class is not counted.
    [UMSpmHybrid skipMe:[self class] pageName:nil];
}

Manual tracking of 6.2 pages

Interface functions:

/**Automatic page duration statistics to record the display duration of a page.
 Usage: You must call the beginLogPageView: and endLogPageView: two functions to complete automatic statistics. If only one function is called, valid data will not be generated. 
 Call beginLogPageView: when the page is displayed, and endLogPageView when exiting the page:
 @ param pageName The name of the page on which statistics are tracked.
 @return void.
 */
+ (void)beginLogPageView:(NSString *)pageName;

/**Automate page duration statistics to record the display duration of a page.
 Usage: You must call the beginLogPageView: and endLogPageView: two functions to complete automatic statistics. If only one function is called, valid data will not be generated. 
 Call beginLogPageView: when the page is displayed, and endLogPageView when exiting the page:
 @ param pageName The name of the page on which statistics are tracked.
 @return void.
 */
+ (void)endLogPageView:(NSString *)pageName;

Parameter:

Note

• You must pair call beginLogPageView: and endLogPageView: two functions to complete automatic statistics. If only one function is called, valid data will not be generated;

• Call beginLogPageView: when the page is displayed, and call endLogPageView: when the page is exited.

Sample code:

In the ViewController class, call the following methods in pairs in viewWillAppear: and viewWillDisappear::

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

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

You can also call the beginLogPageView: and endLogPageView: functions in the viewDidAppear: and viewDidDisappear: methods to complete automatic statistics based on your business scenario.

6.2.1 Page property settings

The iOS page property setting interface updatePageProperties allows you to attach custom properties to the current page. Interface:

/**
 * @brief Updates the business parameters on the page.
 *
 * @param pageName The name of the page, such as Page_Detail.
 * @param pProperties The business parameters, which are kv pairs.
 *
 * @warning Call description: must be called before the viewWillDisappear
 *
 * Best location: call before viewWillDisappear
 */
+(void) updatePageProperties:(NSString *)pageName properties:(NSDictionary *) pProperties;

Parameter:

Note: Please call beginLogPageView after setting page properties.

Introduce header files:

#import <QTCommon/UMSpm.h>

Example

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

Note: You can configure only manual tracking for a page.

6.2.2 Pass through page properties

In addition, the Quick Tracking SDK also provides the pass-through page property tracking interface updateNextPageProperties, which allows you to attach custom properties to the next page.

/**
 * @brief Updates the business parameters on the next page.
 *
 * @param properties Pass the business parameters to the next page. The KV pair
 *
 * @warning Call description: The call must be made before pageAppear on the next page. Otherwise, an error is carried.
 *
 * Best location: must be called before pageAppear on the next page
 */
+(void) updateNextPageProperties:(NSDictionary *) properties;

Parameters:

Example:

Must be called before the next page beginLogPageView.

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

Note: You can use only manual tracking for page attributes.

7 Event Tracking

Custom events can be used to track user behavior and record the specific details of behavior occurrence.

7.1 Event tracking

Interface:

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

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

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

Parameters

Event upload quantity limit:

• Maximum length of custom property key string: 1024

• Maximum length of the custom attribute value string: 1024*4

• Custom attribute map length (number of parameters):100 key-value pairs

• When the custom property value is an array element, the maximum array length of the property value is 100.

• The total length of a single log message is limited to 2MB.

Example 1:

Count the number of times the "forward" event occurs in the application, then call in the forwarding function:

[QTMobClick event:@"Forward"];

Example 2:

To count the number of times the "purchase" event occurs in the application, as well as the type and quantity of purchased goods, then call 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];

8 Full embedding point (automatic embedding point)

8.1 full buried point applicable scope

The SDK is applicable to iOS 8.0 and later.

8.2 Full Buried Point Interface Description

8.2.1 Automatic page tracking interface

/**Set whether to automatically track data. The default value is NO.
 @ param value is set to YES, the QT SDK automatically tracks page information
 */
+ (void)setAutoPageEnabled:(BOOL)value;

Example

 [QTMobClick setAutoPageEnabled:YES];
 // Set the domain name.
 [QTConfigure setCustomDomain:@"Your receipt domain name" standbyDomain:nil]; 
 // Initialize the appkey.
 [QTConfigure initWithAppkey:@"AppKey of your application" channel:@"App Store"]; 

Disable automatic page tracking for a page

/**
 * @brief Skips the statistics on the current page.
 *
 * @param PageObject The object of the container. This parameter is used to automatically obtain the page. By default, this parameter can be set to nil.
 * @param pageName The name of the page. This parameter is used when you manually configure the page. You can enter nil when you configure automatic page retrieval.
 * @warning We recommend that you call this operation before you set the page. After you call this operation, the native page does not send data.
 *                          
 */
+ (void)skipMe:(id)PageObject pageName:(NSString *)pageName;

Example:

[UMSpmHybrid skipMe:self pageName:nil];

8.2.2 Open the control and click the data tracking

It is recommended to call before initialization, which is closed by default.

/**Set whether to automatically track click events. The default value is NO.
 @ param value is set to YES, the QT SDK automatically tracks click events
 */
+ (void)setAutoEventEnabled:(BOOL)value;

Example:

 [QTMobClick setAutoEventEnabled:YES];
 // Set the domain name.
 [QTConfigure setCustomDomain:@"Your receipt domain name" standbyDomain:nil]; 
 // Initialize the appkey.
 [QTConfigure initWithAppkey:@"AppKey of your application" channel:@"App Store"]; 

Supported controls:

Ignore the click event of a container

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

Example:

// This method supports multiple calls and ignores the tracking.    
[QTAutoTrack ignorePageView:self];

Ignore automatic tracking of click events of specific types of controls

Automatic tracking of click events for controls of a specific type is ignored by using the ignoreViewType method.

/**
 * @abstract
 * Ignore a certain type of click
 *
 * @param aClass View the corresponding Class
 */
+(void)ignoreViewType:(Class)aclass;

Example:

// This method supports multiple calls and ignores the tracking.    
[QTAutoTrack ignoreViewType:[UIButton class]];    
[QTAutoTrack ignoreViewType:[UISwitch class]];

Ignore automatic tracking of click events of specific controls

Automatic tracking of click events for a specific control is ignored by the UMAnalyticsIgnoreView method.

button.UMAnalyticsIgnoreView=YES;

8.2.3 Page Setup Custom Information

Custom Encoding for Page Settings

By implementing the-(NSString *)getUMPageName method, a custom encoding is returned

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

Custom Properties

Set custom properties on the page by implementing the-(NSDictionary *)getUMPageProperties method

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

Page setting source (page_referrer) information

You can use the-(NSString *) getUMScreenUrl method to return information about a custom source.

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

8.2.4 Setting Custom Properties for Control Click Events

This method allows you to set custom properties for a specific control. You can set multiple key-value pairs for custom properties. Both Key and Value need to be of the string type. The custom properties and values are included in this control's full-click event data.

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

Set Event Code for Control

This method allows you to set the event encoding for a specific control.

button.UMAnalyticsEventCode=@"abcd123";