Title: 埋点方案选择
Locale: zh
URL: https://sensorswave.com/docs/data-integration/tracking-strategy/
Description: 选择合适的埋点方案：客户端埋点、服务端埋点或混合埋点
选择合适的埋点方案是数据采集成功的关键。本文档将帮助您了解服务端埋点和客户端埋点的优劣，并根据业务需求做出明智的选择。

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

埋点方案的选择直接影响：
- **数据质量**：不同方案的数据完整性差异可达 30-50%
- **维护成本**：跨平台一致性和代码维护的复杂度
- **业务洞察**：能否准确捕获关键业务指标
- **长期扩展**：随业务增长的可扩展性

## 我们的推荐

> **最佳实践**：优先使用服务端埋点追踪所有可能的事件，仅在必要时使用客户端埋点作为补充。

**核心原因**：
- 服务端埋点数据可靠性接近 100%，而客户端可能因广告拦截器丢失 30-50% 的数据
- 服务端埋点易于维护，代码集中管理，修复问题无需等待客户端更新
- 服务端埋点跨平台一致，避免 Web、iOS、Android 等平台的实现差异

## 两种埋点方案对比

### 服务端埋点

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

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

**限制**
- (劣势) **无法直接捕获 UI 交互**：无法记录点击、滑动、页面停留时间等前端行为
- (劣势) **匿名用户追踪复杂**：需要额外的会话管理和 Cookie/Token 传递机制

**适用场景**
- 电商平台：订单创建、支付成功、退款等核心交易事件
- SaaS 应用：用户注册、订阅购买、功能使用等关键业务逻辑
- 金融应用：转账、投资、理财等涉及资金的重要操作

**代码示例（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",
    })
}
```

### 客户端埋点

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

**优势**
- (优势) **UI 交互捕获全面**：能够记录点击、浏览、滑动、页面停留时间等详细的用户行为
- (优势) **匿名用户支持良好**：天然适配未登录用户的行为跟踪需求
- (优势) **实时性优秀**：事件发生时即可采集和发送，延迟极低

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

**适用场景**
- 内容平台：文章阅读时长、视频播放进度、内容分享等行为分析
- 电商平台：商品浏览、加入购物车、价格对比等用户意图分析
- 移动应用：页面访问路径、功能使用频率、UI 交互热力图等用户体验研究

**代码示例（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)
    });
});
```

## 方案对比表格

| 对比维度 | 服务端埋点 | 客户端埋点 |
|---------|-----------|-----------|
| **数据可靠性** | (优势) 接近 100%，不受广告拦截器影响 | (劣势) 可能丢失 30-50% 数据 |
| **跨平台一致性** | (优势) 一次实现，所有平台统一 | (劣势) 需要为每个平台分别开发 |
| **维护成本** | (优势) 集中管理，修复立即生效 | (劣势) 需要等待客户端更新 |
| **UI 交互捕获** | (劣势) 无法直接捕获前端交互 | (优势) 可以记录点击、滑动等行为 |
| **匿名用户追踪** | (劣势) 需要额外的会话管理 | (优势) 天然支持匿名用户 |
| **数据安全性** | (优势) 敏感数据不暴露在客户端 | (劣势) 数据在客户端可见 |
| **实时性** | (劣势) 依赖服务端请求 | (优势) 事件即时发送 |
| **适用场景** | 订单、支付、注册等核心业务 | 页面浏览、点击、停留时间等 |

## 如何选择？

### 决策流程

按照以下问题依次判断：

1. **这个事件是否涉及关键业务逻辑？**（如订单、支付、注册）
   - 是 → **使用服务端埋点**
   - 否 → 继续下一步

2. **这个事件是否需要捕获 UI 交互行为？**（如点击、滑动、页面停留）
   - 是 → **使用客户端埋点**
   - 否 → 继续下一步

3. **能否容忍 30-50% 的数据丢失？**
   - 可以 → **使用客户端埋点**
   - 不可以 → **使用服务端埋点**

### 推荐的混合方案

大多数企业级应用采用**服务端 + 客户端混合架构**：

| 事件类型 | 推荐方案 | 示例 |
|---------|---------|------|
| **核心业务事件** | 服务端埋点 | 用户注册、订单创建、支付成功、退款 |
| **用户行为事件** | 客户端埋点 | 页面浏览、按钮点击、商品加购、视频播放 |
| **系统事件** | 服务端埋点 | 错误日志、性能监控、API 调用 |

## 实施建议

### 1. 渐进式部署策略

建议采用最小可行产品（MVP）模式：
- **第一阶段**：实现 2-3 个核心业务事件（如注册、购买），使用服务端埋点
- **第二阶段**：验证数据质量，确认事件属性准确性
- **第三阶段**：逐步扩展埋点覆盖范围，补充客户端行为数据

### 2. 数据质量保障

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

### 3. 跨团队协作

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

## 注意事项

- **数据隐私合规**：确保埋点方案符合 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 年 1 月 19 日