Title: 事件和属性
Locale: zh
URL: https://sensorswave.com/docs/data-integration/events-and-properties/
Description: 事件和属性的定义、命名规范和使用指南
事件是 Sensors Wave 数据模型的核心，记录用户在应用中执行的具体行为。事件属性和用户属性则为事件提供上下文信息，帮助您进行多维度的数据分析。正确设计事件、事件属性和用户属性是进行有效数据分析的基础，直接影响分析的深度和价值。

## 为什么要了解事件和属性？

合理设计事件、事件属性和用户属性可以帮助您：

- **准确记录用户行为**：捕获关键业务动作和用户意图，支持全面的行为分析
- **提高分析灵活性**：通过事件属性和用户属性对事件进行多维度筛选、分组和聚合分析
- **降低维护成本**：使用通用事件配合属性，避免为每个细微差异创建新事件
- **提升数据质量**：遵循命名规范和最佳实践，确保数据的一致性和可扩展性
- **实现精准用户分群**：通过用户属性构建准确的用户画像，支持个性化分析

## 核心概念

### 什么是事件？

事件是用户在应用中执行的具体行为或系统中发生的活动。每个事件代表一个值得追踪和分析的用户动作。

**事件的组成**：

每个事件包含以下核心要素：

- **事件名称** (`event`)：描述用户行为的名称，如 `PageView`、`Purchase`、`UserLogin`
- **事件时间** (`time`)：事件发生的时间戳（客户端时间）
- **用户标识**：
  - `distinct_id`：当前生效的用户唯一标识
  - `anon_id`：匿名 ID，标识设备或浏览器
  - `login_id`：登录 ID，标识已登录用户
  - `ssid`：服务端生成的用户唯一 ID，用于数据分析
- **事件属性**：描述事件的详细信息和上下文，如商品 ID、金额、来源渠道等
- **用户属性快照**：事件发生那一刻用户的属性状态

**常见事件类型**：

| 业务场景 | 典型事件 | 说明 |
|---------|---------|------|
| **电商平台** | `ProductView`、`AddToCart`、`Purchase` | 商品浏览、加购、购买行为 |
| **内容平台** | `ArticleRead`、`VideoPlay`、`ContentShare` | 内容消费和分享行为 |
| **SaaS 应用** | `UserSignup`、`FeatureUsed`、`SubscriptionRenew` | 用户注册、功能使用、订阅续费 |
| **移动应用** | `AppOpen`、`ScreenView`、`NotificationClick` | 应用打开、页面浏览、通知点击 |

### 什么是事件属性？

事件属性用于描述事件发生时的具体情况和上下文信息。事件属性随事件一起上报，为分析提供必要的维度和细节。

**事件属性的特点**：

- 与特定事件关联，描述"这次行为"的详细信息
- 只在事件发生时记录，不会持久化到用户维度
- 可以用于事件筛选、分组、聚合等分析
- 同一事件的不同实例可以有不同的属性值

**事件属性示例**：

对于 `Purchase` 事件，常见的事件属性包括：

```javascript
{
  event: "Purchase",
  properties: {
    order_id: "ORDER-2026-001",      // 订单 ID
    total_amount: 299.00,            // 订单总金额
    currency: "CNY",                 // 货币类型
    payment_method: "alipay",        // 支付方式
    item_count: 3,                   // 商品数量
    product_category: "electronics", // 商品类别
    discount_amount: 20.00,          // 优惠金额
    shipping_method: "express"       // 配送方式
  }
}
```

### 什么是用户属性？

用户属性用于描述用户的特征和状态，如人口统计信息、行为偏好、账户信息等。与事件属性不同，用户属性是持久化存储的，代表用户在某一时刻的整体画像。

**用户属性的特点**：

- 描述用户的整体特征，而非单次行为
- 存储在用户维度表中，可以随时更新
- 用于用户分群、细分和个性化分析
- 支持多种数据类型：字符串、数值、布尔、日期、列表

**用户属性示例**：

