iOS SDK 自动采集指南

1. 自动采集介绍

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

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

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

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

2. 开启自动采集

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

// 开启某个APPID实例的自动采集事件，支持多个APPID实例都开启自动采集
[[ThinkingAnalyticsSDK sharedInstanceWithAppid:APP_ID]enableAutoTrack:ThinkingAnalyticsEventTypeAppStart |
ThinkingAnalyticsEventTypeAppInstall |
ThinkingAnalyticsEventTypeAppEnd |
ThinkingAnalyticsEventTypeAppViewScreen |
ThinkingAnalyticsEventTypeAppClick |
ThinkingAnalyticsEventTypeAppViewCrash];

// 单APPID实例时可调用以下方法开启
// [[ThinkingAnalyticsSDK sharedInstance] enableAutoTrack:ThinkingAnalyticsEventTypeAppStart |
// ThinkingAnalyticsEventTypeAppInstall |
// ThinkingAnalyticsEventTypeAppEnd |
// ThinkingAnalyticsEventTypeAppViewScreen |
// ThinkingAnalyticsEventTypeAppClick |
// ThinkingAnalyticsEventTypeAppViewCrash];

以上参数分别表示为：

• ThinkingAnalyticsEventTypeAppInstall，APP安装，记录APP被安装的日志
• ThinkingAnalyticsEventTypeAppStart，APP启动事件，记录APP启动或从后台恢复
• ThinkingAnalyticsEventTypeAppEnd，APP关闭事件，记录APP调入后台
• ThinkingAnalyticsEventTypeAppViewScreen，APP浏览页面事件
• ThinkingAnalyticsEventTypeAppClick，APP点击控件事件
• ThinkingAnalyticsEventTypeAppViewCrash，APP崩溃事件

您可以根据业务情况，传入需要收集事件的对应参数，多参数请使用|进行分割。

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


//设置完访客ID与公共属性后，再开启自动采集

[[ThinkingAnalyticsSDK sharedInstance] enableAutoTrack:ThinkingAnalyticsEventTypeAppStart |
ThinkingAnalyticsEventTypeAppInstall |
ThinkingAnalyticsEventTypeAppEnd |
ThinkingAnalyticsEventTypeAppViewScreen |
ThinkingAnalyticsEventTypeAppClick |
ThinkingAnalyticsEventTypeAppViewCrash];

3. 自动采集事件详解

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为直接开启。

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<TDScreenAutoTracker>来设置属性以及页面的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<TDUIViewAutoTrackDelegate>来设置自定义属性：

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

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. 忽略自动采集事件

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

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

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

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

// 多APPID实例时对单个APPID实例设置，忽略某个页面的自动采集事件
[[ThinkingAnalyticsSDK sharedInstanceWithAppid:APP_ID] ignoreAutoTrackViewControllers:array];

// 单APPID实例时可调用
// [[ThinkingAnalyticsSDK sharedInstance] ignoreAutoTrackViewControllers:array];

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

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

// 多APPID实例时对单个APPID实例设置，忽略某个类型的所有控件
[[ThinkingAnalyticsSDK sharedInstanceWithAppid:APP_ID] ignoreViewType:[IgnoredClass class]];

// 单APPID实例时可调用
// [[ThinkingAnalyticsSDK sharedInstance] ignoreViewType:[IgnoredClass class]];

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

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

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

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

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

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

5. 自动采集事件的预置属性

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

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

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

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

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

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