自动采集

一、自动采集介绍

TE 系统提供自动化收集数据的接口，您可根据业务需求自行选择需要自动收集的数据。

现在支持的自动化收集数据有：

1. APP 安装，记录 APP 被安装的日志
2. APP 启动，包括打开 APP 和从后台唤醒
3. APP 关闭，包括关闭 APP 和调入后台，同时收集启动的时长
4. 用户在 APP 中浏览页面（原生页面）
5. 用户在 APP 中点击控件
6. APP 发生崩溃时记录崩溃信息

接下来将会详细介绍每种数据的采集方法

二、开启自动采集

您可以调用enableAutoTrack:，打开自动采集功能：

[TDAnalytics enableAutoTrack:
TDAutoTrackEventTypeAppStart |//APP 启动事件，记录 APP 启动或从后台恢复
TDAutoTrackEventTypeAppInstall |//APP 安装，记录 APP 被安装的日志
TDAutoTrackEventTypeAppEnd |//APP 关闭事件，记录 APP 调入后台
TDAutoTrackEventTypeAppViewScreen |//APP 浏览页面事件
TDAutoTrackEventTypeAppClick |//APP 点击控件事件
TDAutoTrackEventTypeAppViewCrash];//APP 崩溃事件

三、自动采集事件详解

3.1 APP 安装事件

APP 安装事件将会记录 APP 的实际安装，在 APP 启动时上报，事件触发时间是 APP 安装后首次启动的时间，APP 升级并不会触发安装事件，而删除重装后会上报安装事件。

• 事件名：ta_app_install

3.2 APP 启动事件

APP 启动事件将会在用户开启 APP，或从后台唤醒 APP 时触发，详细的事件介绍如下：

• 事件名：ta_app_start
• 预置属性：#resume_from_background，布尔型，表示 APP 是用户开启还是从后台唤醒，取值为 true 表示从后台唤醒，false 为直接开启。
• 事件名：ta_app_bg_start。当 APP 在后台启动时会触发此事件。该事件默认不会被采集，需要在初始化时开启配置项：

TDConfig *config = [[TDConfig alloc] init];
config.appid = appId;
config.serverUrl = serverUrl;

// 允许在后台采集事件
config.trackRelaunchedInBackgroundEvents = YES;

[TDAnalytics startAnalyticsWithConfig:config];
[TDAnalytics enableAutoTrack:TDAutoTrackEventTypeAll];

3.3 APP 关闭事件

APP 关闭事件将会在用户关闭 APP，或将 APP 调至后台时触发，详细的事件介绍如下：

• 事件名：ta_app_end
• 预置属性：#duration，数值型，表示该次 APP 访问（自启动至结束）的时长，单位是秒。

3.4 APP 浏览页面事件

APP 浏览页面事件将会在用户切换页面（View Controller）时，将会触发浏览页面事件，详细的事件介绍如下：

• 事件名：ta_app_view
• 预置属性：
• #screen_name，字符串型，为 View Controller 的类名
• #title，字符串型，为 View Controller 的标题，取值为controller.navigationItem.title属性的值

页面浏览事件中可以加入其它属性以扩展其分析价值，以下是自定义浏览页面事件的属性的方法:

3.4.1 自定义页面浏览事件的属性

对于继承自UIViewController的 View Controller，您可以通过实现 Protocol来设置属性以及页面的 URL 信息，SDK 将会自动将getTrackProperties:的返回值加入到该 View Controller 的 APP 浏览页面事件中；另外getScreenUrl:的返回值将会作为该页面的 URL Schema，当触发该页面的浏览事件时，将会加入预置属性#url，取值即为当前页面的 URL Schema，同时 SDK 会取跳转前页面的 URL Schema，如果能取到则会加入到预置属性#referrer中则为前向地址。

@interface MYController : UITableViewController<TDScreenAutoTracker>
@end

@implementation MYController

//对所有APPID实例进行设置

- (NSDictionary *)getTrackProperties {
    return @{@"PageName" : @"商品详情页", @"ProductId" : @12345};
}

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