```javascript
// 设置用户属性
sensorswave.setUserProfile({
  user_id: "user_12345",
  name: "张三",
  age: 28,
  gender: "male",
  city: "北京",
  membership_level: "gold",
  registration_date: "2025-01-15",
  total_purchase_count: 15,
  total_spent: 4580.00,
  favorite_categories: ["electronics", "books", "sports"],
  is_vip: true,
  last_login_date: "2026-01-22"
});
```

**常见用户属性类型**：

| 类别 | 典型属性 | 说明 |
|------|---------|------|
| **人口统计信息** | `age`、`gender`、`city`、`occupation` | 描述用户的基本特征 |
| **账户信息** | `membership_level`、`registration_date`、`account_status` | 描述用户的账户状态 |
| **行为特征** | `total_purchase_count`、`last_login_date`、`avg_session_duration` | 描述用户的行为模式 |
| **偏好信息** | `favorite_categories`、`preferred_payment_method`、`language` | 描述用户的偏好和习惯 |
| **业务指标** | `total_spent`、`lifetime_value`、`churn_risk_score` | 描述用户的业务价值 |

**用户属性更新方式**：

Sensors Wave 支持多种用户属性更新操作：

```javascript
// 1. 设置属性（set）- 设置或更新用户属性
sensorswave.setUserProfile({
  city: "上海",
  membership_level: "platinum"
});

// 2. 首次设置（set_once）- 仅在属性不存在时设置
sensorswave.setOnceUserProfile({
  first_visit_date: "2026-01-22",
  registration_channel: "wechat"
});

// 3. 累加属性（increment）- 对数值属性进行累加
sensorswave.incrementUserProfile({
  total_purchase_count: 1,
  total_spent: 299.00
});

// 4. 追加列表（append）- 向列表属性追加值
sensorswave.appendUserProfile({
  favorite_categories: "home_appliances"
});

// 5. 删除属性（unset）- 删除指定属性
sensorswave.unsetUserProfile(["old_field_1", "old_field_2"]);
```

### 事件属性 vs 用户属性

理解事件属性和用户属性的区别对于正确设计数据模型至关重要：

| 对比维度 | 事件属性 | 用户属性 |
|---------|---------|---------|
| **数据范围** | 描述单次事件的详细信息 | 描述用户的整体特征 |
| **存储方式** | 存储在事件表中，随事件记录 | 以快照方式存储在事件表中，最新值存储在用户表中 |
| **更新方式** | 事件发生时记录，不可修改 | 可以随时更新、增加或删除（仅限用户表） |
| **分析用途** | 事件筛选、分组统计、趋势分析 | 用户分群、留存分析、转化分析 |
| **示例** | 订单金额、商品类别、页面 URL | 用户年龄、会员等级、注册时间 |

**选择建议**：

- **使用事件属性**：当信息与特定行为相关，且在不同事件中可能有不同值时
  - 商品 SKU（不同购买事件可能购买不同商品）
  - 页面 URL（不同浏览事件访问不同页面）
  - 订单金额（每次购买金额不同）
  - 视频时长（每个视频播放时长不同）

- **使用用户属性**：当信息描述用户整体特征，相对稳定时
  - 用户年龄（相对固定）
  - 会员等级（在一段时间内保持不变）
  - 注册时间（固定不变）
  - 所在城市（相对稳定）

> **注意**：同一个信息可以同时作为事件属性和用户属性。例如，用户在某次购买时的会员等级可以作为事件属性记录（描述购买时的状态），同时当前会员等级也可以作为用户属性存储（描述用户当前状态）。

## 事件设计原则

### 1. 事件粒度要适中

事件既不应过于宽泛，也不应过于具体。事件的粒度应该与您计划分析用户行为的层级相匹配。

**推荐做法**：
- 使用通用事件名称配合属性来区分细节
  - 事件：`PageView`，属性：`page_name: "/home"` 或 `page_name: "/pricing"`
  - 事件：`ButtonClick`，属性：`button_name: "add_to_cart"` 或 `button_name: "checkout"`
  - 事件：`VideoPlay`，属性：`video_id: "V12345"`、`video_category: "tutorial"`

**避免的做法**：
- (不推荐) 为每个页面创建单独的事件
  - `HomePageView`、`PricingPageView`、`ProductPageView`（过于具体）
