Title: 预置事件和预置属性
Locale: zh
URL: https://sensorswave.com/docs/data-integration/preset-events-and-properties/
Description: Sensors Wave 预置的事件和属性说明
Sensors Wave 在 SDK 中内置了一系列预定义事件和预定义属性,用于自动采集用户的基础行为数据和环境信息。合理使用预置事件和预置属性,可以帮助您快速搭建数据采集体系,减少手动埋点的工作量,同时确保数据采集的标准化和一致性。

## 为什么要了解预置事件和预置属性?

了解预置事件和预置属性可以帮助您:

- **减少开发工作量**:SDK 自动采集基础行为数据,无需手动埋点
- **保证数据标准化**:使用统一的事件和属性命名,确保数据的一致性
- **快速启动分析**:立即获得基础的用户行为数据,支持基本的分析需求
- **避免命名冲突**:了解系统保留的属性名称,避免自定义属性与预置属性冲突
- **提升数据质量**:SDK 自动处理数据格式和异常情况,确保数据的准确性

## 核心概念

### 什么是预置事件?

预置事件是 SDK 自动采集的标准化事件,用于记录用户的基础行为,如页面浏览、应用启动、元素点击等。预置事件采用 `$` 开头的命名方式,与用户自定义事件区分。

**预置事件的特点**:

- SDK 自动采集,无需手动调用
- 统一的命名规范,采用 `$` 前缀
- 跨平台的语义一致性
- 包含丰富的预置属性信息

### 什么是预置属性?

预置属性是 SDK 自动采集的标准化属性,分为系统保留属性和业务预定义属性两类:

- **系统保留属性**:系统自动生成的核心字段,如 `time`、`event_id`、`ssid` 等,用于数据的存储、索引和查询
- **业务预定义属性**:SDK 自动采集的业务相关属性,如设备信息、浏览器信息、地理位置等,采用 `$` 前缀命名

**预置属性的特点**:

- SDK 自动采集,确保数据的完整性
- 统一的命名规范,采用 `$` 前缀(业务预定义属性)
- 标准化的数据格式和类型
- 为常见的分析场景提供基础维度

## 预置事件列表

Sensors Wave 支持的预置事件根据不同的上报端进行划分,每个平台都有对应的基础事件用于记录用户行为。

### Web 端预置事件

Web SDK 自动采集以下预置事件:

| 事件名称 | 显示名称 | 描述 | 触发时机 |
|---------|---------|------|---------|
| `$PageView` | Web 页面浏览 | 用户浏览页面时触发 | 页面加载完成或路由切换 |
| `$PageLoad` | Web 页面加载 | 页面加载完成时触发 | 页面 onload 事件触发 |
| `$PageLeave` | Web 页面离开 | 用户离开页面时触发 | 页面 unload 或 beforeunload 事件触发 |
| `$WebClick` | Web 页面点击 | 用户点击页面元素时触发 | 点击可交互元素(链接、按钮等) |

**使用场景**:

- **`$PageView`**:用于分析用户的页面浏览路径、页面停留时长、页面热度等
- **`$PageLoad`**:用于分析页面加载性能、首屏时间等
- **`$PageLeave`**:用于分析用户的离开行为、页面跳出率等
- **`$WebClick`**:用于分析用户的点击行为、热点区域等

### App 端预置事件

App SDK(Android 和 iOS)自动采集以下预置事件:

| 事件名称 | 显示名称 | 描述 | 触发时机 |
|---------|---------|------|---------|
| `$AppStart` | App 启动 | 应用启动时触发 | 应用进入前台 |
| `$AppEnd` | App 退出 | 应用退出时触发 | 应用进入后台或完全退出 |
| `$AppPageView` | App 页面浏览 | 用户浏览应用页面时触发 | 页面(Activity/ViewController)进入 |
| `$AppPageLeave` | App 页面离开 | 用户离开应用页面时触发 | 页面(Activity/ViewController)离开 |
| `$AppClick` | App 元素点击 | 用户点击应用元素时触发 | 点击按钮、视图等可交互元素 |
| `$AppInstall` | App 安装激活 | 应用首次安装激活时触发 | 首次启动应用 |

**使用场景**:

- **`$AppStart` / `$AppEnd`**:用于分析应用启动次数、使用时长、会话分析等
- **`$AppPageView` / `$AppPageLeave`**:用于分析页面浏览路径、页面停留时长、页面热度等
- **`$AppClick`**:用于分析用户的交互行为、功能使用情况等
- **`$AppInstall`**:用于分析新用户激活、渠道效果等

### 微信小程序预置事件

小程序 SDK 自动采集以下预置事件:

| 事件名称 | 显示名称 | 描述 | 触发时机 |
|---------|---------|------|---------|
| `$MPLaunch` | 小程序启动 | 小程序启动时触发 | 小程序初始化完成 |
| `$MPShow` | 小程序显示 | 小程序显示时触发 | 小程序进入前台 |
| `$MPHide` | 小程序进入后台 | 小程序进入后台时触发 | 小程序切换到后台 |
| `$MPPageView` | 小程序页面浏览 | 用户浏览小程序页面时触发 | 页面加载完成 |
| `$MPPageLeave` | 小程序页面离开 | 用户离开小程序页面时触发 | 页面卸载或切换 |
| `$MPClick` | 小程序元素点击 | 用户点击小程序元素时触发 | 点击可交互元素 |
| `$MPShare` | 小程序分享 | 用户分享小程序时触发 | 调用分享功能 |

**使用场景**:

- **`$MPLaunch`**:用于分析小程序启动次数、启动来源场景、用户激活等
- **`$MPShow` / `$MPHide`**:用于分析小程序使用时长、会话分析、用户粘性等
- **`$MPPageView` / `$MPPageLeave`**:用于分析页面浏览路径、页面停留时长、页面热度等
- **`$MPClick`**:用于分析用户的交互行为、功能使用情况、点击热力图等
- **`$MPShare`**:用于分析分享行为、传播效果、裂变分析等

### 全平台预置事件

以下事件在所有平台都支持:

| 事件名称 | 显示名称 | 描述 | 触发时机 |
|---------|---------|------|---------|
| `$ExpImpress` | Experiment 曝光 | 实验曝光时触发 | 用户命中实验策略 |
| `$FeatureImpress` | Feature Gate 曝光 | 功能开关曝光时触发 | 用户命中功能开关策略 |

**使用场景**:

- **`$ExpImpress`**:用于分析实验的曝光情况、实验覆盖率等
- **`$FeatureImpress`**:用于分析功能开关的曝光情况、功能覆盖率等

## 预置属性列表

预置属性分为系统保留属性和业务预定义属性两类。系统保留属性用于数据存储和查询,业务预定义属性用于数据分析。

### 系统保留属性

系统保留属性是 Sensors Wave 自动生成的核心字段,用于数据的存储、索引、查询和用户身份识别。这些属性不可被覆盖或修改。

| 属性名 | 属性显示名 | 描述 | 数据类型 | 采集来源 |
|-------|-----------|------|---------|---------|
| `time` | 事件发生时间 | 事件发生的时间戳(客户端时间) | DateTime | JavaScript、Android、iOS |
| `event_id` | 事件 ID | 事件名称的哈希值,用于索引和查询加速 | Int | - |
| `trace_id` | 去重 ID | 客户端生成的唯一 ID,用于事件去重,未上报时自动填充 UUID | String | JavaScript、Android、iOS |
| `anon_id` | 匿名 ID | 标识设备或浏览器的唯一 ID,通常取设备 ID 或 UUID | String | JavaScript、Android、iOS |
| `user_id` | 登录 ID | 用户的登录 ID,标识已登录用户的业务账号 | String | JavaScript、Android、iOS |
| `event` | 事件名称 | 上报的事件名称 | String | JavaScript、Android、iOS |
| `ssid` | 服务端用户唯一 ID | 服务端生成的用户唯一 ID,基于 distinct_id 哈希计算,用于用户关联和修正 | Int64 | - |
| `received_at` | 事件接收时间 | 服务端接收到数据的时间戳 | DateTime | - |
| `created_at` | 事件入库时间 | 数据写入数据库的时间戳 | DateTime | - |
| `updated_at` | 事件更新时间 | 数据最后更新时间,仅在用户关联修正等场景下存在更新 | DateTime | - |