/** 多APPID实例单独进行设置
 *  - (NSDictionary *)getTrackPropertiesWithAppid{
 *      return @{@"appid1" : @{@"testTrackProperties" : @"测试页"},
 *               @"appid2" : @{@"testTrackProperties2" : @"测试页2"},
 *               };
 *  }
 *  -(NSDictionary *)getScreenUrlWithAppid {
 *      return @{@"appid1" : @"APP://test1",
 *               @"appid2" : @"APP://test2",
 *               };
 *  }
 */

}
@end

• 相关预置属性：
• #url，字符串型，表示浏览页面的 URL
• #referrer，字符串型，表示页面跳转前页面的 URL

3.5 APP 控件点击事件

APP 控件点击事件将会在用户点击控件时触发

• 事件名：ta_app_click
• 预置属性：
• #screen_name，字符串型，为控件所在 View Controller 的类名
• #element_content，字符串型，为控件的内容
• #element_type，字符串型，为控件的类型
• #element_position，字符串型，只有当控件类型为UITableView或UICollectionView才会存在，表示控件被点击的位置，取值为组号(Section):行号(Row)

对于页面上 View 的点击事件，有以下多种方式来设置更多属性，以扩展其分析价值：

3.5.1 设置控件元素 ID

您可以为页面上的元素(View)设置元素 ID 以区分不同意义的元素，可以使用如下方法设置元素 ID：

//对所有APPID实例进行设置
self.table1.thinkingAnalyticsViewID = @"testtable1";

// 多APPID实例单独进行设置
// self.table1.thinkingAnalyticsViewIDWithAppid = @{ @"app1" : @"testtableID2",
                        @"app2" : @"testtableID3" };

此时table1的点击事件中会加入预置属性#element_id，取值即为此处的传入值

• 相关预置属性：#element_id，字符串型，表示该元素的自定义 ID

3.5.2 自定义控件点击事件的属性

对于大多数控件，可以直接使用thinkingAnalyticsViewProperties设置自定义属性：

//对所有APPID实例进行设置
self.table1.thinkingAnalyticsViewProperties = @{@"key1":@"value1"};

// 多APPID实例单独进行设置
// self.table1.thinkingAnalyticsViewPropertiesWithAppid = @{@"app1":@{@"tablekey":@"tablevalue"},
     @"app2":@{@"tablekey2":@"tablevalue2"}
   };

3.5.3 UITableView与UICollectionView控件点击事件的属性

对于UITableView与UICollectionView，则需要通过实现 Protocol来设置自定义属性：

1.首先在 View Controller 类中实现 Protocol

2.其次在类中设置代理，建议在viewDidLoad方法中进行设置

self.table1.thinkingAnalyticsDelegate = self;

• table1可替换为需要设置自定义属性的 View

3.之后根据 View Controller 的类型实现方法

• 此为UITableView需要实现的方法

//对所有APPID实例进行设置，设置UITableView的自定义属性
-(NSDictionary *) thinkingAnalytics_tableView:(UITableView *)tableView autoTrackPropertiesAtIndexPath:(NSIndexPath *)indexPath
{
    return @{@"testProperty":@"test"};
}

/** 多APPID实例单独进行设置
 * -(NSDictionary *) thinkingAnalyticsWithAppid_tableView:(UITableView *)tableView autoTrackPropertiesAtIndexPath:(NSIndexPath *)indexPath {
 *    return @{@"app1":@{@"autoPro":@"tablevalue"},
 *              @"app2":@{@"autoPro2":@"tablevalue2"}
 *            };
 * }
 */

• 此为UICollectionView需要实现的方法

//对所有APPID实例进行设置，设置UICollectionView的自定义属性
-(NSDictionary *) thinkingAnalytics_collectionView:(UICollectionView *)collectionView autoTrackPropertiesAtIndexPath:(NSIndexPath *)indexPath;
{
    return @{@"testProperty":@"test"};
}

/** 多APPID实例单独进行设置
 * - (NSDictionary *)thinkingAnalyticsWithAppid_collectionView:(UICollectionView *)collectionView autoTrackPropertiesAtIndexPath:(NSIndexPath *)indexPath {
 *     return @{@"app1":@{@"autoProCOLL":@"tablevalueCOLL"},
 *              @"app2":@{@"autoProCOLL2":@"tablevalueCOLL2"}
 *              };
 * }
 */

4.最后，在类中viewWillDisappear方法中将thinkingAnalyticsDelegate设置为nil

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