- (不推荐) 为每个按钮创建单独的事件
  - `AddToCartButtonClick`、`CheckoutButtonClick`（过于具体）
- (不推荐) 使用过于宽泛的事件名称
  - `UserAction`、`Click`（过于宽泛，缺少语义）

**对比示例**：

```javascript
// 不推荐：为每个页面创建单独事件
sensorswave.trackEvent('HomePageView');
sensorswave.trackEvent('PricingPageView');
sensorswave.trackEvent('ProductPageView');

// 推荐：使用通用事件配合属性
sensorswave.trackEvent('PageView', {
  page_name: '/home',
  page_title: '首页',
  page_category: 'marketing'
});

sensorswave.trackEvent('PageView', {
  page_name: '/pricing',
  page_title: '定价',
  page_category: 'marketing'
});
```

### 2. 事件命名规范

统一的命名规范有助于保持数据的一致性，降低团队协作成本。

**事件名称规范**：

- **推荐使用大写驼峰格式（PascalCase）**：如 `PageView`、`UserLogin`、`AddToCart`
- **采用"对象 + 动作"格式**：如 `ProductView`（商品查看）、`OrderCreate`（订单创建）
- **保持语义清晰**：事件名称应该清楚表达用户的具体行为
- **避免使用缩写**：除非是广泛认可的缩写（如 `URL`、`ID`）
- **历史兼容性**：如果已存在历史埋点数据采用小写下划线风格（snake_case），可以继续保持该风格，但务必在同一应用中**保持统一**
- **预置事件**：SDK 预置的系统事件（如 `$Identify`、`$ABImpress` 等）统一采用 `$` 前缀 + 大写驼峰格式

**推荐示例**：
```javascript
PageView          // 页面浏览
ProductView       // 商品查看
AddToCart         // 加入购物车
OrderCreate       // 订单创建
Purchase          // 购买
UserSignup        // 用户注册
VideoPlay         // 视频播放
ButtonClick       // 按钮点击
```

**不推荐示例**：
```javascript
page_view         // 小写下划线（除非有历史数据）
ViewProduct       // 应使用"对象 + 动作"格式
Click             // 过于宽泛
PV                // 避免使用缩写
purchase_2026     // 不要在事件名称中包含日期
```

**历史数据兼容说明**：

如果您的应用已经使用小写下划线格式（如 `page_view`、`add_to_cart`）并且有大量历史数据，可以继续使用该格式，但请注意：
- **保持一致性**：同一应用中的所有事件必须使用相同的命名风格
- **新应用推荐**：对于新项目，强烈推荐使用大写驼峰格式
- **统一团队规范**：在团队内部制定统一的命名规范文档并严格执行

### 3. 事件属性命名规范

**属性名称规范**：

- **使用下划线命名法（snake_case）**：如 `order_id`、`total_amount`、`page_url`
- **保持简洁且具有描述性**：如 `product_name` 而非 `pn`
- **避免与预置属性冲突**：不要使用 `$` 前缀（系统保留）
- **统一单位和格式**：如金额统一使用元、时间统一使用秒

**正确示例**：
```javascript
(推荐) order_id          // 订单 ID
(推荐) total_amount      // 总金额
(推荐) product_name      // 商品名称
(推荐) page_url          // 页面 URL
(推荐) video_duration    // 视频时长（秒）
```

**错误示例**：
```javascript
(不推荐) OrderID           // 应使用下划线命名法
(不推荐) totalAmount       // 应使用下划线命名法
(不推荐) $custom_prop      // 避免使用 $ 前缀
(不推荐) mp_source         // 避免使用 mp_ 前缀
(不推荐) pn                // 避免缩写
```

### 4. 属性值类型要明确

属性值的数据类型应该保持一致，避免混用不同类型。

**支持的数据类型**：

Sensors Wave 支持以下五种数据类型：

