跳到主要内容

预置属性

最近更新 2026/10/03

一、 所有事件带有的预置属性​

以下预置属性，是 Android SDK 中所有事件（包括自动采集事件）都会带有的预置属性

属性名中文名属性类型采集时机说明

#ip

IP 地址

文本

服务端采集

用户的 IP 地址，AE 将以此获取用户的地理位置信息
#country国家文本服务端采集用户所在国家，根据 IP 地址生成

#country_code

国家代码文本

服务端采集

用户所在国家的国家代码(ISO 3166-1 alpha-2，即两位大写英文字母)，根据 IP 地址生成
#province省份文本服务端采集用户所在省份，根据 IP 地址生成
#city城市文本服务端采集用户所在城市，根据 IP 地址生成
#os_version操作系统版本文本初始化时采集一次iOS 11.2.2、Android 8.0.0 等

#manufacturer

设备制造商文本初始化时采集一次用户设备的制造商，如 Apple，vivo 等
#os操作系统文本初始化时采集一次如 Android、iOS 等
#device_id设备 ID文本初始化时采集一次用户的设备 ID，iOS 取用户的 IDFV 或 UUID，Android 取 androidID
#screen_height屏幕高度数值初始化时采集一次用户设备的屏幕高度，如 1920 等
#screen_width屏幕宽度数值初始化时采集一次用户设备的屏幕宽度，如 1080 等
#device_model设备型号文本初始化时采集一次用户设备的型号，如 iPhone 8 等
#device_type设备类型文本初始化时采集一次设备类型，如 "Tablet"、"Phone"
#app_versionAPP 版本文本初始化时采集一次您的 APP 的版本
#bundle_id应用唯一标识文本初始化时采集一次应用包名或进程名

#lib

SDK 类型文本

初始化时采集一次

您接入 SDK 的类型，如 Android，iOS 等
#lib_versionSDK 版本文本初始化时采集一次您接入 SDK 的版本
#network_type网络状态文本初始化时采集一次，网络状态变化时采集上传事件时的网络状态，如 WIFI、3G、4G 等

#carrier

网络运营商文本

初始化时采集一次

用户设备的网络运营商，如中国移动，中国电信等

#zone_offset

时区偏移

数值

事件发生时采集

数据时间相对 UTC 时间的偏移小时数
#install_time程序安装时间时间初始化时采集一次用户安装应用的时间，值来源于系统
#simulator是/否为模拟器布尔初始化时采集一次设备是否是模拟器 true/false

#ram

设备运行内存状态

文本

事件发生时采集

用户设备的当前剩余内存和总内存，单位GB，如 1.4/2.4（3.2.0及之后的版本默认不采集）

#disk

设备存储空间状态文本事件发生时采集

用户设备的当前剩余存储空间和总存储空间，

单位GB，如 30/200（3.2.0及之后的版本默认不采集）

#fps

设备帧率

数值

事件发生时采集

用户设备的当前图像每秒传输帧率，如 60（3.2.0及之后的版本默认不采集）

#system_language

系统语言文本初始化时采集一次用户设备的系统语言(ISO 639-1，即两位小写英文字母)，如 zh, en 等

二、自动采集事件的预置属性​

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

  • APP 启动事件（ta_app_start）的预置属性
属性名中文名属性类型说明

#resume_from_background

是否从后台唤醒

布尔表示 APP 是被开启还是从后台唤醒，取值为 true 表示从后台唤醒，false 为直接开启
#start_reason

应用启动来源

文本内容为JSON字符串；应用使用url或者intent方式打开APP时，自动记录url内容以及intent中的data数据，样例参考:{url:"thinkingdata://","data":{}}

#background_duration

后台停留时长

数值

记录两次start事件发生区间内，应用处于后台的时长，

单位:秒

  • APP 关闭事件（ta_app_end）的预置属性
属性名中文名属性类型说明
#duration事件时长

数值

表示该次 APP 访问（自启动至结束）的时长，单位是秒
  • APP 浏览页面事件（ta_app_view）的预置属性
属性名中文名属性类型说明
#title页面标题文本为控件所属Activity标题，取值为title属性的值
#screen_name页面名称文本为控件所属Activity的包名.类名
#url页面地址文本当前页面的地址，需要调用getScreenUrl进行 url 的设置
#referrer前向地址文本跳转前页面的地址，跳转前页面需要调用getScreenUrl进行 url 的设置
  • APP 控件点击事件（ta_app_click）的预置属性
属性名中文名属性类型说明
#title页面标题文本控件所属Activity的标题，取值为Activity的title属性的值
#screen_name页面名称文本控件所属Activity的包名.类名
#element_id元素 ID文本控件的 ID，默认使用android:id，可调用setViewID进行设置
#element_type元素类型文本控件的类型
#element_selector元素选择器文本控件的viewPath的拼接
#element_position元素位置文本控件的位置信息，当控件存在position属性时才会上传
#element_content元素内容文本控件上的内容
  • APP 崩溃事件（ta_app_crash）的预置属性
属性名中文名属性类型说明
#app_crashed_reason异常信息文本字符型，记录崩溃时的堆栈轨迹