• table1可替换为需要设置自定义属性的 View，与设置代理时对应

3.6 APP 崩溃事件

当 APP 出现未捕获异常时，会上报 APP 崩溃事件

• 事件名：ta_app_crash
• 预置属性：
• #app_crashed_reason，字符型，记录崩溃时的堆栈轨迹

四、忽略自动采集事件

您可以通过以下方式，忽略某页面或控件的自动采集事件

4.1 忽略某个页面的自动采集事件

对于某些页面（View Controller），如果不想传输自动采集事件（包括页面浏览与控件点击事件），可以通过以下方法进行忽略：

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

// 忽略某个页面的自动采集事件
[TDAnalytics ignoreAutoTrackViewControllers:array];

4.2 忽略某个类型控件的点击事件

如果需要忽略某个类型控件的点击事件，可以使用以下方法进行忽略

// 忽略某个类型的所有控件
[TDAnalytics ignoreViewType:[IgnoredClass class]];

• ignoredClass即为需要忽略的控件类型

4.3 忽略某个元素（View）的点击事件

如果希望忽略某个元素（View）的点击事件，可以使用以下方法进行忽略

// 对所有APPID实例进行设置
self.table1.thinkingAnalyticsIgnoreView = YES;

// 多APPID实例单独进行设置
// self.table2.thinkingAnalyticsIgnoreViewWithAppid = @{@"appid1" : @YES,@"appid2" : @NO};

• table1可替换为需要忽略的 View

五、自动采集事件的预置属性

以下预置属性，是各个自动采集事件中所特有的预置属性

• APP 启动事件（ta_app_start）的预置属性

属性名	中文名	属性类型	说明
#resume_from_background	是否从后台唤醒	布尔	表示 APP 是被开启还是从后台唤醒，取值为 true 表示从后台唤醒，false 为直接开启
#start_reason	启动原因	文本	表示 APP 启动原因，value为字符串类型。目前支持收集deeplink、推送、3dtouch启动原因。
#background_duration	后台停留时长	数值	单位是秒

- APP 关闭事件（ta_app_end）的预置属性

属性名	中文名	属性类型	说明
#duration	事件时长	数值	表示该次 APP 访问（自启动至结束）的时长，单位是秒

- APP 浏览页面事件（ta_app_view）的预置属性

属性名	中文名	属性类型	说明
#title	页面标题	文本	为 View Controller 的标题，取值为controller.navigationItem.title属性的值
#screen_name	页面名称	文本	为 View Controller 的类名
#url	页面地址	文本	当前页面的地址，需要调用getScreenUrl进行 url 的设置
#referrer	前向地址	文本	跳转前页面的地址，跳转前页面需要调用getScreenUrl进行 url 的设置

- APP 控件点击事件（ta_app_click）的预置属性

属性名	中文名	属性类型	说明
#title	页面标题	文本	为 View Controller 的标题，取值为controller.navigationItem.title属性的值
#screen_name	页面名称	文本	为 View Controller 的类名
#element_id	元素 ID	文本	控件的 ID，需要thinkingAnalyticsViewID进行设置
#element_type	元素类型	文本	控件的类型
#element_selector	元素选择器	文本	为控件的viewPath的拼接
#element_position	元素位置	文本	控件的位置信息，只有当控件类型为UITableView或UICollectionView才会存在，表示控件被点击的位置，取值为组号(Section):行号(Row)
#element_content	元素内容	文本	控件上的内容

- APP 崩溃事件（ta_app_crash）的预置属性

属性名	中文名	属性类型	说明
#app_crashed_reason	异常信息	文本	字符型，记录崩溃时的堆栈轨迹

六、自动采集事件设置自定义属性

您可以调用enableAutoTrack:properties:，打开自动采集功能，同时设置自定义属性

// 自动化采集自定义属性
[TDAnalytics enableAutoTrack:TDAutoTrackEventTypeAll properties:@{@"auto_key1": @"auto_value1"}];

您也可以调用setAutoTrackProperties:properties:，设置或者更新自定义属性

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

七、自动采集事件回调

从v2.7.4 版本开始支持自动采集事件回调，您可以调用enableAutoTrack:callback:，打开自动采集功能，您可以在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 @{};
}];

请不要在此回调中做耗时操作，否则会影响数据正常入库