Title: 快速开始
Locale: zh
URL: https://sensorswave.com/docs/getting-started/quick-start/
Description: 5 分钟快速集成 Sensors Wave SDK，开始数据采集
Sensors Wave（简称 Wave）帮助您快速集成数据埋点，开始收集用户行为数据。本指南将从创建数据流开始，逐步引导您完成 SDK 安装、初始化、埋点启用，最后验证数据接入的全过程。

## 前提条件

在开始之前，请确保您已经：
- 拥有 Sensors Wave 账号并已登录
- 已创建相关组织和对应的项目

## 概述

完整的快速开始流程包括 5 个步骤：

1. **创建导入数据流**：在数据流模块创建导入数据流配置
2. **获取 SDK 配置代码**：从数据流详情中获取自动生成的配置代码
3. **安装并初始化 SDK**：按照提供的代码完成 SDK 安装和初始化
4. **启用埋点和用户识别**：开启自动埋点并调用 identify 方法识别用户
5. **验证数据接入**：在实时数据流中查看采集的数据

## 步骤1：创建导入数据流

在开始集成 SDK 之前，您需要先在 Sensors Wave 控制台创建一个导入数据流。数据流是数据采集和上报的通道，不同的 SDK 类型需要创建对应的数据流。

### 操作步骤

1. 登录 Sensors Wave 控制台
2. 进入「数据中心」→「数据流」模块
3. 点击「创建数据流」按钮
4. 选择「导入数据流」类型
5. 填写基本信息：
   - **任务名称**：输入有意义的名称，例如"Web 前端埋点"
   - **任务描述**：简要说明该数据流的用途（可选）
   - **SDK 类型**：选择对应埋点语言的 SDK 类型
6. 点击「确定」完成创建

> **提示**：每种 SDK 都需要创建一个独立的数据流，如果有多个 APP 需要接入同一个项目，同一个 SDK 类型也可以创建多个数据流。

## 步骤2：获取 SDK 配置代码

创建数据流后，系统会自动生成包含 Source Token 和 API Endpoint 的配置代码，您可以直接复制使用。

### 操作步骤

1. 在数据流列表中，找到刚创建的数据流
2. 点击数据流名称进入详情页
3. 在「SDK 集成指南」区域，查看自动生成的安装和初始化代码
4. 代码中已经包含：
   - **Source Token**：用于标识您的项目
   - **API Endpoint**：数据上报地址

> **说明**：系统生成的代码已经预填充了正确的配置参数，您可以直接复制使用，无需手动配置 Token 和 Endpoint。

## 步骤3：安装并初始化 SDK

本指南以 JavaScript SDK 为例演示完整流程。如需集成其他语言的 SDK，请参考对应的 [SDK 文档](/docs/data-integration)。

### 安装 SDK

根据您选择的 SDK 类型，使用相应的包管理器安装：

**JavaScript**

```bash
# 使用 npm
npm install @sensorswave/js-sdk

# 或使用 yarn
yarn add @sensorswave/js-sdk
```

**Go**

```bash
go get github.com/sensorswave/sdk-go
```

**Android**

```gradle
dependencies {
    implementation 'com.sensorswave:android-sdk:latest.release'
}
```

**iOS**

```ruby
pod 'SensorsWave'
```

### 初始化 SDK

将数据流详情页中生成的代码复制到您的项目中。以下是不同语言的初始化示例：

**JavaScript - ES6 模块导入（推荐）**

```javascript

// 初始化 SDK（使用数据流详情页提供的 Token 和 Endpoint）
SensorsWave.init('YOUR_SOURCE_TOKEN', {
  apiHost: 'https://your-api-endpoint.com',  // 自动填充的数据上报地址
  debug: false,
  autoCapture: false,
});
```

**JavaScript - CDN 引入**

```html

  SensorsWave.init('YOUR_SOURCE_TOKEN', {
    apiHost: 'https://your-api-endpoint.com',  // 自动填充的数据上报地址
    debug: false,
    autoCapture: false,
  });

```

**Go**

```go
package main

    "log"
    "github.com/sensorswave/sdk-go"
)

func main() {
    // 使用数据流详情页提供的配置初始化
    client, err := sensorswave.New(
        sensorswave.Endpoint("https://your-api-endpoint.com"),
        sensorswave.SourceToken("YOUR_SOURCE_TOKEN"),
    )
    if err != nil {
        log.Fatal(err)
    }
    defer client.Close()
}
```

