# iOS SDK 自动采集指南

# 一、自动采集介绍

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

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

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

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

# 二、开启自动采集

您可以调用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 崩溃事件

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

如需设置公共事件属性或设置自定义访客 ID,请务必确保在开启自动采集之前调用 setSuperProperties:或 identify:


-(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.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来设置属性以及页面的 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"];

// 多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

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

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

  • APP 启动事件(ta_app_start)的预置属性
属性名
中文名
说明
#resume_from_background
是否从后台唤醒
表示 APP 是被开启还是从后台唤醒,取值为 true 表示从后台唤醒,false 为直接开启
#start_reason
启动原因
表示 APP 启动原因,value为字符串类型。目前支持收集deeplink、推送、3dtouch启动原因。
  • 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:,打开自动采集功能,同时设置自定义属性

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

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

[[ThinkingAnalyticsSDK sharedInstance] setAutoTrackProperties:ThinkingAnalyticsEventTypeAppEnd properties: @{@"auto_key2": @"auto_value2"}];

# 七、自动采集事件回调

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

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