Title: 微信小程序 SDK
Locale: zh
URL: https://sensorswave.com/docs/data-integration/client-sdks/wechatMini/
Description: 微信小程序 SDK 集成指南和 API 参考
Sensors Wave 微信小程序 SDK 是专为微信小程序设计的数据采集和 A/B 测试工具，帮助您轻松实现用户行为分析、漏斗分析、留存分析等功能。

## 核心功能

微信小程序 SDK 提供以下核心能力：

- **事件追踪**：手动追踪自定义事件和用户行为
- **自动埋点**：自动采集小程序生命周期、页面浏览、分享、点击等事件
- **用户识别**：支持匿名用户和登录用户身份关联
- **用户属性管理**：完整的用户属性操作（设置、追加、增量更新等）
- **A/B 测试集成**：支持功能开关（Feature Gate）和实验变量获取
- **批量发送**：优化网络请求性能，每 5 秒批量发送最多 10 个事件
- **公共属性**：支持静态和动态公共属性，自动附加到所有事件
- **设备信息采集**：自动采集设备品牌、型号、网络类型等预置属性

## 安装

### NPM 安装

```bash
npm install @sensorswave/wechat-mini
```

## 快速开始

### 基础初始化

在小程序的 `app.js` 中初始化 SDK：

```javascript
// app.js

// 初始化 SDK
Sensorswave.init('YOUR_SOURCE_TOKEN', {
  apiHost: 'https://your-api-endpoint.com',  // 数据上报地址
  debug: false,                               // 调试模式
  autoCapture: true                           // 开启自动埋点
});
```

### 发送第一个事件

初始化完成后，您可以在任意页面中上报事件：

```javascript
// pages/index/index.js

Page({
  handleButtonClick() {
    // 追踪用户点击按钮
    Sensorswave.trackEvent('ButtonClick', {
      button_name: 'submit',
      page: 'home'
    });
  }
});
```

## 配置选项

`init` 方法的第二个参数是配置对象，支持以下选项：

| 配置项 | 类型 | 默认值 | 说明 |
|--------|------|--------|------|
| `apiHost` | `string` | `''` | **必填**，数据上报的 API 地址，您可以在 Pipeline 中查看 |
| `debug` | `boolean` | `false` | 是否开启调试模式，开启后在控制台输出详细日志 |
| `autoCapture` | `boolean` | `true` | 是否开启自动埋点，自动采集小程序生命周期和页面事件 |
| `enableClickTrack` | `boolean` | `false` | 是否开启点击自动追踪（追踪主要的可点击元素） |
| `batchSend` | `boolean` | `true` | 是否使用批量发送，每 5 秒批量发送最多 10 个事件 |
| `enableAB` | `boolean` | `false` | 是否开启 A/B 测试功能 |
| `abRefreshInterval` | `number` | `600000` | A/B 测试配置刷新间隔（毫秒），默认 10 分钟 |

### 完整配置示例

```javascript
// app.js

Sensorswave.init('YOUR_SOURCE_TOKEN', {
  apiHost: 'https://your-api-endpoint.com',
  debug: false,                          // 开发环境关闭调试
  autoCapture: true,                    // 开启自动埋点
  enableClickTrack: true,               // 开启点击追踪
  batchSend: true,                      // 批量发送优化性能
  enableAB: true,                       // 开启 A/B 测试
  abRefreshInterval: 10 * 60 * 1000     // A/B 测试数据每 10 分钟刷新
});
```

> **提示**：在生产环境中建议关闭 `debug` 模式，以避免在控制台输出过多日志。

## API 方法

### 事件追踪

#### trackEvent - 追踪自定义事件

手动追踪自定义事件及其属性。

**参数**：
- `eventName` (string，必填)：事件名称
- `properties` (Object，可选)：事件属性，键值对形式

**示例**：

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

**实际场景示例**：

