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//351/242/204/347/275/256/345/261/236/346/200/247.md

@@ -0,0 +1,587 @@
+---
+code: ios_sdk_preset_properties
+name: "预置属性"
+wikiToken: V6zgwA0APibMk7kC3ufcrN0DnAc
+parentWikiToken: T7Ocw5qr7is1Z5k0P6VcZVSKnDd
+updateTime: 1772103046000
+sourceUrl: https://docs-v2.thinkingdata.cn/?version=v5.0&lan=zh-CN&code=ios_sdk_preset_properties
+---
+# 预置属性
+
+### 一、 所有事件带有的预置属性
+
+以下预置属性，是 iOS SDK 中所有事件（包括自动采集事件）都会带有的预置属性
+
+**属性名**
+
+**中文名**
+
+**属性类型**
+
+**采集时机**
+
+**说明**
+
+#ip
+
+IP 地址
+
+文本
+
+服务端采集
+
+用户的 IP 地址，AE 将以此获取用户的地理位置信息
+
+#country
+
+国家
+
+文本
+
+服务端采集
+
+用户所在国家，根据 IP 地址生成
+
+#country_code
+
+国家代码
+
+文本
+
+服务端采集
+
+用户所在国家的国家代码(ISO 3166-1 alpha-2，即两位大写英文字母)，根据 IP 地址生成
+
+#province
+
+省份
+
+文本
+
+服务端采集
+
+用户所在省份，根据 IP 地址生成
+
+#city
+
+城市
+
+文本
+
+服务端采集
+
+用户所在城市，根据 IP 地址生成
+
+#os_version
+
+操作系统版本
+
+文本
+
+初始化时采集一次
+
+显示操作系统版本号：15.6.1
+
+#manufacturer
+
+设备制造商
+
+文本
+
+初始化时采集一次
+
+用户设备的制造商，如 Apple
+
+#os
+
+操作系统
+
+文本
+
+初始化时采集一次
+
+如 iOS 等
+
+#device_id
+
+设备 ID
+
+文本
+
+初始化时采集一次
+
+用户的设备 ID，iOS 取用户的 IDFV 或 UUID
+
+#device_type
+
+设备类型
+
+文本
+
+初始化时采集一次
+
+设备类型，如 iPhone，iPad
+
+#screen_height
+
+屏幕高度
+
+数值
+
+初始化时采集一次
+
+用户设备的屏幕高度，如 667 等
+
+#screen_width
+
+屏幕宽度
+
+数值
+
+初始化时采集一次
+
+用户设备的屏幕高度，如 375 等
+
+#device_model
+
+设备型号
+
+文本
+
+初始化时采集一次
+
+用户设备的型号，如 iPhone12,8 等
+
+#app_version
+
+APP 版本
+
+文本
+
+初始化时采集一次
+
+您的 APP 的版本
+
+#bundle_id
+
+应用唯一标识
+
+文本
+
+初始化时采集一次
+
+应用包名
+
+#lib
+
+SDK 类型
+
+文本
+
+事件发生时采集
+
+您接入 SDK 的类型，如 Android，iOS 等
+
+#lib_version
+
+SDK 版本
+
+文本
+
+事件发生时采集
+
+您接入 SDK 的版本
+
+#network_type
+
+网络状态
+
+文本
+
+初始化时采集一次，网络状态变化时采集
+
+上传事件时的网络状态，如 WIFI、3G、4G 等
+
+#carrier
+
+网络运营商
+
+文本
+
+初始化时采集一次
+
+用户设备的网络运营商，如中国移动，中国电信等。在 iOS16.4 以后的系统版本，该字段不会被采集
+
+#zone_offset
+
+时区偏移
+
+数值
+
+事件发生时采集
+
+数据时间相对 UTC 时间的偏移小时数
+
+#install_time
+
+程序安装时间
+
+时间
+
+初始化时采集一次
+
+用户安装应用的时间，值来源于系统
+
+#simulator
+
+是/否为模拟器
+
+数值
+
+初始化时采集一次
+
+设备是否是模拟器 true/false
+
+#ram
+
+设备运行内存状态
+
+文本
+
+事件发生时采集
+
+用户设备的当前剩余内存和总内存，单位GB，如 1.4/2.4
+
+#disk
+
+设备存储空间状态
+
+文本
+
+事件发生时采集
+
+用户设备的当前剩余存储空间和总存储空间，单位GB，如 30/200
+
+#fps
+
+设备FPS
+
+数值
+
+事件发生时采集
+
+用户设备的当前图像每秒传输帧率，如 60。(v3.2.0 版本后的 SDK 默认不采集该字段)
+
+#system_language
+
+系统语言
+
+文本
+
+事件发生时采集
+
+用户设备的系统语言(ISO 639-1，即两位小写英文字母)，如 zh, en 等
+
+#relaunched_in_background
+
+应用是否在后台
+
+数值
+
+事件发生时采集
+
+当 APP 在后台启动时，采集到的事件中此属性为 YES。
+
+当 APP 正常启动时，采集到的事件中不包含此属性。
+
+### 二、 自动采集事件的预置属性
+
+以下预置属性，是各个自动采集事件中所特有的预置属性
+
+- APP 启动事件（ta_app_start）的预置属性
+**属性名**
+
+**中文名**
+
+**属性类型**
+
+**说明**
+
+#resume_from_background
+
+是否从后台唤醒
+
+布尔
+
+表示 APP 是被开启还是从后台唤醒，取值为 true 表示从后台唤醒，false 为直接开启
+
+#start_reason
+
+应用启动来源
+
+文本
+
+表示 APP 启动原因，内容为JSON字符串。目前支持收集deeplink、推送、3dtouch启动原因。数据样例参考{url:"thinkingdata://","data":{}}
+
+#backgroud_duration
+
+后台停留时长
+
+数值
+
+记录两次start事件发生区间内，应用在后台的停留时长，单位是秒
+
+- 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
+
+异常信息
+
+文本
+
+字符型，记录崩溃时的堆栈轨迹
+
+### 三、 其他预置属性
+
+除了上述提到预置属性，还有部分预置属性需要调用对应接口才会被记录：
+
+**属性名**
+
+**中文名**
+
+属性类型
+
+**说明**
+
+#duration
+
+事件时长
+
+数值
+
+需要调用计时功能接口`timeEvent`，记录事件发生时长，单位是秒
+
+#background_duration
+
+后台停留时长
+
+数值
+
+需要调用计时功能接口`timeEvent`，记录事件发生区间内，应用在后台的停留时长，单位是秒
+
+### 四、 获取预置属性
+
+v2.7.0 及以后的版本可以调用 `getPresetProperties` 方法获取预置属性。
+
+服务端埋点需要 App 端的一些预置属性时，可以通过此方法获取 App 端的预置属性，再传给服务端。
+
+:::: el-tabs
+
+::: el-tab-pane label=Objective-C
+
+```
+//获取属性对象
+TDPresetProperties *presetProperties = [TDAnalytics getPresetProperties];
+
+//生成事件预置属性
+NSDictionary *properties = [presetProperties toEventPresetProperties];
+/*
+   {
+        "#carrier": "中国电信",
+        "#os": "iOS",
+        "#device_id": "A8B1C00B-A6AC-4856-8538-0FBC642C1BAD",
+        "#screen_height": 2264,
+        "#bundle_id": "com.sw.thinkingdatademo",
+        "#manufacturer": "Apple",
+        "#device_model": "iPhone7",
+        "#screen_width": 1080,
+        "#system_language": "zh",
+        "#os_version": "10",
+        "#network_type": "WIFI",
+        "#zone_offset": 8,
+    }
+*/
+
+//获取某个预置属性
+NSString *bundle_id = presetProperties.bundle_id;//包名
+NSString *os = presetProperties.os;//os类型，如iOS
+NSString *system_language = presetProperties.system_language;//手机系统语言类型
+NSNumber *screen_width = presetProperties.screen_width;//屏幕宽度
+NSNumber *screen_height = presetProperties.screen_height;//屏幕高度
+NSString *device_model = presetProperties.device_model;//设备型号
+NSString *device_id = presetProperties.device_id;//设备唯一标识
+NSString *carrier = presetProperties.carrier;//手机SIM卡运营商信息，双卡双待时，取主卡的运营商信息
+NSString *manufacture = presetProperties.manufacturer;//手机制造商 如Apple
+NSString *network_type = presetProperties.network_type;//网络类型
+NSString *os_version = presetProperties.os_version;//系统版本号
+NSNumber *zone_offset = presetProperties.zone_offset;//时区偏移
+```
+
+:::
+
+::: el-tab-pane label=Swift
+
+```
+let presetProperties = TDAnalytics.getPresetProperties();
+
+//生成事件预置属性
+let properties = presetProperties.toEventPresetProperties();
+
+//获取某个预置属性
+let bundle_id = presetProperties.bundle_id;//包名
+let os = presetProperties.os;//os类型，如iOS
+let system_language = presetProperties.system_language;//手机系统语言类型
+let screen_width = presetProperties.screen_width;//屏幕宽度
+let screen_height = presetProperties.screen_height;//屏幕高度
+let device_model = presetProperties.device_model;//设备型号
+let device_id = presetProperties.device_id;//设备唯一标识
+let carrier = presetProperties.carrier;//手机SIM卡运营商信息，双卡双待时，取主卡的运营商信息
+let manufacture = presetProperties.manufacturer;//手机制造商 如Apple
+let network_type = presetProperties.network_type;//网络类型
+let os_version = presetProperties.os_version;//系统版本号
+let zone_offset = presetProperties.zone_offset;//时区偏移值
+```
+
+:::
+
+::::
+
+<!-- unsupported block: 34 -->
+
+IP，国家城市信息由服务端解析生成，客户端不提供接口获取这些属性
+
+### 五、 关闭预置属性采集
+
+在某些场景下，出于合规、实际业务需求等的考量，您也许期望禁止某些预置属性的采集。您可以在工程的info.plist文件中添加**TDDisPresetProperties**字段，类型是Array，添加的字段对应的预置属性将不会上传。如屏蔽"#fps", @"#ram", @"#disk", @"#start_reason", @"#simulator"等预置属性，配置如下图：
+
+<!-- unsupported block: 34 -->
+
+如果您屏蔽设备ID的情况下，需要使用首次事件，请务必填写first_check_id属性