| 数据类型 | 说明 | 示例 |
|---------|------|------|
| **String（字符串）** | 文本数据 | `"alipay"`、`"electronics"` |
| **Numeric（数值）** | 整数或浮点数 | `299.00`、`42` |
| **Boolean（布尔）** | 真或假 | `true`、`false` |
| **Datetime（日期）** | 日期时间 | `"2026-01-21T10:30:00Z"` |
| **List（列表）** | 数组，包含多个值 | `["red", "blue"]`、`[1, 2, 3]` |

**推荐做法**：
- 同一属性在所有事件中使用相同的数据类型
  - `total_amount` 始终为 Numeric
  - `payment_method` 始终为 String
  - `is_member` 始终为 Boolean

**避免的做法**：
- 同一属性混用不同数据类型
  - `total_amount: "299"` 和 `total_amount: 299`（字符串 vs 数值）
  - `is_member: "true"` 和 `is_member: true`（字符串 vs 布尔）

### 5. 使用全局属性

全局属性（Super Properties）是几乎每个事件（通常 > 80%）都会追踪的事件属性，提供统一的上下文信息。

**常见的全局属性**：

- **设备信息**：`device_type`、`os_name`、`os_version`、`browser_name`
- **应用信息**：`app_version`、`app_build_number`
- **地理位置**：`country`、`region`、`city`
- **流量来源**：`utm_source`、`utm_medium`、`utm_campaign`
- **会话信息**：`session_id`、`referrer`

**代码示例**：

```javascript
// 设置全局属性，所有后续事件都会自动包含这些属性
sensorswave.registerSuperProperties({
  app_version: '2.5.0',
  device_type: 'mobile',
  os_name: 'iOS',
  os_version: '17.2'
});

// 后续追踪的事件会自动包含全局属性
sensorswave.trackEvent('Purchase', {
  order_id: 'ORDER-001',
  total_amount: 299.00
});
// 实际发送的事件包含：
// { order_id, total_amount, app_version, device_type, os_name, os_version }
```

## 事件属性设计最佳实践

### 1. 设计事件属性时考虑分析需求

在添加事件属性之前，思考您将如何使用这些属性进行分析。

**分析维度**：
- **筛选**：您需要筛选哪些事件？（例如：只看金额 > 100 的订单）
- **分组**：您需要按什么维度分组？（例如：按支付方式、商品类别分组）
- **聚合**：您需要计算什么指标？（例如：总金额、平均订单价值）

**示例：购买事件属性设计**：

```javascript
sensorswave.trackEvent('Purchase', {
  // 唯一标识
  order_id: 'ORDER-2026-001',

  // 金额相关（用于聚合分析）
  total_amount: 299.00,
  discount_amount: 20.00,
  tax_amount: 15.00,
  currency: 'CNY',

  // 商品信息（用于分组分析）
  product_category: 'electronics',
  product_brand: 'Apple',
  item_count: 2,

  // 支付信息（用于筛选和分组）
  payment_method: 'alipay',
  payment_status: 'success',

  // 渠道信息（用于来源分析）
  order_source: 'mobile_app',
  referrer_channel: 'wechat'
});
```

### 2. 保持属性值的一致性

相同语义的属性值应该使用统一的格式和表述。

**推荐做法**：
- 建立属性值的枚举规范
  - `payment_method` 的值统一为：`alipay`、`wechat`、`credit_card`
  - `order_status` 的值统一为：`pending`、`paid`、`shipped`、`completed`
- 使用小写字母配合下划线
  - (推荐) `payment_method: "credit_card"`
  - (不推荐) `payment_method: "Credit Card"` 或 `"CreditCard"`

**避免的做法**：
- 同一属性值使用多种表述
  - `payment_method: "alipay"`、`"支付宝"`、`"Alipay"` 混用
  - `order_status: "paid"`、`"已支付"`、`"PAID"` 混用

### 3. 避免动态属性名称

不要根据业务数据动态生成属性名称，而应该使用固定的属性名称和动态的属性值。

**推荐做法**：
```javascript
// 使用固定属性名称，动态属性值
sensorswave.trackEvent('Purchase', {
  product_category: 'electronics',
  product_name: '无线蓝牙耳机'
});
```