```javascript
// 电商场景：用户浏览商品
Sensorswave.trackEvent('ProductView', {
  product_id: '12345',
  product_name: '无线蓝牙耳机',
  category: '电子产品',
  price: 299.00,
  currency: 'CNY'
});

// 电商场景：用户加入购物车
Sensorswave.trackEvent('AddToCart', {
  product_id: '12345',
  quantity: 1,
  price: 299.00
});

// 内容平台：文章阅读
Sensorswave.trackEvent('ArticleRead', {
  article_id: 'article_001',
  title: '微信小程序性能优化技巧',
  category: '技术博客',
  read_duration: 120  // 阅读时长（秒）
});
```

#### track - 高级事件追踪

发送完整的事件对象，支持更精细的控制。此方法允许您手动指定所有事件字段。

**参数**：
- `eventData` (SensorswaveSendEvent，必填)：完整事件对象，包含以下字段：
  - `event` (string，必填)：事件名称
  - `properties` (Object，可选)：事件属性
  - `time` (number，必填)：时间戳（毫秒）
  - `trace_id` (string，必填)：请求追踪 ID
  - `anon_id` (string，可选)：匿名用户 ID
  - `login_id` (string，可选)：登录用户 ID。login_id 和 anon_id 必须传一个，同时传递时，优先使用 login_id
  - `user_properties` (Object，可选)：用户属性操作

**示例**：

```javascript
Sensorswave.track({
  event: 'UserSignup',
  properties: {
    signup_method: 'wechat',
    referral_code: 'FRIEND2024'
  },
  time: Date.now(),
  trace_id: 'signup_67890',
  anon_id: 'anonymous-user-id',
  login_id: 'user_12345',
  user_properties: {
    $set: {
      signup_date: new Date().toISOString(),
      referral_source: 'friend'
    },
    $set_once: {
      initial_campaign: 'spring_2024'
    }
  }
});
```

> **注意**：`track` 方法是高级功能，大多数场景下使用 `trackEvent` 即可满足需求。

### 用户识别

#### identify - 设置登录用户 ID

设置登录用户 ID 并发送绑定事件，将匿名行为与已识别用户关联。

**参数**：
- `loginId` (string | number，必填)：用户的唯一标识符（如用户 ID、手机号、邮箱）

**示例**：

```javascript
// 用户登录后设置用户 ID
Sensorswave.identify('user_12345');
```

**完整登录流程示例**：

```javascript
// 用户登录流程
function handleUserLogin(code) {
  // 调用登录 API
  wx.request({
    url: 'https://your-api.com/login',
    method: 'POST',
    data: { code },
    success: (res) => {
      const { userId } = res.data;

      // 设置用户 ID 并关联匿名行为
      Sensorswave.identify(userId);
    },
    fail: (error) => {
      console.error('登录失败:', error);
    }
  });
}
```

> **重要提醒**：如果 `loginId` 包含隐私信息（如手机号、邮箱、身份证号等），请务必在加密后再进行传输，避免敏感信息明文上报。

#### setLoginId - 仅设置登录 ID

设置登录用户 ID，但不发送绑定事件。如果您只想识别用户但不需要关联用户，可以使用此方法。

**参数**：
- `loginId` (string | number，必填)：用户的唯一标识符

**示例**：

```javascript
Sensorswave.setLoginId('user_12345');
```

> **重要提醒**：如果 `loginId` 包含隐私信息（如手机号、邮箱、身份证号等），请务必在加密后再进行传输，避免敏感信息明文上报。

> **使用建议**：通常情况下推荐使用 `identify` 方法，因为它会记录用户身份关联事件，有助于后续分析。

#### getLoginId - 获取当前登录 ID

获取当前已识别用户的登录 ID。

**返回值**：string | number

**示例**：

```javascript
const loginId = Sensorswave.getLoginId();
console.log('当前登录 ID:', loginId);
```

#### getAnonId - 获取匿名 ID

获取当前用户的匿名 ID。此 ID 是自动生成的，并在会话之间保持持久化。