> **提示**:系统保留属性不需要手动上报,由 SDK 或服务端自动生成和管理。

### SDK 相关属性

| 属性名 | 属性显示名 | 描述 | 示例值 | 采集来源 |
|-------|-----------|------|-------|---------|
| `$lib` | 埋点 lib 库 | 使用的 SDK 类型 | `"webjs"`, `"mpjs"`, `"go"`, `"java"`, `"android"`, `"ios"` | JavaScript、Android、iOS |
| `$lib_version` | lib 库版本 | SDK 的版本号 | `"3.0.2"` | JavaScript、Android、iOS |

### 端通用属性

适用于所有客户端(Web、App):

| 属性名 | 属性显示名 | 描述 | 示例值 | 采集来源 |
|-------|-----------|------|-------|---------|
| `$title` | 页面标题 | 当前页面的标题 | `"Sensors Wave"` | JavaScript、Android、iOS |
| `$url` | 当前浏览 URL | 当前页面的完整 URL | `"https://example.com/page"` | JavaScript、Android、iOS |
| `$timezone_offset` | 时区偏移量 | App 或系统的时区偏移量(单位:秒) | `28800`(东八区,UTC+8) | JavaScript、Android、iOS |
| `$referrer` | http 来源地址 | HTTP Referrer,用户来源页面的完整 URL | `"https://www.baidu.com"` | JavaScript、Android、iOS |
| `$language` | 语言 | 用户的系统语言设置 | `"en"`, `"zh-CN"` | JavaScript、Android、iOS |

### 设备相关属性

适用于所有客户端(Web、App):

| 属性名 | 属性显示名 | 描述 | 示例值 | 采集来源 |
|-------|-----------|------|-------|---------|
| `$model` | 设备型号 | 设备的型号信息 | `"xiaomi 15"` | JavaScript、Android、iOS |
| `$os` | 操作系统 | 设备的操作系统 | `"iOS"`, `"Android"`, `"Windows"` | JavaScript、Android、iOS |
| `$os_version` | 操作系统版本 | 操作系统的版本号 | `"10.15.7"`, `"14.0"` | JavaScript、Android、iOS |
| `$screen_height` | 屏幕高度 | 设备屏幕的高度(像素) | `1080` | JavaScript、Android、iOS |
| `$screen_width` | 屏幕宽度 | 设备屏幕的宽度(像素) | `1920` | JavaScript、Android、iOS |

### 浏览器相关属性

仅适用于 Web 端:

| 属性名 | 属性显示名 | 描述 | 示例值 | 采集来源 |
|-------|-----------|------|-------|---------|
| `$browser` | 浏览器 | 浏览器类型 | `"Chrome"`, `"Safari"`, `"Firefox"` | JavaScript |
| `$browser_version` | 浏览器版本 | 浏览器的版本号 | `"125"`, `"16.5"` | JavaScript |
| `$pathname` | 当前网页路径 | 当前页面的路径部分 | `"/page"`, `"/products/123"` | JavaScript |
| `$host` | 主机地址 | 当前页面的主机地址 | `"example.com"` | JavaScript |
| `$viewport_height` | 视图高度 | 浏览器视口的高度(像素) | `950` | JavaScript |
| `$viewport_width` | 视图宽度 | 浏览器视口的宽度(像素) | `1903` | JavaScript |
| `$search_engine` | 搜索引擎 | 用户来源的搜索引擎 | `"google"`, `"baidu"` | JavaScript |
| `$referrer_host` | http 来源地址域名 | HTTP Referrer 的域名部分 | `"www.baidu.com"` | JavaScript |

### App 相关属性