**避免的做法**：
```javascript
// 不要使用动态属性名称
sensorswave.trackEvent('Purchase', {
  'product_electronics': '无线蓝牙耳机'
});
```

### 4. 合理控制属性数量

虽然 Sensors Wave 支持每个事件最多 255 个属性，但并不意味着您应该追踪所有可能的属性。

**推荐做法**：
- 每个事件保持 5-20 个核心属性
- 只追踪对分析有价值的属性
- 定期审查和清理不再使用的属性

**避免的做法**：
- 将所有数据库字段都作为事件属性上报
- 追踪冗余或重复的属性信息

### 5. 敏感信息处理

不要在事件属性中存储敏感的个人信息或安全凭证。

**避免追踪的敏感信息**：
- 密码、访问令牌、API 密钥
- 完整的信用卡号、身份证号
- 未加密的个人健康信息
- 完整的电话号码、邮箱地址（除非符合隐私政策）

**推荐做法**：
- 使用脱敏或哈希处理后的值
  - `phone_last4: "8888"`（仅保留后 4 位）
  - `email_domain: "gmail.com"`（仅保留域名）
- 使用标识符而非原始值
  - `user_id: "U123456"` 而非完整个人信息

## 代码示例

### JavaScript SDK 示例

```javascript
// 基础事件追踪
sensorswave.trackEvent('PageView', {
  page_url: window.location.href,
  page_title: document.title,
  page_category: 'product',
  referrer: document.referrer
});

// 购买事件
sensorswave.trackEvent('Purchase', {
  order_id: 'ORDER-2026-001',
  total_amount: 299.00,
  currency: 'CNY',
  payment_method: 'alipay',
  product_category: 'electronics',
  item_count: 2
});

// 使用全局属性
sensorswave.registerSuperProperties({
  app_version: '2.5.0',
  platform: 'web',
  language: 'zh-CN'
});

// 设置用户属性
sensorswave.setUserProfile({
  user_id: 'user_12345',
  name: '张三',
  age: 28,
  city: '北京',
  membership_level: 'gold'
});

// 首次设置用户属性（注册信息）
sensorswave.setOnceUserProfile({
  registration_date: '2025-01-15',
  first_channel: 'wechat'
});

// 累加用户属性（购买后更新）
sensorswave.incrementUserProfile({
  total_purchase_count: 1,
  total_spent: 299.00
});

// 追加列表属性（浏览历史）
sensorswave.appendUserProfile({
  browsed_categories: 'electronics'
});
```

### Go SDK 示例

```go
// 基础事件追踪
user := sensorswave.User{
    LoginID: "user123",
}

err := client.TrackEvent(user, "Purchase", sensorswave.Properties{
    "order_id":         "ORDER-2026-001",
    "total_amount":     299.00,
    "currency":         "CNY",
    "payment_method":   "alipay",
    "product_category": "electronics",
    "item_count":       2,
})

// 使用完整事件结构
event := sensorswave.NewEvent("anon-123", "user123", "ProductView").
    WithProperties(sensorswave.NewProperties().
        Set("product_id", "SKU-12345").
        Set("product_name", "无线蓝牙耳机").
        Set("category", "electronics"))

err = client.Track(event)

// 设置用户档案属性
err = client.ProfileSet(user, sensorswave.Properties{
    "name":             "张三",
    "age":              28,
    "city":             "北京",
    "membership_level": "gold",
})

// 首次设置用户档案属性
err = client.ProfileSetOnce(user, sensorswave.Properties{
    "registration_date": "2025-01-15",
    "first_channel":     "wechat",
})

// 增加用户档案属性
err = client.ProfileIncrement(user, sensorswave.Properties{
    "total_purchase_count": 1,
    "total_spent":          299.00,
})
```

### Android SDK 示例