**返回值**：string

**示例**：

```javascript
const anonId = Sensorswave.getAnonId();
console.log('匿名用户 ID:', anonId);
```

### 用户属性

用户属性用于描述用户的特征，如会员等级、注册时间、偏好设置等。与事件属性不同，用户属性会持久化保存并与用户关联。

#### profileSet - 设置用户属性

设置用户属性，如果属性已存在则覆盖。

**参数**：
- `properties` (Object，必填)：要设置的用户属性

**示例**：

```javascript
// 用户完成注册后，设置用户属性
Sensorswave.profileSet({
  name: '张三',
  age: 30,
  plan: 'premium',
  city: '北京'
});
```

#### profileSetOnce - 仅首次设置

设置用户属性，仅在属性不存在时设置，已存在的属性不会被覆盖。

**参数**：
- `properties` (Object，必填)：要设置的用户属性

**示例**：

```javascript
// 记录用户首次访问信息（仅记录一次，后续不会覆盖）
Sensorswave.profileSetOnce({
  first_visit_date: '2024-01-15',
  initial_referrer: 'search',
  initial_campaign: 'spring_sale'
});
```

#### profileIncrement - 增量更新数值属性

对数值类型的用户属性进行增减操作。仅支持数值属性。

**参数**：
- `properties` (Object，必填)：要增减的属性及其数值

**示例**：

```javascript
// 增加单个属性
Sensorswave.profileIncrement({
  login_count: 1
});

// 增加多个属性
Sensorswave.profileIncrement({
  login_count: 1,
  points_earned: 100,
  purchases_count: 1
});
```

#### profileAppend - 追加到数组属性

向数组类型的用户属性追加新值，不进行去重。

**参数**：
- `properties` (Object，必填)：要追加的属性及其数组值

**示例**：

```javascript
Sensorswave.profileAppend({
  categories_viewed: ['电子产品', '手机配件'],
  tags: ['新用户', '2024年第一季度']
});
```

#### profileUnion - 追加到集合属性（去重）

向数组类型的用户属性追加新值，自动去重。

**参数**：
- `properties` (Object，必填)：要追加的属性及其数组值

**示例**：

```javascript
// 第一次调用
Sensorswave.profileUnion({
  interests: ['科技', '游戏']
});

// 第二次调用，'科技' 不会重复添加
Sensorswave.profileUnion({
  interests: ['科技', '音乐']  // 只会增加 '音乐'
});
```

#### profileUnset - 删除指定属性

将指定的用户属性设置为 null。

**参数**：
- `propertyNames` (string[]，必填)：要置为 null 的属性名数组

**示例**：

```javascript
// 删除单个属性
Sensorswave.profileUnset(['temporary_campaign']);

// 删除多个属性
Sensorswave.profileUnset(['old_plan', 'expired_flag', 'temp_id']);
```

#### profileDelete - 删除所有用户属性

删除当前用户的所有用户属性数据。此操作不可撤销。

**示例**：

```javascript
// 用户注销账号时，删除所有用户属性
Sensorswave.profileDelete();
```

> **警告**：`profileDelete` 会删除所有用户属性，请谨慎使用。

#### 用户属性使用示例

**会员升级场景**：

```javascript
function handleMembershipUpgrade(newPlan) {
  // 更新会员等级和升级时间
  Sensorswave.profileSet({
    plan: newPlan,
    upgrade_time: new Date().toISOString()
  });

  // 增加升级次数
  Sensorswave.profileIncrement({
    upgrade_count: 1
  });

  // 追踪升级事件
  Sensorswave.trackEvent('MembershipUpgrade', {
    from_plan: 'basic',
    to_plan: newPlan
  });
}
```

### 公共属性

公共属性会自动添加到所有事件中，适用于需要在每个事件中都包含的通用信息。支持静态属性（字符串值）和动态属性（函数返回值）。

#### registerCommonProperties - 注册公共属性

