Auto-tracking

Last updated 10/03/2026

1. Auto-tracking overview

AE provides APIs for collecting data automatically. You can choose which data to collect automatically based on your business needs.

The auto-collected data currently supported includes:

1. APP install: Records the installation of the APP
2. APP start: Includes opening the APP and waking the APP from the background
3. APP end: Includes closing the APP and the APP moving to the background, and also collects the duration since start
4. The user views a page (native page) in the APP
5. The user clicks a control in the APP
6. Crash information is recorded when the APP crashes

The following sections describe how each type of data is collected

2. Enable auto-tracking

Call enableAutoTrack: to enable auto-tracking:

[TDAnalytics enableAutoTrack:
TDAutoTrackEventTypeAppStart |//APP start event
TDAutoTrackEventTypeAppInstall |//APP install event
TDAutoTrackEventTypeAppEnd |//APP end event
TDAutoTrackEventTypeAppViewScreen |//APP view page event
TDAutoTrackEventTypeAppClick |//APP control click event
TDAutoTrackEventTypeAppViewCrash];//APP crash event

3. Auto-tracked events in detail

3.1 APP install event

The APP install event records the actual installation of the APP and is reported when the APP starts. The event trigger time is the time of the first start after the APP is installed. Upgrading the APP doesn't trigger the install event, but deleting and reinstalling the APP reports an install event.

• Event name: ta_app_install

3.2 APP start event

The APP start event is triggered when the user opens the APP or wakes the APP from the background. Details of the event are as follows:

• Event name: ta_app_start. This event is triggered by the normal APP start process.
• Preset property: #resume_from_background, Boolean, indicates whether the APP was opened by the user or woken from the background. true means it was woken from the background, and false means it was opened directly.
• Event name: ta_app_bg_start. This event is triggered when the APP is launched in the background. It isn't collected by default; to collect it, enable the following configuration option during initialization:

  TDConfig *config = [[TDConfig alloc] init];
  config.appid = appId;
  config.serverUrl = serverUrl;
  
  // Allow events to be collected in the background
  config.trackRelaunchedInBackgroundEvents = YES;
  
  [TDAnalytics startAnalyticsWithConfig:config];
  [TDAnalytics enableAutoTrack:TDAutoTrackEventTypeAll];

3.3 APP end event

The APP end event is triggered when the user closes the APP or moves the APP to the background. Details of the event are as follows:

• Event name: ta_app_end
• Preset property: #duration, number, indicates the duration of this APP visit (from start to end), in seconds.

3.4 APP view page event

The APP view page event is triggered when the user switches pages (View Controller). Details of the event are as follows:

• Event name: ta_app_view
• Preset properties:
• #screen_name, string, the class name of the View Controller
• #title, string, the title of the View Controller, whose value is the value of the controller.navigationItem.title property

You can add other properties to page view events to extend their analytical value. The following describes how to customize the properties of view page events:

3.4.1 Customize the properties of page view events

For a View Controller that inherits from UIViewController, you can implement the Protocol <TDScreenAutoTracker> to set properties and the page's URL information. The SDK automatically adds the return value of getTrackProperties to the APP view page event of that View Controller. In addition, the return value of getScreenUrl is used as the URL Schema of the page. When the view event of this page is triggered, the preset property #url is added, whose value is the URL Schema of the current page. The SDK also gets the URL Schema of the page before the jump; if it can be obtained, it's added to the preset property #referrer as the referrer URL.

@interface MYController : UITableViewController<TDScreenAutoTracker>
@end

@implementation MYController

//Set for all APPID instances

- (NSDictionary *)getTrackProperties {
    return @{@"PageName" : @"Product details page", @"ProductId" : @12345};
}

- (NSString *)getScreenUrl {
    return @"APP://test";
}

/** Set separately for each APPID instance
 *  - (NSDictionary *)getTrackPropertiesWithAppid{
 *      return @{@"appid1" : @{@"testTrackProperties" : @"Test page"},
 *               @"appid2" : @{@"testTrackProperties2" : @"Test page 2"},
 *               };
 *  }
 *  -(NSDictionary *)getScreenUrlWithAppid {
 *      return @{@"appid1" : @"APP://test1",
 *               @"appid2" : @"APP://test2",
 *               };
 *  }
 */

@end

Related preset properties:

• #url, string, the URL of the page being viewed
• #referrer, string, the URL of the page before the jump

3.5 APP control click event

The app control click event is triggered when the user clicks a control

• Event name: ta_app_click
• Preset properties:
• #screen_name, string, the class name of the View Controller that the control belongs to
• #element_content, string, the content of the control
• #element_type, string, the type of the control
• #element_position, string, exists only when the control type is UITableView or UICollectionView, and indicates the position where the control was clicked. The value is section number(Section):row number(Row)

For click events of Views on a page, you can set more properties in the following ways to extend their analytical value:

3.5.1 Set the control element ID

You can set element IDs for elements (Views) on a page to distinguish elements with different meanings. Use the following method to set an element ID:

//Set for all APPID instances
self.table1.thinkingAnalyticsViewID = @"testtable1";

// Set separately for each APPID instance
self.table1.thinkingAnalyticsViewIDWithAppid = @{ @"app1" : @"testtableID2",
                        @"app2" : @"testtableID3" };

The click events of table1 then include the preset property #element_id, whose value is the value passed in here

• Related preset property: #element_id, string, the custom ID of the element

3.5.2 Customize the properties of control click events

For most controls, you can use thinkingAnalyticsViewProperties directly to set custom properties:

//Set for all APPID instances
self.table1.thinkingAnalyticsViewProperties = @{@"key1":@"value1"};

// Set separately for each APPID instance
self.table1.thinkingAnalyticsViewPropertiesWithAppid = @{@"app1":@{@"tablekey":@"tablevalue"},
    @"app2":@{@"tablekey2":@"tablevalue2"}
};

3.5.3 Properties of UITableView and UICollectionView click events

For UITableView and UICollectionView, you need to implement the Protocol <TDUIViewAutoTrackDelegate> to set custom properties:

1. First, implement the Protocol <TDUIViewAutoTrackDelegate> in the View Controller class

2. Next, set the delegate in the class. We recommend doing this in the viewDidLoad method

self.table1.thinkingAnalyticsDelegate = self;

• Replace table1 with the View for which you want to set custom properties

3. Then implement the methods based on the type of View Controller

• The following method must be implemented for UITableView

//Set for all APPID instances: set custom properties for UITableView
-(NSDictionary *) thinkingAnalytics_tableView:(UITableView *)tableView autoTrackPropertiesAtIndexPath:(NSIndexPath *)indexPath
{
    return @{@"testProperty":@"test"};
}

/** Set separately for each APPID instance
 * -(NSDictionary *) thinkingAnalyticsWithAppid_tableView:(UITableView *)tableView autoTrackPropertiesAtIndexPath:(NSIndexPath *)indexPath {
 *    return @{@"app1":@{@"autoPro":@"tablevalue"},
 *              @"app2":@{@"autoPro2":@"tablevalue2"}
 *            };
 * }
 */

• The following method must be implemented for UICollectionView

//Set for all APPID instances: set custom properties for UICollectionView
-(NSDictionary *) thinkingAnalytics_collectionView:(UICollectionView *)collectionView autoTrackPropertiesAtIndexPath:(NSIndexPath *)indexPath;
{
    return @{@"testProperty":@"test"};
}

/** Set separately for each APPID instance
 * - (NSDictionary *)thinkingAnalyticsWithAppid_collectionView:(UICollectionView *)collectionView autoTrackPropertiesAtIndexPath:(NSIndexPath *)indexPath {
 *     return @{@"app1":@{@"autoProCOLL":@"tablevalueCOLL"},
 *              @"app2":@{@"autoProCOLL2":@"tablevalueCOLL2"}
 *              };
 * }
 */

4. Finally, set thinkingAnalyticsDelegate to nil in the viewWillDisappear method of the class

-(void)viewWillDisappear:(BOOL)animated
{
    [super viewWillDisappear:animated];
    self.table1.thinkingAnalyticsDelegate = nil;
}

• Replace table1 with the View for which you want to set custom properties; it must match the View you set the delegate on

3.6 APP crash event

When an uncaught exception occurs in the APP, an APP crash event is reported

• Event name: ta_app_crash
• Preset properties:
• #app_crashed_reason, string, records the stack trace at the time of the crash

4. Ignore auto-tracked events

You can ignore the auto-tracked events of a page or control in the following ways