**Android**

```java
// 在 Application 类的 onCreate 方法中初始化
SensorsWave.init(this, new SensorsWaveConfig.Builder()
    .setSourceToken("YOUR_SOURCE_TOKEN")
    .setApiHost("https://your-api-endpoint.com")
    .setAutoCapture(false)
    .build());
```

**iOS**

```swift
// 在 AppDelegate 中初始化
let config = SensorsWaveConfig(
    sourceToken: "YOUR_SOURCE_TOKEN",
    apiHost: "https://your-api-endpoint.com"
)
SensorsWave.initialize(with: config)
```

> **重要提示**：请务必使用数据流详情页中生成的实际 Token 和 Endpoint，上述示例中的占位符需要替换为真实值。

## 步骤4：启用埋点和用户识别

完成 SDK 初始化后，您需要调用 `identify` 方法来识别用户身份。此外，如果您使用的是客户端 SDK，我们推荐开启自动埋点功能，以便更快速地采集数据。

### 开启自动埋点（可选，推荐）

自动埋点可以帮助您自动采集页面浏览、点击等常见用户行为，无需手动编写埋点代码。客户端 SDK 默认不开启自动埋点，您可以通过设置 `autoCapture: true` 来启用。

> **推荐**：开启自动埋点可以在不修改业务代码的情况下，自动采集预置事件（如页面浏览、元素点击等），帮助您快速完成基础数据采集。

> **说明**：自动埋点功能仅客户端 SDK（JavaScript、Android、iOS 等）支持。服务端 SDK（Go、Python、Java 等）不支持自动埋点，需使用手动埋点方式。

**JavaScript 示例**

```javascript
// 开启自动埋点
SensorsWave.init('YOUR_SOURCE_TOKEN', {
  apiHost: 'https://your-api-endpoint.com',
  autoCapture: true,  // 开启自动埋点
});
```

**Android 示例**

```java
SensorsWave.init(this, new SensorsWaveConfig.Builder()
    .setSourceToken("YOUR_SOURCE_TOKEN")
    .setApiHost("https://your-api-endpoint.com")
    .setAutoCapture(true)  // 开启自动埋点
    .build());
```

**iOS 示例**

```swift
let config = SensorsWaveConfig(
    sourceToken: "YOUR_SOURCE_TOKEN",
    apiHost: "https://your-api-endpoint.com"
)
config.autoCapture = true  // 开启自动埋点
SensorsWave.initialize(with: config)
```

### 识别用户身份

Sensors Wave 通过两种 ID 来识别用户：

- **匿名 ID（AnonymousID）**：在用户未登录时自动采集，通常是设备标识符
- **登录 ID（LoginID）**：在用户登录后需要主动设置，用于关联用户身份

当用户登录时，需要调用 `identify` 方法设置登录 ID：

**JavaScript 示例**

```javascript
// 用户登录时进行身份关联
const loginID = "user_12345";
SensorsWave.identify(loginID);
```

**Go 示例**

```go
// 设置用户身份
client.Identify("user_12345", nil)
```

**Android 示例**

```java
// 用户登录时调用
SensorsWave.identify("user_12345");
```

**iOS 示例**

```swift
// 用户登录时调用
SensorsWave.identify("user_12345")
```

> **提示**：`identify` 方法会将登录 ID 与当前设备的匿名 ID 进行绑定，实现单个设备上登录前后用户行为追踪或者跨设备的用户行为追踪，详情参考[用户识别](/docs/data-integration/user-identification)。

### 自定义事件追踪（可选）

除了自动埋点，您也可以手动追踪特定的业务事件：

**JavaScript 示例**

```javascript
// 追踪按钮点击行为
SensorsWave.trackEvent('ButtonClick', {
  button_name: 'submit',
  page: 'home',
  category: 'user_action'
});

// 电商场景：追踪商品加入购物车
SensorsWave.trackEvent('AddToCart', {
  product_id: 'SKU-12345',
  product_name: '无线蓝牙耳机',
  category: '电子产品',
  price: 299.00,
  currency: 'CNY',
  quantity: 1
});
```

**Go 示例**