注册静态或动态公共属性，这些属性将自动包含在所有事件中。

**参数**：
- `properties` (Record，必填)：要注册的属性
  - 静态属性：字符串、数字、布尔值
  - 动态属性：函数（每次发送事件时调用）

**示例**：

```javascript
Sensorswave.registerCommonProperties({
  // 静态属性
  app_version: '1.0.0',
  environment: 'production',

  // 动态属性（每次发送事件时调用）
  current_time: () => new Date().toISOString(),
  user_session_id: () => getSessionId()
});
```

#### clearCommonProperties - 清除公共属性

移除指定的已注册公共属性。如果不提供参数，将清除所有公共属性。

**参数**：
- `propertyNames` (string[]，可选)：要移除的属性名数组

**示例**：

```javascript
// 清除指定属性
Sensorswave.clearCommonProperties(['app_version', 'user_session_id']);

// 清除所有公共属性
Sensorswave.clearCommonProperties();
```

> **注意**：公共属性会增加每个事件的数据量，建议仅添加确实需要的通用属性。

### A/B 测试

微信小程序 SDK 内置了 A/B 测试支持，可以获取功能开关状态和实验变量。

#### 开启 A/B 测试功能

```javascript
Sensorswave.init('YOUR_SOURCE_TOKEN', {
  apiHost: 'https://your-api-endpoint.com',
  enableAB: true,                       // 开启 A/B 测试
  abRefreshInterval: 10 * 60 * 1000     // 配置刷新间隔（10 分钟）
});
```

#### checkFeatureGate - 检查功能开关

检查功能开关（Feature Flag）是否为当前用户启用。返回 Promise，解析为布尔值。

**参数**：
- `key` (string，必填)：功能开关的 Key

**返回值**：Promise

**示例**：

```javascript
// 检查功能是否启用
Sensorswave.checkFeatureGate('new_checkout_flow')
  .then(isEnabled => {
    if (isEnabled) {
      // 显示新功能
      this.setData({ showNewCheckout: true });
    } else {
      // 显示旧功能
      this.setData({ showNewCheckout: false });
    }
  });

// 使用 async/await
async function initFeature() {
  const isEnabled = await Sensorswave.checkFeatureGate('advanced_search');
  if (isEnabled) {
    this.setData({ enableAdvancedSearch: true });
  }
}
```

#### getExperiment - 获取实验变量

获取当前用户的实验变量数据。返回 Promise，解析为实验配置对象。

**参数**：
- `key` (string，必填)：实验的 Key

**返回值**：Promise

返回的对象包含实验的变量配置值（Record）。

**示例**：

```javascript
// 获取实验配置
Sensorswave.getExperiment('homepage_layout')
  .then(experiment => {
    if (experiment) {
      // 应用实验配置
      this.setData({
        layoutType: experiment.layout_type
      });
    }
  });

// 使用 async/await
async function initExperiment() {
  const experiment = await Sensorswave.getExperiment('pricing_display');
  if (experiment) {
    const { price_format, discount_type } = experiment;
    this.setData({
      priceFormat: price_format,
      discountType: discount_type
    });
  }
}
```

**完整 A/B 测试示例**：

```javascript
// 电商首页 CTA 按钮 A/B 测试
Page({
  data: {
    buttonText: '立即购买',
    buttonColor: '#ff6600'
  },

  async onLoad() {
    try {
      const experiment = await Sensorswave.getExperiment('homepage_cta_test');

      if (experiment) {
        const { button_text, button_color, button_size } = experiment;

        this.setData({
          buttonText: button_text || '立即购买',
          buttonColor: button_color || '#ff6600',
          buttonSize: button_size || '16px'
        });
      }
    } catch (error) {
      console.error('获取实验变量失败:', error);
      // 使用默认配置
    }
  }
});
```

> **提示**：A/B 测试功能需要在 Sensors Wave 后台配置实验和功能开关后才能使用。

## 自动埋点

