---
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属性
