Title: 埋点方案选择
Locale: zh
URL: https://sensorswave.cn/docs/data-integration/tracking-strategy/
Description: 选择合适的埋点方案：客户端埋点、服务端埋点或混合埋点
选择合适的埋点方案是数据采集成功的关键。本文档帮助您了解客户端埋点和服务端埋点各自的优势与局限，根据业务需求为每个事件选择最合适的采集方式。

## 为什么埋点方案选择很重要？

埋点方案的选择直接影响：
- **数据质量**：不同方案的数据完整性存在显著差异
- **维护成本**：跨平台一致性和代码维护的复杂度
- **业务洞察**：能否同时准确捕获用户行为和业务指标
- **长期扩展**：随业务增长的可扩展性

## 两种埋点方案对比

### 客户端埋点

客户端埋点是在用户的设备或浏览器中生成事件并发送到 Sensors Wave。例如，当用户点击「加入购物车」按钮时，JavaScript SDK 可以立即记录一个 `AddToCart` 事件。

客户端埋点是**采集用户交互行为的必要手段**——点击、页面浏览、滚动、导航路径等行为只发生在浏览器或 App 中，服务端无法感知。

**优势**
- (优势) **UI 交互捕获全面**：能够记录点击、浏览、滑动、页面停留时间等详细的用户行为，这些行为在服务端不可见
- (优势) **匿名用户支持良好**：天然适配未登录用户的行为跟踪需求
- (优势) **设备上下文丰富**：自动采集设备类型、屏幕分辨率、浏览器版本、来源渠道等客户端环境信息
- (优势) **实时性优秀**：事件发生时即可采集和发送，延迟极低

**限制**
- (劣势) **数据丢失风险**：广告拦截器、浏览器隐私设置可能导致数据无法发送
- (劣势) **跨平台维护复杂**：Web、iOS、Android 等平台需要分别集成 SDK 并维护
- (劣势) **版本管理困难**：历史版本应用的埋点逻辑难以统一更新，问题修复需等待用户升级

**适用场景**
- 页面浏览、按钮点击、表单交互、导航路径
- 内容互动：文章阅读时长、视频播放进度、滚动深度
- 用户意图信号：商品浏览、加入购物车、搜索关键词、价格对比
- 登录前行为：着陆页交互、引导流程

**代码示例（JavaScript）**

```javascript
// 用户点击「加入购物车」按钮时，在客户端记录事件
document.getElementById('add-to-cart-btn').addEventListener('click', function() {
    sensorswave.trackEvent('AddToCart', {
        product_id: 'SKU-12345',
        product_name: '无线蓝牙耳机',
        category: '电子产品',
        price: 299.00,
        currency: 'CNY',
        from_page: 'product_detail'
    });
});

// 追踪页面停留时间
let pageStartTime = Date.now();
window.addEventListener('beforeunload', function() {
    const duration = Date.now() - pageStartTime;
    sensorswave.trackEvent('PageView', {
        page_url: window.location.href,
        duration_seconds: Math.floor(duration / 1000)
    });
});
```

### 服务端埋点

服务端埋点是在您的应用服务器上发送事件数据到 Sensors Wave。例如，当用户完成支付时，您的支付服务处理逻辑中可以创建一个 `Purchase` 事件并发送到 Sensors Wave。

服务端埋点**适用于业务关键事件**，这类事件对数据准确性要求极高，且自然发生在后端业务逻辑中。

**优势**
- (优势) **数据可靠性高**：不受广告拦截器或客户端环境影响，数据从服务端直接发送，送达率接近 100%
- (优势) **跨平台一致性**：一次实现，所有平台（Web、iOS、Android）数据格式统一
- (优势) **易于维护**：集中式代码管理，问题修复立即生效，无需等待客户端更新
- (优势) **安全性更好**：敏感数据（如支付金额、订单信息）不暴露在客户端

**限制**
- (劣势) **无法捕获 UI 交互**：无法记录点击、滑动、页面停留时间等前端行为
- (劣势) **匿名用户追踪复杂**：需要额外的会话管理和 Cookie/Token 传递机制
- (劣势) **设备上下文有限**：无法直接获取屏幕分辨率、浏览器版本等客户端环境信息

**适用场景**
- 核心交易：订单创建、支付成功、退款、订阅变更
- 账户生命周期：用户注册、登录、资料更新、账户注销
- 后端操作：API 调用、数据导出、权限变更
- 金融操作：转账、投资、计费

**代码示例（Go）**

```go
// 用户完成支付后，在服务端记录事件
func handlePaymentSuccess(orderID string, userID string, amount float64) {
    user := sensorswave.User{
        LoginID: userID,
    }

    client.TrackEvent(user, "Purchase", sensorswave.Properties{
        "order_id":       orderID,
        "total_amount":   amount,
        "currency":       "CNY",
        "payment_method": "alipay",
    })
}
```

## 方案对比表格

| 对比维度 | 客户端埋点 | 服务端埋点 |
|---------|-----------|-----------|
| **数据可靠性** | (劣势) 可能被广告拦截器或隐私工具阻断 | (优势) 送达率接近 100%，不受客户端环境影响 |
| **UI 交互捕获** | (优势) 可以记录点击、滚动、导航等行为 | (劣势) 无法感知前端交互 |
| **匿名用户追踪** | (优势) 天然支持匿名用户 | (劣势) 需要额外的会话管理 |
| **设备上下文** | (优势) 采集设备、浏览器、屏幕、来源渠道等信息 | (劣势) 无法直接获取客户端环境信息 |
| **跨平台一致性** | (劣势) 需要为每个平台分别实现 | (优势) 一次实现，所有平台统一 |
| **维护成本** | (劣势) 需要等待客户端更新 | (优势) 集中管理，修复立即生效 |
| **数据安全性** | (劣势) 数据在客户端可见 | (优势) 敏感数据保留在服务端 |
| **实时性** | (优势) 事件即时发送 | 取决于服务端处理事件的时机 |