仅适用于 App 端(Android 和 iOS):
| 属性名 | 属性显示名 | 描述 | 示例值 |
|-------|-----------|------|-------|
| `$lib` | 埋点 lib 库 | 使用的 SDK 类型 | `"android"`, `"ios"` |
| `$lib_version` | lib 库版本 | SDK 的版本号 | `"3.0.2"` |
| `$device_id` | 设备 ID | 设备的唯一标识符 | 设备唯一标识 |
| `$network_type` | 网络类型 | 当前网络连接类型 | `"wifi"`, `"4G"`, `"5G"` |
| `$manufacturer` | 设备制造商 | 设备的制造商 | `"Google"`, `"Apple"`, `"Samsung"` |
| `$app_version` | APP 的应用版本 | 应用的版本号 | `"1.0.0"`, `"2.5.3"` |
| `$app_id` | App 的唯一标识 | 应用的唯一标识符 | `"com.sol.analytics"` |
| `$app_name` | 应用的名称 | 应用的名称 | `"Sol"`, `"Sensors Wave"` |
| `$brand` | 设备品牌 | 设备的品牌 | `"xiaomi"`, `"huawei"`, `"apple"` |
| `$wifi` | 事件触发时是否为 wifi | 事件触发时是否使用 WiFi 网络 | `true`, `false` |
| `$timezone_offset` | 时区偏移量 | App 或系统的时区偏移量(单位:秒) | `28800`(东八区,UTC+8) |
| `$referrer_title` | 前一个页面标题 | 用户来源页面的标题 | `"首页"`, `"商品列表"` |
| `$region` | 地区 | 用户所在地区(国家或地区代码) | `"us"`, `"cn"` |
| `$language` | 语言 | 用户的系统语言设置 | `"en"`, `"zh-CN"` |

### 小程序相关属性

仅适用于小程序端:

| 属性名 | 属性显示名 | 描述 | 示例值 | 采集来源 |
|-------|-----------|------|-------|---------|
| `$brand` | 设备品牌 | 设备的品牌 | `"xiaomi"`, `"huawei"`, `"apple"` | 小程序 |
| `$manufacturer` | 设备制造商 | 设备的制造商 | `"Google"`, `"Apple"`, `"Samsung"` | 小程序 |
| `$network_type` | 网络类型 | 当前网络连接类型 | `"wifi"`, `"4G"`, `"5G"` | 小程序 |
| `$url_path` | 页面路径 | 小程序页面的路径 | `"pages/index"`, `"pages/detail"` | 小程序 |
| `$url_query` | 页面参数 | 小程序页面的查询参数 | `"id=123&source=home"` | 小程序 |

适用于所有平台,服务端根据客户端 IP 地址解析生成:

| 属性名 | 属性显示名 | 描述 | 示例值 | 采集来源 |
|-------|-----------|------|-------|---------|
| `$ip` | IP 地址 | 客户端的 IP 地址 | `"192.168.1.1"` | - |
| `$city` | 城市 | 根据 IP 解析的城市 | `"青岛"`, `"北京"` | - |
| `$province` | 省份 | 根据 IP 解析的省份 | `"山东"`, `"广东"` | - |
| `$country` | 国家 | 根据 IP 解析的国家 | `"中国"`, `"美国"` | - |

> **提示**:IP 解析属性由服务端根据客户端 IP 地址自动解析生成,无需在客户端上报。

### 广告相关属性(UTM 参数)

适用于 Web 和 App,用于追踪广告投放效果:

SDK 会自动解析 URL 中的 UTM 参数,并将其作为用户属性上报,用于记录用户的广告来源信息。UTM 参数会自动更新为最新一次访问的值。

**示例 URL**:

```
https://example.com/product?utm_source=newsletter&utm_medium=email&utm_campaign=product_launch&utm_term=new+product&utm_content=logolink
```

> **注意**: UTM 参数属于用户属性,存储在用户表中,记录用户最近一次访问的广告来源信息。

### 特定事件的专属属性

某些预置事件除了包含通用预置属性外,还包含该事件专属的预置属性。

#### $PageLoad 专属属性

| 属性名 | 属性显示名 | 描述 | 示例值 | 采集来源 |
|-------|-----------|------|-------|---------|
| `$event_duration` | 页面加载时长 | 页面加载完成所需的时间,单位:秒 | `1.5` | JavaScript |
| `$page_resource_size` | 页面资源大小 | 页面资源的大小,单位:kb | `1000` | JavaScript |

#### $PageLeave 专属属性

| 属性名 | 属性显示名 | 描述 | 示例值 | 采集来源 |
|-------|-----------|------|-------|---------|
| `$event_duration` | 页面浏览时长 | 用户在页面停留的时长,单位:秒 | `30` | JavaScript |