```java
// 基础事件追踪
JSONObject properties = new JSONObject();
properties.put("order_id", "ORDER-2026-001");
properties.put("total_amount", 299.00);
properties.put("currency", "CNY");
properties.put("payment_method", "alipay");
properties.put("item_count", 2);

sensorswave.track("Purchase", properties);

// 设置全局属性
JSONObject superProperties = new JSONObject();
superProperties.put("app_version", "2.5.0");
superProperties.put("platform", "android");
sensorswave.registerSuperProperties(superProperties);

// 设置用户属性
JSONObject userProperties = new JSONObject();
userProperties.put("name", "张三");
userProperties.put("age", 28);
userProperties.put("city", "北京");
userProperties.put("membership_level", "gold");
sensorswave.setUserProfile(userProperties);

// 首次设置用户属性
JSONObject onceProperties = new JSONObject();
onceProperties.put("registration_date", "2025-01-15");
onceProperties.put("first_channel", "wechat");
sensorswave.setOnceUserProfile(onceProperties);

// 累加用户属性
JSONObject incrementProperties = new JSONObject();
incrementProperties.put("total_purchase_count", 1);
incrementProperties.put("total_spent", 299.00);
sensorswave.incrementUserProfile(incrementProperties);
```

### iOS SDK 示例

```swift
// 基础事件追踪
let properties: [String: Any] = [
    "order_id": "ORDER-2026-001",
    "total_amount": 299.00,
    "currency": "CNY",
    "payment_method": "alipay",
    "item_count": 2
]

sensorswave.track("Purchase", properties: properties)

// 设置全局属性
let superProperties: [String: Any] = [
    "app_version": "2.5.0",
    "platform": "ios"
]
sensorswave.registerSuperProperties(superProperties)

// 设置用户属性
let userProperties: [String: Any] = [
    "name": "张三",
    "age": 28,
    "city": "北京",
    "membership_level": "gold"
]
sensorswave.setUserProfile(userProperties)

// 首次设置用户属性
let onceProperties: [String: Any] = [
    "registration_date": "2025-01-15",
    "first_channel": "wechat"
]
sensorswave.setOnceUserProfile(onceProperties)

// 累加用户属性
let incrementProperties: [String: Any] = [
    "total_purchase_count": 1,
    "total_spent": 299.00
]
sensorswave.incrementUserProfile(incrementProperties)
```

## 数据限制

了解 Sensors Wave 的数据限制有助于您更好地设计事件和属性：

| 限制项 | 限制值 | 说明 |
|-------|-------|------|
| **事件类型数量** | 1000 个 | 不同事件名称的总数上限 |
| **单个事件的属性数量** | 255 个 | 单个事件关联的事件属性数量上限 |
| **事件属性总数** | 500 个 | 所有事件属性的总数上限 |
| **用户属性总数** | 500 个 | 所有用户属性的总数上限 |
| **属性名称长度** | 255 字符 | 超出部分会被截断 |
| **属性值长度（String）** | 255 字符 | 超出部分会被截断 |
| **List 属性大小（事件属性）** | 8 KB | 超出部分会被截断 |
| **List 属性大小（用户属性）** | 256 KB | 超出部分会被截断 |

> **提示**：
> - 事件类型数量限制为 1000 个，建议使用通用事件名称配合属性来区分细节，避免为每个细微差异创建新事件
> - 事件属性和用户属性各有 500 个的总数限制，建议定期清理不再使用的属性
> - 虽然单个事件可以有 255 个属性，但建议保持 5-20 个核心属性，确保数据简洁

## 用户属性设计最佳实践

### 1. 选择合适的属性类型

根据信息的性质和使用场景，选择正确的用户属性类型。

**标准用户属性（Profile Properties）**：
- 描述用户的基本特征和状态
- 使用 `setUserProfile()` 方法设置
- 适用于大多数场景

**首次设置属性（Set Once）**：
- 仅在首次设置时生效，后续不会被覆盖
- 使用 `setOnceUserProfile()` 方法
- 适用于注册时间、首次来源等不变信息

**累加属性（Increment）**：
- 对数值型属性进行累加操作
- 使用 `incrementUserProfile()` 方法
- 适用于购买次数、总消费金额等累计指标

**列表属性（Append）**：
- 向列表中追加新值，保留历史记录
- 使用 `appendUserProfile()` 方法
- 适用于浏览过的类目、使用过的功能等

**示例**：