开启自动埋点后，SDK 会自动采集以下事件类型：

| 事件名称 | 说明 | 触发时机 |
|---------|------|---------|
| `$MPLaunch` | 小程序启动 | 小程序初始化完成（App.onLaunch） |
| `$MPShow` | 小程序显示 | 小程序进入前台（App.onShow） |
| `$MPHide` | 小程序进入后台 | 小程序切换到后台（App.onHide） |
| `$MPPageView` | 小程序页面浏览 | 页面加载完成（Page.onShow） |
| `$MPPageLeave` | 小程序页面离开 | 页面卸载或切换（Page.onHide） |
| `$MPShare` | 小程序分享 | 调用分享功能（onShareAppMessage） |
| `$MPClick` | 小程序元素点击 | 点击可交互元素（需开启 `enableClickTrack`） |

### $MPClick 事件详情

当 `enableClickTrack` 开启时，SDK 会自动捕获元素点击事件。**重要说明：**

- **仅追踪绑定了事件处理函数的元素** — SDK 代理 Page/Component 的事件函数，因此元素必须绑定了 `bindtap`/`catchtap`（或类似）处理函数才会被捕获
- **支持的事件类型**：`tap`、`longtap`、`longpress`

```xml

提交

无事件处理函数
```

### 开启自动埋点

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

### 自动埋点使用场景

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

> **提示**：自动埋点功能可以大幅减少手动编码工作量，但会增加一定的数据量。建议根据实际需求选择性开启。

## 注意事项

### 性能优化

- 避免在循环中频繁调用 `trackEvent`，建议合并事件或使用节流
- 批量发送功能默认已开启，可有效减少网络请求
- 自动埋点会增加一定性能开销，仅在需要时开启
- 注意小程序的存储容量限制（10MB）

### 数据安全

- 不要在事件属性中传递敏感信息（如密码、身份证号、完整手机号）
- Source Token 应妥善保管，避免在公开代码仓库中暴露
- 确保数据上报地址已在微信公众平台配置了合法域名

### 平台限制

- **网络请求域名白名单**：确保数据上报地址已在小程序后台配置
- **request 最大并发数**：微信小程序对并发请求数有限制，批量发送功能已考虑此限制
- **用户隐私保护**：遵守微信小程序用户隐私保护规范，获取必要的用户授权

### 数据丢失风险

- 客户端埋点可能受网络环境影响导致数据丢失
- 核心业务数据建议使用服务端埋点，详见 [埋点方案选择](../tracking-strategy.mdx)

## 调试模式

开启调试模式后，SDK 会在控制台输出详细日志：

```javascript
Sensorswave.init('YOUR_SOURCE_TOKEN', {
  apiHost: 'https://your-api-endpoint.com',
  debug: true  // 开启调试模式
});
```

调试日志会输出：
- SDK 初始化信息
- 事件追踪信息
- 错误信息

## 常见问题

### 为什么我的数据没有上报成功？

检查以下几点：

1. **Source Token 是否正确**：确认 `sourceToken` 参数是否正确
2. **数据上报地址是否正确**：确认 `apiHost` 配置是否正确
3. **网络域名白名单**：确认数据上报地址已在小程序后台配置
4. **网络连接**：查看控制台是否有网络请求错误
5. **调试模式**：开启 `debug: true` 查看控制台日志

## 相关文档

- [埋点方案选择](../tracking-strategy.mdx)：了解服务端埋点和客户端埋点的优劣
- [如何正确的标识用户](../user-identification.mdx)：用户身份识别的最佳实践
- [数据模型](../data-model.mdx)：理解 Sensors Wave 的数据结构
- [事件和属性](../events-and-properties.mdx)：事件设计规范和最佳实践
- [预置事件和预置属性](../preset-events-and-properties.mdx)：查看所有预置事件和属性的详细说明

---

**最后更新时间**：2026 年 4 月 7 日
**许可证**：Apache-2.0