# iOS SDK Automatic Collection Guide
# I. Introduction to Automatic Acquisition
The TA system provides an interface for automatic data collection. You can choose the data that needs to be collected automatically according to your business needs.
Support for automated data collection now includes:
- App installation, record the log of APP installation
- APP startup, including opening the APP and waking up from the background
- APP shutdown, including shutdown of APP and transfer to the background, while collecting the duration of startup
- Users browse pages in the app (native pages)
- User clicks on controls in the app
- Record crash information when the APP crashes
Next, we will introduce in detail the collection method of each data
# II. Turn on Automatic Acquisition
You can use enableAutoTrack:
to turn on the automatic collection function:
// Open an automatic acquisition event for an APPID instance and support multiple APPID instances to enable automatic acquisition
[[ThinkingAnalyticsSDK sharedInstanceWithAppid:APP_ID]enableAutoTrack:ThinkingAnalyticsEventTypeAppStart |
ThinkingAnalyticsEventTypeAppInstall |
ThinkingAnalyticsEventTypeAppEnd |
ThinkingAnalyticsEventTypeAppViewScreen |
ThinkingAnalyticsEventTypeAppClick |
ThinkingAnalyticsEventTypeAppViewCrash];
// The following methods can be called to open a single APPID instance
// [[ThinkingAnalyticsSDK sharedInstance] enableAutoTrack:ThinkingAnalyticsEventTypeAppStart |
// ThinkingAnalyticsEventTypeAppInstall |
// ThinkingAnalyticsEventTypeAppEnd |
// ThinkingAnalyticsEventTypeAppViewScreen |
// ThinkingAnalyticsEventTypeAppClick |
// ThinkingAnalyticsEventTypeAppViewCrash];
The above parameters are expressed as:
ThinkingAnalyticsEventTypeAppInstall
, APP installation, record the log of APP installationThinkingAnalyticsEventTypeAppStart
, APP start event, record APP start or restore from backgroundThinkingAnalyticsEventTypeAppEnd
, APP shutdown event, record APP transferred to the backgroundThinkingAnalyticsEventTypeAppViewScreen
, APP browsing page eventThinkingAnalyticsEventTypeAppClick
, APP click control eventThinkingAnalyticsEventTypeAppViewCrash
, APP crash event
You can pass in the corresponding parameters of the event that need to be collected according to the business situation. Please use |
to split multiple parameters.
If you need to set public event properties or set custom guest IDs, be sure to call setSuperProperties: or identify: before turning on automatic collection.
-(BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
[ThinkingAnalyticsSDK startWithAppId:@"APP_ID"
withUrl:@"SERVER_URL"];
return YES;
}
[[ThinkingAnalyticsSDK sharedInstance] identify:@"123ABCabc"];
[[ThinkingAnalyticsSDK sharedInstance] setSuperProperties:@{
@"Channel":@"ABC",
@"Server":123,
@"isTest":@YES
}];
//After setting visitor ID and public attributes, start automatic collection
[[ThinkingAnalyticsSDK sharedInstance] enableAutoTrack:ThinkingAnalyticsEventTypeAppStart |
ThinkingAnalyticsEventTypeAppInstall |
ThinkingAnalyticsEventTypeAppEnd |
ThinkingAnalyticsEventTypeAppViewScreen |
ThinkingAnalyticsEventTypeAppClick |
ThinkingAnalyticsEventTypeAppViewCrash];
# III. Detailed Description of Automatic Acquisition Event
# 3.1 APP Installation Event
The APP installation event will record the actual installation of the APP and report it when the APP is started. The event trigger time is the time when the APP is first started after installation. The APP upgrade will not trigger the installation event, and the installation event will be reported after deletion and reinstallation.
- Event name: ta_app_install
# 3.2 APP Launch Event
The APP startup event will be triggered when the user opens the APP or wakes up the APP from the background. The detailed event description is as follows:
- Event name: ta_app_start
- Preset attribute:
#resume_from_background
, Boolean type, indicating whether the APP is turned on by the user or woken up from the background. The value of true indicates waking up from the background, and false is directly turned on.
# 3.3 APP Shutdown Event
The APP shutdown event will be triggered when the user closes the APP or adjusts the APP to the background. The detailed event is described as follows:
- Event name: ta_app_end
- Preset attribute:
#duration
, numeric, indicating the duration of the APP access (from start to end), in seconds.
# 3.4 APP Browsing Page Events
The APP browsing page event will trigger the browsing page event when the user switches the page (View Controller). The detailed event is described as follows:
- Event name: ta_app_view
- Preset properties:
#screen_name
, string type, the class name of the View Controller#title
, string type, is the title of the View Controller, and the value is the value of thecontroller.navigation I tem.title
attribute
Other properties can be added to the page browsing event to extend its analysis value. The following is how to customize the properties of the page browsing event:
# 3.4.1 Custom Properties for Page Browsing Events
For the View Controller inherited from UIViewController
, you can set the properties and the URL information of the page by implementing Protocol < TDScreenAutoTracker >
. The SDK will automatically add the return value of getTrackProperties:
to the APP browsing page event of the View Controller; in addition, the return value of getScreenUrl:
will be used as the URL Schema of the page. When the browsing event of the page is triggered, the preset attribute #url
will be added, and the value is the current page At the same time, the SDK will take the URL Schema of the page before the jump, and if it can be taken, it will be added to the preset property #referrer
as the forward address.
@interface MYController : UITableViewController<TDScreenAutoTracker>
@end
@implementation MYController
//Set up all APPID instances
- (NSDictionary *)getTrackProperties {
return @{@"PageName" : @"Product details page", @"ProductId" : @12345};
}
- (NSString *)getScreenUrl {
return @"APP://test";
/** Multiple APPID instances are set individually
* - (NSDictionary *)getTrackPropertiesWithAppid{
* return @{@"appid1" : @{@"testTrackProperties" : @"test page"},
* @"appid2" : @{@"testTrackProperties2" : @"test page2"},
* };
* }
* -(NSDictionary *)getScreenUrlWithAppid {
* return @{@"appid1" : @"APP://test1",
* @"appid2" : @"APP://test2",
* };
* }
*/
}
@end
- Related preset properties:
#url
, string type, represents the URL of the browsing page#referrer
, string type, represents the URL of the page before the page redirection
# 3.5 App Control Click Event
The APP control click event will be triggered when the user clicks the control
- Event name: ta_app_click
- Preset properties:
#screen_name
, string type, is the class name of the View Controller where the control is located#element_content
, string type, for the content of the control#element_type
, string type, is the type of control#element_position
, string type, only exists if the widget type isUITableView
orUICollectionView
, indicating the position where the control is clicked, the value isGroup Number (Section): Line Number (Row)
For viewing click events on a page, there are several ways to set more properties to extend their analytical value:
# 3.5.1 Set the control element ID
You can set the element ID for the element (View) on the page to distinguish elements with different meanings. You can set the element ID as follows:
//Set up all APPID instances
self.table1.thinkingAnalyticsViewID = @"testtable1";
// Multiple APPID instances are set individually
// self.table1.thinkingAnalyticsViewIDWithAppid = @{ @"app1" : @"testtableID2",
@"app2" : @"testtableID3" };
At this time, the preset attribute #element_id
will be added to the click event of table1
, and the value is the incoming value here.
- Related preset attribute:
#element_id
, string type, representing the customized ID of the element.
# 3.5.2 Properties of custom control click events
For most controls, you can set custom properties directly using thinkingAnalyticsViewProperties
:
//Set up all APPID instances
self.table1.thinkingAnalyticsViewProperties = @{@"key1":@"value1"};
// Multiple APPID instances are set individually
// self.table1.thinkingAnalyticsViewPropertiesWithAppid = @{@"app1":@{@"tablekey":@"tablevalue"},
@"app2":@{@"tablekey2":@"tablevalue2"}
};
# 3.5.3 UITableView and UICollectionView control click event properties
For UITableView
and UICollectionView
, you need to set custom properties by implementing Protocol < TDUIViewAutoTrackDelegate >
:
First implement Protocol
< TDUIViewAutoTrackDelegate > in the View Controller class
Secondly, set the proxy in the class, it is recommended to set it in the
viewDidLoad
method
self.table1.thinkingAnalyticsDelegate = self;
Table1
can be replaced with Views that need to set custom properties
- Then implement the method according to the type of View Controller
- This is the method that
UITableView
needs to implement
//Set all APPID instances to set custom attributes for UITableView
-(NSDictionary *) thinkingAnalytics_tableView:(UITableView *)tableView autoTrackPropertiesAtIndexPath:(NSIndexPath *)indexPath
{
return @{@"testProperty":@"test"};
}
/** Multiple APPID instances are set individually
* -(NSDictionary *) thinkingAnalyticsWithAppid_tableView:(UITableView *)tableView autoTrackPropertiesAtIndexPath:(NSIndexPath *)indexPath {
* return @{@"app1":@{@"autoPro":@"tablevalue"},
* @"app2":@{@"autoPro2":@"tablevalue2"}
* };
* }
*/
- This is the method that
UICollectionView
needs to implement
//Set all APPID instances to set custom attributes for UICollectionView
-(NSDictionary *) thinkingAnalytics_collectionView:(UICollectionView *)collectionView autoTrackPropertiesAtIndexPath:(NSIndexPath *)indexPath;
{
return @{@"testProperty":@"test"};
}
/** Multiple APPID instances are set individually
* - (NSDictionary *)thinkingAnalyticsWithAppid_collectionView:(UICollectionView *)collectionView autoTrackPropertiesAtIndexPath:(NSIndexPath *)indexPath {
* return @{@"app1":@{@"autoProCOLL":@"tablevalueCOLL"},
* @"app2":@{@"autoProCOLL2":@"tablevalueCOLL2"}
* };
* }
*/
- Finally, in the class the
viewWillDisappear
methodsets thinkingAnalyticsDelegate
tonil
-(void)viewWillDisappear:(BOOL)animated
{
[super viewWillDisappear:animated];
self.table1.thinkingAnalyticsDelegate = nil;
}
Table1
can be replaced with a View that needs to set custom properties, corresponding to when setting the proxy.
# 3.6 APP Crash Event
An app crash event is reported when the app has an uncaught exception
- Event name: ta_app_crash
- Preset properties:
#app_crashed_reason
, character type, record the stack trajectory when crashing
# IV. Ignoring Automatic Acquisition Events
You can ignore auto-capture events for a page or control by
# 4.1 Ignore Automatic Collection Events
For some pages (View Controller), if you do not want to transmit automatic collection events (including page browsing and control click events), you can ignore them by the following methods:
NSMutableArray *array = [[NSMutableArray alloc] init];
[array addObject:@"IgnoredViewController"];
// Multiple APPID instances are set for a single APPID instance, ignoring the automatic collection event for a page
[[ThinkingAnalyticsSDK sharedInstanceWithAppid:APP_ID] ignoreAutoTrackViewControllers:array];
// Callable from a single APPID instance
// [[ThinkingAnalyticsSDK sharedInstance] ignoreAutoTrackViewControllers:array];
# 4.2 Ignore Click Events for A Type of Control
If you need to ignore click events for a type of control, you can use the following methods to ignore.
// Set a single APPID instance when multiple APPID instances ignore all controls of a type
[[ThinkingAnalyticsSDK sharedInstanceWithAppid:APP_ID] ignoreViewType:[IgnoredClass class]];
// Callable from a single APPID instance
// [[ThinkingAnalyticsSDK sharedInstance] ignoreViewType:[IgnoredClass class]];
IgnredClass
is the widget type to ignore
# 4.3 Ignore Click Events for An Element (View)
If you want to ignore the click event of an element (View), you can use the following methods to ignore.
// Set up all APPID instances
self.table1.thinkingAnalyticsIgnoreView = YES;
// Multiple APPID instances are set individually
// self.table2.thinkingAnalyticsIgnoreViewWithAppid = @{@"appid1" : @YES,@"appid2" : @NO};
Table1
can be replaced with a View that needs to be ignored.
# V. Preset Properties of Automatic Acquisition Events
The following preset properties are unique to each AutoCollect event.
- Preset properties for APP launch event (ta_app_start)
Attribute name | Chinese name | Description |
---|---|---|
#resume_from_background | Whether to wake up from the background | Indicates whether the APP is turned on or woken up from the background, the value of true indicates waking up from the background, and false indicates direct opening |
#start_reason | Start reason | Represents the reason for the APP to start, and the value is of type string. Currently, it supports the collection of deeplink, push, and 3dtouch start reasons. |
#background_duration | Duration of backstage stay | In seconds |
- Preset properties for APP shutdown events (ta_app_end)
Attribute name | Chinese name | Description |
---|---|---|
#duration | Event duration | Represents the duration of the APP visit (from start to end) in seconds |
- Preset properties for APP browsing page events (ta_app_view)
Attribute name | Chinese name | Description |
---|---|---|
#title | Page Title | For the title of the View Controller, take the value of the controller.navigation I tem.title attribute |
#screen_name | Page name | Class name for View Controller |
#url | Page address | The address of the current page, you need to call getScreenUrl to set the url |
#referrer | Forward address | The address of the page before the jump, the page before the jump needs to call getScreenUrl to set the url |
- Preset properties for APP control click events (ta_app_click)
Attribute name | Chinese name | Description |
---|---|---|
#title | Page Title | For the title of the View Controller, take the value of the controller.navigation I tem.title attribute |
#screen_name | Page name | Class name for View Controller |
#element_id | Element ID | Control ID, need thinkingAnalyticsViewID to set |
#element_type | Element type | Type of control |
#element_selector | Element selector | Splicing for the viewPath of a control |
#element_position | Element location | Control location information, only if the widget type is UITableView or UICollectionView will exist, indicating the position where the control was clicked, the value is Group Number (Section): Line Number (Row) |
#element_content | Element content | Content on the control |
- Preset properties for app crash events (ta_app_crash)
Attribute name | Chinese name | Description |
---|---|---|
#app_crashed_reason | Abnormal information | Character type to record the stack trajectory when crashing |
# VI. Set Custom Attributes for Automatic Acquisition Events
You can call enableAutoTrack: properties:
, turn on the automatic collection function, and set custom properties at the same time
// Automatic Collection of Custom Properties
[[ThinkingAnalyticsSDK sharedInstance] enableAutoTrack:ThinkingAnalyticsEventTypeAll properties:@{@"auto_key1": @"auto_value1"}];
You can also call setAutoTrackProperties: properties:
to set or update custom properties
[[ThinkingAnalyticsSDK sharedInstance] setAutoTrackProperties:ThinkingAnalyticsEventTypeAppEnd properties: @{@"auto_key2": @"auto_value2"}];
# VII. Automated Acquisition Event Callback
Since v2.7.4 version supports automatic capture event callback, you can call enableAutoTrack: callback:
, turn on the automatic capture function, you can add and update properties in the callback.
[[ThinkingAnalyticsSDK sharedInstance] enableAutoTrack:ThinkingAnalyticsEventTypeAll callback:^NSDictionary * _Nonnull(ThinkingAnalyticsAutoTrackEventType eventType, NSDictionary * _Nonnull properties) {
if (eventType == ThinkingAnalyticsEventTypeAppStart) {
return @{@"addkey":@"addvalue"};
}
if (eventType == ThinkingAnalyticsEventTypeAppEnd) {
return @{@"updatekey":@"updatevalue"};
}
return @{};
}];
Please do not do time-consuming operations in this callback, otherwise it will affect the normal storage of data.