```javascript
// 首次设置 - 注册信息
sensorswave.setOnceUserProfile({
  registration_date: "2026-01-22",
  first_channel: "wechat",
  first_device: "iOS"
});

// 标准设置 - 可更新的用户信息
sensorswave.setUserProfile({
  city: "北京",
  membership_level: "gold",
  last_login_date: "2026-01-22"
});

// 累加 - 业务指标
sensorswave.incrementUserProfile({
  total_purchase_count: 1,
  total_spent: 299.00,
  login_days: 1
});

// 追加 - 行为历史
sensorswave.appendUserProfile({
  browsed_categories: "electronics",
  used_features: "video_chat"
});
```

### 2. 保持用户属性的时效性

用户属性应该反映用户的当前状态，需要及时更新。

**推荐做法**：
- 在关键业务事件发生时更新用户属性
  - 用户完成购买后，更新 `total_purchase_count` 和 `total_spent`
  - 用户升级会员后，更新 `membership_level` 和 `membership_upgrade_date`
  - 用户更新个人信息后，同步更新对应的用户属性

- 定期批量更新计算类属性
  - 每日计算用户的活跃天数、最近 30 天消费金额等
  - 定期更新用户的生命周期阶段、流失风险评分等

**代码示例**：

```javascript
// 在购买事件中同步更新用户属性
sensorswave.trackEvent('Purchase', {
  order_id: 'ORDER-001',
  total_amount: 299.00
});

// 同时更新用户的累计消费数据
sensorswave.incrementUserProfile({
  total_purchase_count: 1,
  total_spent: 299.00
});

sensorswave.setUserProfile({
  last_purchase_date: new Date().toISOString(),
  latest_purchase_amount: 299.00
});
```

### 3. 合理设计用户分群属性

设计用户属性时，应考虑后续的用户分群和细分需求。

**常见分群维度**：

| 分群类型 | 相关属性 | 分群示例 |
|---------|---------|---------|
| **人口统计分群** | `age`、`gender`、`city`、`occupation` | 25-35 岁的北京女性用户 |
| **行为分群** | `total_purchase_count`、`avg_order_value`、`last_active_date` | 近 30 天活跃且购买 3 次以上的用户 |
| **价值分群** | `total_spent`、`lifetime_value`、`membership_level` | 累计消费超过 5000 元的金卡会员 |
| **生命周期分群** | `registration_date`、`days_since_last_purchase`、`churn_risk` | 注册 90 天以上但 30 天未登录的流失风险用户 |
| **偏好分群** | `favorite_categories`、`preferred_payment_method`、`content_preferences` | 偏好电子产品且使用支付宝的用户 |

**示例**：

```javascript
// 设计支持精细分群的用户属性
sensorswave.setUserProfile({
  // 人口统计
  age: 28,
  gender: "female",
  city: "北京",

  // 行为指标
  total_purchase_count: 15,
  avg_order_value: 458.50,
  last_active_date: "2026-01-22",
  active_days_last_30: 18,

  // 价值指标
  total_spent: 6877.50,
  lifetime_value: 8500.00,
  membership_level: "gold",

  // 生命周期
  registration_date: "2025-01-15",
  days_since_registration: 372,
  days_since_last_purchase: 5,
  user_lifecycle_stage: "active",

  // 偏好信息
  favorite_categories: ["electronics", "books"],
  preferred_payment_method: "alipay",
  preferred_delivery_time: "evening"
});
```

### 4. 避免敏感信息

用户属性中不应包含敏感的个人身份信息（PII）。

**避免存储的敏感信息**：
- 完整姓名、身份证号、护照号
- 完整手机号、完整邮箱地址
- 密码、支付密码、安全问题答案
- 信用卡号、银行账号
- 详细家庭住址、GPS 坐标

**推荐的替代方案**：
- 使用加密或脱敏后的标识符
  - `user_id: "U123456"` 而非真实姓名
  - `phone_area_code: "010"` 或 `phone_last4: "8888"` 而非完整手机号
  - `email_domain: "gmail.com"` 而非完整邮箱

- 使用派生或聚合数据
  - `age: 28` 或 `age_group: "25-30"` 而非出生日期
  - `city: "北京"` 而非详细地址
  - `region: "华北"` 而非精确位置