4.1 Ignore auto-tracked events of a page

If you don't want to send auto-tracked events (including page view and control click events) for certain pages (View Controller), use the following method to ignore them:

NSMutableArray *array = [[NSMutableArray alloc] init];
[array addObject:@"IgnoredViewController"];

// Ignore auto-tracked events of a page
[TDAnalytics ignoreAutoTrackViewControllers:array];

4.2 Ignore click events of a control type

To ignore the click events of a certain type of control, use the following method

// Ignore all controls of a type
[TDAnalytics ignoreViewType:[IgnoredClass class]];

• IgnoredClass is the control type to ignore

4.3 Ignore click events of an element (View)

To ignore the click events of a specific element (View), use the following method

// Set for all APPID instances
self.table1.thinkingAnalyticsIgnoreView = YES;

// Set separately for each APPID instance
// self.table2.thinkingAnalyticsIgnoreViewWithAppid = @{@"appid1" : @YES,@"appid2" : @NO};

• Replace table1 with the View to ignore

5. Preset properties of auto-tracked events

The following preset properties are specific to each auto-tracked event

• Preset properties of the APP start event (ta_app_start)

Property name	Display name	Property type	Description
#resume_from_background	Resumed from background	Boolean	Indicates whether the APP was opened or woken from the background. true means it was woken from the background, and false means it was opened directly
#start_reason	Launch reason	Text	The reason the APP was launched; the value is a string. Currently, deeplink, push, and 3D Touch launch reasons can be collected.
#background_duration	Background duration	Numeric	In seconds

• Preset properties of the APP end event (ta_app_end)

Property name	Display name	Property type	Description
#duration	Event duration	Number	The duration of this APP visit (from start to end), in seconds

• Preset properties of the APP view page event (ta_app_view)

Property name	Display name	Property type	Description
#title	Page Title	Text	The title of the View Controller, whose value is the value of the controller.navigationItem.title property
#screen_name	Page name	Text	The class name of the View Controller
#url	Page URL	Text	The URL of the current page. Call getScreenUrl to set the URL
#referrer	Referrer URL	Text	The URL of the page before the jump. That page must call getScreenUrl to set the URL

• Preset properties of the APP control click event (ta_app_click)

Property name	Display name	Property type	Description
#title	Page Title	Text	The title of the View Controller, whose value is the value of the controller.navigationItem.title property
#screen_name	Page name	Text	The class name of the View Controller
#element_id	Element ID	Text	The ID of the control, which must be set with thinkingAnalyticsViewID
#element_type	Element type	Text	The type of the control
#element_selector	Element selector	Text	The concatenation of the control's viewPath
#element_position	Element position	Text	Position of the control. Exists only when the control type is UITableView or UICollectionView, and indicates the position where the control was clicked. The value is section number(Section):row number(Row)
#element_content	Element content	Text	The content on the control

• Preset properties of the APP crash event (ta_app_crash)

Property name	Display name	Property type	Description
#app_crashed_reason	Exception information	Text	String. Records the stack trace at the time of the crash

6. Set custom properties for auto-tracked events

Call enableAutoTrack:properties: to enable auto-tracking and set custom properties at the same time

// Custom properties for auto-tracking
[TDAnalytics enableAutoTrack:TDAutoTrackEventTypeAll properties:@{@"auto_key1": @"auto_value1"}];

You can also call setAutoTrackProperties:properties: to set or update custom properties

[TDAnalytics setAutoTrackProperties:TDAutoTrackEventTypeAll properties:@{@"auto_key2": @"auto_value2"}];

7. Auto-tracked event callback

Starting from v2.7.4, auto-tracked event callbacks are supported. Call enableAutoTrack:callback: to enable auto-tracking, and add or update properties in the callback.

[TDAnalytics enableAutoTrack:TDAutoTrackEventTypeAll callback:^NSDictionary * _Nonnull(TDAutoTrackEventType eventType, NSDictionary * _Nonnull properties) {
    if (eventType == TDAutoTrackEventTypeAppStart) {
      return @{@"addkey":@"addvalue"};
    }
    if (eventType == TDAutoTrackEventTypeAppEnd) {
      return @{@"updatekey":@"updatevalue"};
    }
    return @{};
}];

Don't perform time-consuming operations in this callback; otherwise, data may not be stored normally