#### $WebClick 专属属性

| 属性名 | 属性显示名 | 描述 | 示例值 | 采集来源 |
|-------|-----------|------|-------|---------|
| `$element_type` | 元素类型 | 被点击元素的 HTML 标签类型 | `"button"`, `"a"`, `"input"` | JavaScript |
| `$element_name` | 元素名字 | 元素的 name 属性值 | `"button"`, `"submit"` | JavaScript |
| `$element_id` | 元素 ID | 元素的 id 属性值 | `"id"`, `"submit-btn"` | JavaScript |
| `$element_class_name` | 元素样式名 | 元素的 class 属性值 | `"class"`, `"btn-primary"` | JavaScript |
| `$element_target_url` | 元素链接地址 | 链接元素的 href 属性值 | `"https://example.com"` | JavaScript |
| `$element_content` | 元素内容 | 元素的文本内容 | 元素文案 | JavaScript |
| `$element_selector` | 元素选择器 | 元素的 CSS 选择器 | `"#id"`, `".class"` | JavaScript |
| `$element_path` | 元素路径 | 元素在 DOM 树中的路径 | `"body > .class"` | JavaScript |
| `$page_x` | 点击位置距网页左侧距离 | 点击位置距离网页左侧的距离(像素) | `100` | JavaScript |
| `$page_y` | 点击位置距网页顶部距离 | 点击位置距离网页顶部的距离(像素) | `200` | JavaScript |

#### $AppStart 和 $AppEnd 专属属性

| 属性名 | 属性显示名 | 描述 | 示例值 | 采集来源 |
|-------|-----------|------|-------|---------|
| `$screen_name` | 页面名称 | 当前页面的名称 | `"name"`, `"HomePage"` | Android、iOS |

**$AppEnd 额外属性**:

| 属性名 | 属性显示名 | 描述 | 示例值 | 采集来源 |
|-------|-----------|------|-------|---------|
| `$event_duration` | 事件时长 | 本次 App 启动到 App 退出的时长,单位:秒 | `180` | Android、iOS |

#### $AppPageView 和 $AppPageLeave 专属属性

| 属性名 | 属性显示名 | 描述 | 示例值 | 采集来源 |
|-------|-----------|------|-------|---------|
| `$screen_name` | 页面名称 | 当前页面的名称 | `"name"`, `"HomePage"` | Android、iOS |

#### $AppClick 专属属性

| 属性名 | 属性显示名 | 描述 | 示例值 | 采集来源 |
|-------|-----------|------|-------|---------|
| `$event_duration` | 事件时长 | 页面浏览的时长,单位:秒 | `30` | Android、iOS |
| `$screen_name` | 页面名称 | 当前页面的名称 | `"name"`, `"HomePage"` | Android、iOS |
| `$element_position` | 元素位置 | 元素在模块中的位置,从 0 开始 | `0`, `1`, `2` | Android、iOS |
| `$element_id` | 元素 ID | 元素的 ID 标识 | 元素 ID | Android、iOS |
| `$element_content` | 元素内容 | 元素的文本内容 | 元素文案 | Android、iOS |
| `$element_type` | 元素类型 | 控件的类型 | `"Button"`, `"TextView"` | Android、iOS |
| `$element_selector` | 元素选择器 | 记录按钮在 APP 中的位置 | 选择器路径 | Android、iOS |
| `$element_path` | 元素路径 | 元素在页面中的路径 | 路径信息 | Android、iOS |

#### $MPLaunch 和 $MPShow 专属属性

| 属性名 | 属性显示名 | 描述 | 示例值 | 采集来源 |
|-------|-----------|------|-------|---------|
| `$scene` | 启动场景 | 小程序的启动场景值 | `1000`, `1011`, `1047` | 小程序 |

#### $MPHide 专属属性

| 属性名 | 属性显示名 | 描述 | 示例值 | 采集来源 |
|-------|-----------|------|-------|---------|
| `$event_duration` | 事件时长 | 小程序在前台的停留时长,单位:秒 | `180` | 小程序 |

#### $MPPageLeave 专属属性

