ae-tracking 0.1.0

package/wiki/te-docs/raw//346/216/245/345/205/245/346/214/207/345/215/227//345/256/242/346/210/267/347/253/257-sdk/ios//350/277/233/351/230/266/346/214/207/345/215/227//350/207/252/345/212/250/351/207/207/351/233/206.md

@@ -0,0 +1,479 @@
+---
+code: ios_sdk_autotrack
+name: "自动采集"
+wikiToken: FGw9wzSwhizYXMk2yAscUxiJn1d
+parentWikiToken: T7Ocw5qr7is1Z5k0P6VcZVSKnDd
+updateTime: 1762842919000
+sourceUrl: https://docs-v2.thinkingdata.cn/?version=v5.0&lan=zh-CN&code=ios_sdk_autotrack
+---
+# 自动采集
+
+### 一、自动采集介绍
+
+AE 系统提供自动化收集数据的接口，您可根据业务需求自行选择需要自动收集的数据。
+
+现在支持的自动化收集数据有：
+
+1. APP 安装，记录 APP 被安装
+1. APP 启动，包括打开 APP和从后台唤醒
+1. APP 关闭，包括关闭 APP和进入后台，同时收集启动的时长
+1. 用户在 APP 中浏览页面（原生页面）
+1. 用户在 APP 中点击控件
+1. APP 发生崩溃时记录崩溃信息
+接下来将会详细介绍每种数据的采集方法
+
+### 二、开启自动采集
+
+您可以调用`enableAutoTrack:`，打开自动采集功能：
+
+```
+[TDAnalytics enableAutoTrack:
+TDAutoTrackEventTypeAppStart |//APP启动事件
+TDAutoTrackEventTypeAppInstall |//APP安装事件
+TDAutoTrackEventTypeAppEnd |//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。正常的 APP 启动流程会触发此事件。
+- 预置属性：`#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`<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.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** @{};
+}];
+```
+
+<!-- unsupported block: 34 -->
+
+请不要在此回调中做耗时操作，否则会影响数据正常入库