## 如何选择？

### 核心原则

大多数应用**同时需要**客户端埋点和服务端埋点。问题不是「选哪个」，而是「每个事件应该用哪种方式采集」。

- **只能在客户端观测到的事件**（点击、页面浏览、滚动）→ 使用客户端埋点
- **只能在服务端观测到的事件**（后端处理、定时任务、第三方回调）→ 使用服务端埋点
- **客户端和服务端都可以采集的事件**（如表单提交同时触发客户端事件和服务端 API 调用）→ **推荐使用服务端埋点**，数据可靠性更高

### 决策流程

针对每个需要追踪的事件，按照以下问题判断：

1. **这个事件是否涉及 UI 交互行为？**（如点击、页面浏览、滚动、导航）
   - 是 → **使用客户端埋点**

2. **这个事件是否纯粹发生在服务端？**（如后端处理、Webhook、定时任务）
   - 是 → **使用服务端埋点**

3. **这个事件是否可以在客户端和服务端都进行采集？**（如表单提交、完成购买）
   - 是 → **推荐使用服务端埋点**，数据可靠性更高
   - 如果还需要捕获周边的 UI 上下文（如点击了哪个按钮、提交前在页面停留多久），可以补充一个客户端事件

### 推荐的混合方案

大多数应用采用**客户端 + 服务端混合架构**，让每种方案发挥各自的优势：

| 事件类型 | 推荐方案 | 示例 |
|---------|---------|------|
| **用户行为事件** | 客户端埋点 | 页面浏览、按钮点击、滚动、导航路径、搜索关键词 |
| **核心业务事件** | 服务端埋点 | 用户注册、订单创建、支付成功、退款 |
| **系统事件** | 服务端埋点 | 错误日志、性能监控、API 调用 |
| **两端均可采集的事件** | 推荐服务端 | 表单提交、功能激活、结算完成 |

## 实施建议

### 1. 从关键事件开始

识别对业务分析最重要的事件，然后为每个事件选择合适的方案：
- **优先客户端**：如果主要目标是理解用户行为、优化用户体验，优先为关键页面浏览和交互实施客户端埋点
- **优先服务端**：如果主要目标是追踪业务指标（收入、转化、订阅），优先为核心交易事件实施服务端埋点
- **两端并行**：大多数团队受益于在两端同时实施若干高价值事件

### 2. 渐进式扩展

采用渐进式部署策略：
- **第一阶段**：实现 5-10 个关键事件，为每个事件选择最合适的方案
- **第二阶段**：验证数据质量，确认事件属性准确性
- **第三阶段**：根据分析需求逐步扩展埋点覆盖范围

### 3. 数据质量保障

建立完整的数据验证体系：
- **实施前**：制定数据质量标准和验收标准
- **实施中**：在开发环境验证事件格式和属性完整性
- **实施后**：定期检查数据上报情况，确认数据完整性

### 4. 跨团队协作

明确不同团队的埋点职责：
- **后端团队**：负责服务端埋点实施和维护
- **前端/客户端团队**：负责客户端埋点实施和维护
- **数据团队**：负责数据质量监控和需求收集
- **产品团队**：负责定义需要追踪的业务事件

## 注意事项

- **数据隐私合规**：确保埋点方案符合 GDPR、CCPA 等数据隐私保护法规，在采集前获得用户同意
- **性能影响**：客户端埋点过多可能影响应用性能，建议：
  - 使用事件批量发送而非逐个发送
  - 避免在关键渲染路径中添加埋点代码
  - 对埋点代码进行性能测试和优化
- **版本兼容性**：客户端埋点需考虑历史版本兼容问题，制定版本升级和废弃策略
- **数据一致性**：确保服务端和客户端埋点的事件命名、属性定义保持一致

## 其他集成方式

除了直接使用 SDK，您还可以通过以下方式将数据发送到 Sensors Wave：

### CDP / Tag Manager 集成
如果您已经使用 CDP（客户数据平台）或 Tag Manager，可以通过集成将事件路由到 Sensors Wave：
- **Segment**：通过 Segment 集成，统一管理多个分析工具
- **Google Tag Manager**：使用 GTM 管理和部署追踪代码
- **其他 CDP**：RudderStack、mParticle 等

### 数据仓库集成
如果您的数据已经存储在数据仓库中，Sensors Wave 可以直接从仓库加载数据：
- **Snowflake**：从 Snowflake 导入历史数据和批量数据
- **BigQuery**：从 Google BigQuery 同步数据
- **其他仓库**：Redshift、ClickHouse 等

> **提示**：这些集成方式适合已有数据基础设施的企业，可以减少重复开发工作。

## 下一步

完成埋点方案选型后，建议按以下顺序进行实施：

1. **[集成 SDK](sdks/javascript.mdx)**：根据选定的埋点方案集成相应的 Sensors Wave SDK
2. **[用户标识管理](user-identification.mdx)**：建立用户身份识别和关联机制
3. **[数据模型设计](data-model.mdx)**：构建标准化的事件和属性数据结构
4. **[事件和属性](events-and-properties.mdx)**：了解如何设计和管理事件和属性信息

---

**最后更新时间**：2026 年 4 月 14 日