```go
// 追踪订单完成事件
client.Track("user_12345", "Purchase", map[string]interface{}{
    "order_id":       "ORDER-2026-001",
    "total_amount":   299.00,
    "currency":       "CNY",
    "payment_method": "alipay",
    "item_count":     1,
})
```

## 步骤5：验证数据接入

完成上述配置后，您可以在数据流模块中查看实时数据，验证数据是否正确接入。

### 操作步骤

1. 返回 Sensors Wave 控制台
2. 进入「数据中心」→「数据流」
3. 找到之前创建的导入数据流，点击进入详情页
4. 点击「查看实时数据流」按钮
5. 点击「开始监听」按钮
6. 在您的应用中执行一些操作（如页面浏览、点击按钮、用户登录等）
7. 查看实时数据流中是否出现对应的事件数据

### 验证要点

- **事件名称**：确认事件名称符合预期（如 `PageView`、`ButtonClick`、`AddToCart` 等）
- **事件属性**：检查事件属性是否完整准确
- **用户 ID**：验证匿名 ID 和登录 ID 是否正确关联
- **数据时效性**：数据通常在 1-2 秒内显示在实时数据流中

> **提示**：如果未看到数据，请检查：
> - SDK 是否正确初始化
> - Source Token 和 API Endpoint 是否配置正确
> - 网络连接是否正常
> - 浏览器控制台是否有错误信息

## 注意事项

### 安全性建议

- **Source Token 保护**：Source Token 是敏感信息，不要在公开代码仓库或前端代码中暴露
- **环境变量**：建议使用环境变量或配置文件来管理 Source Token 和 API Endpoint
- **HTTPS**：确保所有数据上报都通过 HTTPS 加密传输

### 埋点规范

- **事件命名**：使用 PascalCase 命名事件，如 `UserLogin`、`AddToCart`、`PageView` 等
- **属性命名**：使用 snake_case 命名属性，如 `user_id`、`product_name`、`page_url` 等
- **避免重复**：相同的业务行为应该使用同一个事件名称，避免创建重复的事件

### 性能考虑

- **事件发送频率**：避免在短时间内发送大量事件，可能导致网络阻塞
- **批量发送**：大多数 SDK 支持批量发送事件，可以提高发送效率
- **异步处理**：客户端 SDK 默认异步发送数据，不会阻塞主线程

### 常见问题

**Q：为什么看不到实时数据？**

A：请检查以下几点：
- SDK 是否正确初始化
- Source Token 和 API Endpoint 是否配置正确
- 网络连接是否正常
- 浏览器控制台是否有错误信息
- 数据流是否已创建且处于正常状态

**Q：匿名 ID 和登录 ID 的区别是什么？**

A：
- 匿名 ID：用于未登录状态的用户追踪，自动采集，通常是设备标识
- 登录 ID：用于已登录用户的身份识别，需要手动设置，关联用户账户信息

**Q：如何在多个 SDK 之间共享用户身份？**

A：在各个 SDK（客户端、服务端）中使用相同的登录 ID，系统会自动进行身份关联和归并。

## 下一步

恭喜！您已经成功完成了 Sensors Wave SDK 的基本集成和配置。现在您可以：

### 进阶功能

1. **自定义事件追踪**：针对您业务特有的行为创建自定义事件进行追踪，获取更精准的业务数据

2. **用户属性设置**：为用户添加自定义属性（如用户等级、会员状态等），以便进行更精准的用户分析

3. **数据洞察分析**：使用数据洞察功能对采集到的数据进行多维度分析，了解用户行为模式

4. **A/B 实验**：基于采集的数据创建 A/B 实验，验证产品优化方案的效果

5. **查看更多 SDK 文档**：了解如何在其他应用类型（移动端、后端服务等）中集成 Sensors Wave SDK

### 相关资源

- **[数据接入准备](data-integration-preparation.mdx)**：了解完整的数据接入方案和最佳实践
- **[SDK 文档](../data-integration/client-sdks/javascript.mdx)**：查看详细的 JavaScript SDK 文档
- **[埋点规范](../data-integration/tracking-strategy.mdx)**：了解埋点命名规范和设计原则
- **[数据洞察](../analytics/overview.mdx)**：学习如何使用分析功能挖掘数据价值

---

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