### 5. 用户属性命名规范

与事件属性类似，用户属性也应遵循统一的命名规范。

**命名规范**：
- 使用下划线命名法（snake_case）：`membership_level`、`total_spent`
- 保持语义清晰：`registration_date` 而非 `reg_dt`
- 避免使用 `$` 前缀（系统保留）
- 布尔类型使用 `is_`、`has_` 前缀：`is_vip`、`has_purchased`
- 日期类型使用 `_date`、`_time` 后缀：`last_login_date`、`registration_date`
- 计数类型使用 `_count` 后缀：`login_count`、`purchase_count`

**示例**：

```javascript
// 推荐的命名
{
  membership_level: "gold",
  total_spent: 5000.00,
  is_vip: true,
  has_purchased: true,
  registration_date: "2025-01-15",
  last_login_date: "2026-01-22",
  total_purchase_count: 15
}

// 不推荐的命名
{
  membershipLevel: "gold",     // 应使用下划线
  $custom_field: "value",      // 避免 $ 前缀
  reg_dt: "2025-01-15",        // 避免缩写
  vip: true,                   // 应为 is_vip
  purchases: 15                // 应为 total_purchase_count
}
```

### 6. 控制用户属性数量

虽然 Sensors Wave 支持大量用户属性，但应保持属性数量合理。

**推荐做法**：
- 保持 20-50 个核心用户属性
- 定期清理不再使用的属性
- 优先选择高价值、常用的属性
- 避免将所有数据库字段都同步为用户属性

**避免的做法**：
- 创建数百个用户属性
- 保留大量历史遗留属性
- 存储冗余或可计算的属性

## 实施建议

### 事件设计注意事项

- **避免频繁变更事件语义**：事件一旦定义并开始使用，应保持语义稳定。如需修改，建议创建新事件并逐步迁移
- **区分事件和属性的职责**：不要为每个细微差异创建新事件，而应该使用属性来区分
- **考虑长期可扩展性**：设计事件时考虑未来可能的扩展需求，避免过度具体化

### 属性设计注意事项

**事件属性**：
- **避免属性值膨胀**：某些属性（如 `page_url`、`product_id`）可能有数万个不同的值，这会影响分析性能。考虑使用分类或分组减少基数
- **时区一致性**：确保所有时间类型的属性使用统一的时区（建议使用 UTC）
- **空值处理**：明确定义如何处理缺失值或空值，避免混用 `null`、空字符串、`undefined` 等

**用户属性**：
- **更新时机要合理**：确保用户属性在正确的时机更新，避免数据不一致
  - (推荐) 在购买事件后立即更新购买次数和消费金额
  - (不推荐) 延迟数小时或数天才更新用户属性
- **选择正确的更新操作**：
  - 使用 `setOnceUserProfile` 设置注册时间等不变属性
  - 使用 `incrementUserProfile` 累加购买次数、消费金额等
  - 使用 `appendUserProfile` 追加浏览历史、兴趣标签等
  - 不要对累加类属性使用 `setUserProfile`，会导致数据覆盖
- **避免属性语义冲突**：
  - 不要使用 `total_orders`（总订单数）和 `order_count`（订单计数）这样语义重复的属性
  - 确保属性命名清晰，避免歧义

### 数据质量监控

- **建立异常监控**：监控事件上报量、属性完整性等指标，及时发现异常
- **定期数据审计**：定期检查数据质量，识别不规范的事件和属性
- **版本管理**：对于 SDK 升级或埋点代码变更，建立版本管理和回滚机制

## 相关文档

- [数据模型](data-model.mdx)：了解事件、事件属性和用户属性在整体数据模型中的位置和作用
- [属性数据类型](property-data-types.mdx)：了解 Sensors Wave 支持的属性数据类型及使用规范
- [预置事件和预置属性](preset-events-and-properties.mdx)：了解 Sensors Wave 自动采集的预置事件和预置属性
- [埋点方案选择](tracking-strategy.mdx)：选择合适的埋点方式

---

**最后更新时间**：2026 年 1 月 22 日