三、其他预置属性​

除了上述提到预置属性，还有部分预置属性需要调用对应接口才会被记录：

属性名中文名属性类型说明

#duration

事件时长

数值

需要调用计时功能timeEvent，记录事件发生时长，单位是秒

#background_duration

后台停留时长

数值需要调用计时功能timeEvent，记录事件发生区间内，应用处于后台的时长，单位是秒

四、获取预置属性​

v2.7.0 及以后的版本可以调用 getPresetProperties() 方法获取预置属性。

服务端埋点需要 App 端的一些预置属性时，可以通过此方法获取 App 端的预置属性，再传给服务端。

   //获取属性对象
   TDPresetProperties presetProperties = TDAnalytics.getPresetProperties();

   //生成事件预置属性
   JSONObject properties = presetProperties.toEventPresetProperties();
   /*
   {
        "#carrier": "T-Mobile",
        "#os": "Android",
        "#device_id": "dd4a508df0dbff08",
        "#screen_height": 2560,
        "#bundle_id": "cn.thinkingdata.android.demo",
        "#device_model": "sdk_gphone64_arm64",
        "#screen_width": 1440,
        "#system_language": "en",
        "#install_time": "2022-08-19 17:31:52.398",
        "#simulator": true,
        "#manufacturer": "Google",
        "#os_version": "12",
        "#app_version": "1.0",
        "#network_type": "3G",
        "#zone_offset": 8,
        "#ram": "0.8\/1.9",
        "#disk": "0.1\/0.8",
        "#fps": 60
    }
   */

    //获取某个预置属性
    String bundle_id = presetProperties.bundleId;//包名
    String os =  presetProperties.os;//os类型，如Android
    String system_language = presetProperties.systemLanguage;//手机系统语言类型
    int screen_width = presetProperties.screenWidth;//屏幕宽度
    int screen_height = presetProperties.screenHeight;//屏幕高度
    String device_model = presetProperties.deviceModel;//设备型号
    String device_id = presetProperties.deviceId;//设备唯一标识
    String carrier = presetProperties.carrier;//手机SIM卡运营商信息，双卡双待时，取主卡的运营商信息
    String manufacture = presetProperties.manufacture;//手机制造商 如HuaWei
    String network_type = presetProperties.networkType;//网络类型
    String os_version = presetProperties.osVersion;//系统版本号
    String app_version = presetProperties.appVersion;//app版本号
    double zone_offset = presetProperties.zoneOffset;//时区偏移值
    String ram = presetProperties.ram;//内存使用情况
    String disk = presetProperties.disk;//硬盘使用情况
    int fps = presetProperties.fps;//fps
    String installTime = presetProperties.installTime;//应用安装时间
    boolean isSimulator = presetProperties.isSimulator;//设备是否为模拟器

IP，国家城市信息由服务端解析生成，客户端不提供接口获取这些属性

五、关闭预置属性采集​

在某些场景下，出于合规、实际业务需求等的考量，您也许期望禁止某些预置属性的采集。您可以在工程目录的res/values目录下新增ta_public_config.xml文件，用于配置需要禁用采集的属性数组。

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <!-- ThinkingAnalytics DisablePresetProperties start -->
    <string-array name="TDDisPresetProperties">
<!--        <item>#disk</item>-->
<!--        <item>#fps</item>-->
<!--        <item>#ram</item>-->
<!--        <item>#app_version</item>-->
<!--        <item>#os_version</item>-->
<!--        <item>#manufacturer</item>-->
<!--        <item>#device_model</item>-->
<!--        <item>#screen_height</item>-->
<!--        <item>#screen_width</item>-->
<!--        <item>#carrier</item>-->
<!--        <item>#device_id</item>-->
<!--        <item>#system_language</item>-->
<!--        <item>#lib</item>-->
<!--        <item>#lib_version</item>-->
<!--        <item>#os</item>-->
<!--        <item>#bundle_id</item>-->
<!--        <item>#install_time</item>-->
<!--        <item>#start_reason</item>-->
<!--        <item>#simulator</item>-->
<!--        <item>#network_type</item>-->
<!--        <item>#zone_offset</item>-->
<!--        <item>#start_reason</item>-->
<!--        <item>#resume_from_background</item>-->
<!--        <item>#title</item>-->
<!--        <item>#screen_name</item>-->
<!--        <item>#url</item>-->
<!--        <item>#referrer</item>-->
<!--        <item>#element_type</item>-->
<!--        <item>#element_id</item>-->
<!--        <item>#element_position</item>-->
<!--        <item>#element_content</item>-->
<!--        <item>#element_selector</item>-->
<!--        <item>#app_crashed_reason</item>-->
<!--        <item>#background_duration</item>-->
<!--        <item>#duration</item>-->
    </string-array>
    <!-- ThinkingAnalytics DisablePresetProperties end -->
</resources>

如果您屏蔽设备ID的情况下，需要使用首次事件，请务必填写first_check_id属性

关于Android ID属性，我们可以支持代码级别的完全隔离，即隔离后，应用内不再包含获取该属性的相关代码。详情请见自动采集插件配置章节

这篇文档对你有帮助吗？
本页内容