| 属性名 | 属性显示名 | 描述 | 示例值 | 采集来源 |
|-------|-----------|------|-------|---------|
| `$event_duration` | 事件时长 | 页面浏览时长,单位:秒 | `30` | 小程序 |

#### $MPClick 专属属性

| 属性名 | 属性显示名 | 描述 | 示例值 | 采集来源 |
|-------|-----------|------|-------|---------|
| `$element_type` | 元素类型 | 被点击元素的类型 | `"button"` | 小程序 |
| `$element_name` | 元素名字 | 元素的 name 属性值 | `"submit-btn"`, `"nav-bar"` | 小程序 |
| `$element_id` | 元素 ID | 元素的 id 属性值 | `"button-1"`, `"page-header"` | 小程序 |
| `$element_content` | 元素内容 | 元素的文本内容 | `"提交"`, `"确认"` | 小程序 |
| `$element_selector` | 元素选择器 | 元素的选择器路径 | `"#id"`, `".class"` | 小程序 |
| `$element_path` | 元素路径 | 元素在页面中的路径 | `"page > .container > view"` | 小程序 |

#### $MPShare 专属属性

| 属性名 | 属性显示名 | 描述 | 示例值 | 采集来源 |
|-------|-----------|------|-------|---------|
| `$share_method` | 分享途径 | 分享的方式 | `"分享到朋友圈"`, `"转发消息卡片"` | 小程序 |

#### $FeatureImpress 专属属性

| 属性名 | 属性显示名 | 描述 | 示例值 | 采集来源 |
|-------|-----------|------|-------|---------|
| `$feature_key` | 功能开关标识 | 功能开关的唯一标识 | `"new_ui_enabled"`, `"dark_mode"` | 全平台 |
| `$feature_variant` | 功能开关变体 | 功能开关的变体值 | `"pass"`, `"fail"` | 全平台 |

#### $ExpImpress 专属属性

| 属性名 | 属性显示名 | 描述 | 示例值 | 采集来源 |
|-------|-----------|------|-------|---------|
| `$exp_key` | 实验标识 | 实验的唯一标识 | `"button_color_test"`, `"layout_v2"` | 全平台 |
| `$exp_variant` | 实验变体 | 实验的变体值 | `"v0"`, `"v1"`, `"v2"` | 全平台 |

## 预置用户属性

预置用户属性用于描述用户的基本信息和关键时间节点,存储在用户表中。

### 系统保留用户属性

| 属性名 | 显示名 | 描述 | 数据类型 |
|-------|-------|------|---------|
| `ssid` | 服务端用户唯一 ID | 服务端生成的用户唯一 ID,基于 distinct_id 哈希计算,用于用户关联和修正 | Int64 |
| `user_id` | 登录 ID | 用户的登录 ID,标识已登录用户的业务账号 | String |
| `anon_ids` | 匿名 ID 列表 | 同一个用户使用过的匿名 ID 列表 | Array |
| `created_at` | 用户创建时间 | 用户首次被记录的时间 | DateTime |
| `updated_at` | 用户更新时间 | 用户属性最后更新时间 | DateTime |
| `aid` | 用户自增 ID | 用户的自增 ID,用于内部索引 | Int |

### Feature 相关用户属性

当用户命中功能开关时,系统会自动记录以下用户属性:

| 属性名 | 显示名 | 描述 | 示例值 |
|-------|-------|------|-------|
| `$feature_{ID}` | {功能开关名}_{ID} | 记录用户命中的功能开关状态 | `"pass"` / `"fail"` |

**说明**:

- **pass**:用户通过功能开关,可以使用新功能
- **fail**:用户未通过功能开关,无法使用新功能

**示例**:

```javascript
// 用户命中了 ID 为 123 的功能开关,通过
{
  $feature_123: "pass"
}

// 用户命中了 ID 为 456 的功能开关,未通过
{
  $feature_456: "fail"
}
```

### UTM 相关用户属性

当用户通过带有 UTM 参数的链接访问时,系统会自动记录以下用户属性:

| 属性名 | 显示名 | 描述 | 示例值 |
|-------|-------|------|-------|
| `$utm_source` | 广告来源 | 标识流量来源,如搜索引擎、网站名称 | `"newsletter"`, `"google"` |
| `$utm_medium` | 广告媒介 | 标识营销媒介,如邮件、CPC | `"email"`, `"cpc"`, `"social"` |
| `$utm_campaign` | 广告活动 | 标识具体的营销活动 | `"product_launch"`, `"summer_sale"` |
| `$utm_term` | 广告关键词 | 标识付费搜索的关键词 | `"new+product"`, `"data+analytics"` |
| `$utm_content` | 广告内容 | 用于区分同一广告的不同内容或链接 | `"logolink"`, `"textlink"` |
| `$initial_utm_source` | 首次广告来源 | 用户首次访问时的广告来源 | `"newsletter"`, `"google"` |
| `$initial_utm_medium` | 首次广告媒介 | 用户首次访问时的广告媒介 | `"email"`, `"cpc"`, `"social"` |
| `$initial_utm_campaign` | 首次广告活动 | 用户首次访问时的广告活动 | `"product_launch"`, `"summer_sale"` |
| `$initial_utm_term` | 首次广告关键词 | 用户首次访问时的广告关键词 | `"new+product"`, `"data+analytics"` |

**说明**:

- `$utm_*` 属性记录用户最近一次访问的广告来源信息,会随着每次带有 UTM 参数的访问而更新
- `$initial_utm_*` 属性记录用户首次访问时的广告来源信息,一旦设置后不再变更
- 首次 UTM 属性可以帮助您分析用户的原始获取渠道,追踪用户的来源归因

### Experiment 相关用户属性

当用户命中实验时,系统会自动记录以下用户属性:

| 属性名 | 显示名 | 描述 | 示例值 |
|-------|-------|------|-------|
| `$exp_{ID}` | {实验名}_{ID} | 记录用户命中的实验版本 | `"v0"`, `"v1"`, `"v2"` |

**说明**:

- 实验版本标识,如 `"v0"`(对照组)、`"v1"`、`"v2"` 等
- 用于记录用户在实验中被分配到的版本

**示例**:

```javascript
// 用户命中了 ID 为 789 的实验,分配到 v1 版本
{
  $exp_789: "v1"
}

// 用户命中了 ID 为 1000 的实验,分配到对照组
{
  $exp_1000: "v0"
}
```

## 预置属性的使用方式

### 自动采集

大部分预置属性由 SDK 自动采集,无需手动上报。只需正确集成 SDK,即可自动获得这些属性。

```javascript
// Web SDK 示例:SDK 自动采集预置属性
sensorswave.trackEvent('PageView');

// 实际发送的事件包含预置属性:
// {
//   event: "PageView",
//   time: 1769595185716,
//   $url: "https://example.com/products",
//   $pathname: "/products",
//   $browser: "Chrome",
//   $browser_version: "125",
//   $os: "Windows",
//   $os_version: "10",
//   $screen_width: 1920,
//   $screen_height: 1080,
//   ...
// }
```

### 手动覆盖(可选)

某些预置属性支持手动覆盖,您可以在上报事件时提供自定义值:

```javascript
// 覆盖预置属性的值
sensorswave.trackEvent('Purchase', {
  $referrer: 'https://custom-referrer.com',  // 覆盖默认的 $referrer
  order_id: 'ORDER-001',                     // 自定义事件属性
  total_amount: 299.00
});
```

> **注意**:
> - 系统保留属性(如 `time`、`event_id`、`ssid`)不可被覆盖
> - 仅在有明确需求时才覆盖预置属性,否则可能导致数据不一致

### 在分析中使用

预置属性可以像自定义属性一样用于数据分析:

- **筛选**:筛选特定浏览器、操作系统、来源渠道的事件
- **分组**:按设备型号、地理位置、广告来源等维度分组统计
- **聚合**:计算不同维度下的事件数量、转化率等指标

**示例:按浏览器类型分析页面浏览量**

1. 选择事件:`$PageView`
2. 分组维度:选择 `$browser`
3. 查看结果:Chrome、Safari、Firefox 等浏览器的页面浏览量分布

## 最佳实践

### 1. 了解预置属性的采集范围

不同平台的 SDK 采集的预置属性有所不同:

- **Web SDK**:采集浏览器、设备、URL 等相关属性
- **App SDK**:采集设备、网络、应用版本等相关属性
- **小程序 SDK**:采集设备品牌、网络类型、页面路径等相关属性
- **服务端**:采集 IP 解析相关属性

在设计分析方案时,需要了解目标平台支持的预置属性,避免依赖不存在的属性。

### 2. 避免与预置属性冲突

自定义属性不要使用 `$` 前缀,避免与预置属性命名冲突:

```javascript
// 不推荐:使用 $ 前缀
sensorswave.trackEvent('Purchase', {
  $custom_field: 'value'  // 可能与预置属性冲突
});

// 推荐:不使用 $ 前缀
sensorswave.trackEvent('Purchase', {
  custom_field: 'value'   // 清晰区分自定义属性
});
```

### 3. 利用预置属性减少埋点工作

充分利用 SDK 自动采集的预置属性,避免重复埋点:

```javascript
// 不推荐:手动上报浏览器信息
sensorswave.trackEvent('PageView', {
  browser: navigator.userAgent,  // SDK 已自动采集 $browser
  url: window.location.href      // SDK 已自动采集 $url
});

// 推荐:依赖 SDK 自动采集
sensorswave.trackEvent('PageView', {
  page_category: 'product'  // 只上报 SDK 未采集的自定义属性
});
```

### 4. 合理使用 UTM 参数

在营销活动中,统一使用 UTM 参数追踪流量来源:

**推荐做法**:

- 为每个营销活动设置完整的 UTM 参数
- 使用统一的命名规范(小写、下划线分隔)
- 在团队内部建立 UTM 参数管理规范

**示例**:

```
# 邮件营销活动
https://example.com/product?utm_source=newsletter&utm_medium=email&utm_campaign=summer_sale

# Google Ads 投放
https://example.com/product?utm_source=google&utm_medium=cpc&utm_campaign=brand_keywords&utm_term=sensors+wave

# 社交媒体推广
https://example.com/product?utm_source=wechat&utm_medium=social&utm_campaign=product_launch&utm_content=banner
```

### 5. 监控预置属性的数据质量

定期检查预置属性的数据质量,确保 SDK 正常工作:

- 检查 `$browser`、`$os` 等属性的覆盖率
- 验证 `$url`、`$referrer` 等属性的准确性
- 监控 `$ip`、`$city` 等 IP 解析属性的解析成功率

## 注意事项

### 系统保留属性不可修改

系统保留属性(如 `time`、`event_id`、`ssid`)由系统自动生成,不可被手动覆盖或修改。如果尝试覆盖这些属性,将被忽略。

### 预置属性的可用性

- **客户端采集的属性**:仅在客户端上报事件时自动采集,服务端埋点不会包含这些属性
- **IP 解析属性**:依赖客户端 IP 地址,如果 IP 地址无法解析(如内网 IP),相关属性可能为空
- **UTM 参数**:仅在 URL 包含 UTM 参数时才会采集,否则相关属性为空

### 预置属性的命名限制

- `$` 前缀为系统保留,仅用于预置属性
- 自定义属性不要使用 `$` 前缀
- 不要创建与预置属性同名的自定义属性

### 跨平台差异

不同平台的预置属性有所差异:

- **Web 端**:包含浏览器相关属性(如 `$browser`、`$url`)
- **App 端**:包含应用相关属性(如 `$app_version`、`$network_type`)
- **小程序端**:包含小程序相关属性(如 `$url_path`、`$url_query`)
- **通用属性**:所有平台都支持(如 `$os`、`$ip`)

在进行跨平台分析时,需要注意属性的可用性。

## 相关文档

- [数据模型](data-model.mdx)：了解事件、属性在整体数据模型中的位置和作用
- [事件和属性](events-and-properties.mdx)：了解如何设计自定义事件和属性
- [属性数据类型](property-data-types.mdx)：了解 Sensors Wave 支持的属性数据类型及使用规范
- [如何正确的标识用户](user-identification.mdx)：了解用户标识相关的预置属性（`anon_id`、`user_id`、`ssid`）的含义

---

**最后更新时间**:2026 年 1 月 28 日