@eclicktech/mp-sdk/README.md

The Eclicktech Funsdata of MiniProgram SDK, suport echat, Alipay, TikTok

# FunsData Analytics 小程序 SDK

## 上报参数

1. app_id 您的项目的 app_id，可通过在项目产品页面获取
2. 上报地址 ：your_serviceurl

## 一、集成 SDK

安装命令：

```javascript
pnpm add @eclicktech/mp-sdk
```

将 analytics.wx.js 文件导入

```javascript
const analytics = require("miniprogram_npm/@eclicktech/mp-sdk/analytics.wx");
```

在 project.config.json 中需要确认：

```javascript
"miniprogramRoot": "./",
"setting": {
  "nodeModules": true,
  "packNpmRelationList": [
      {
          "packageJsonPath": "./package.json",
          "miniprogramNpmDistDir": "./miniprogram_npm"
      }
  ],
}
```

## 二、配置 SDK

引入 SDK 之后，您就可以创建 SDK 实例，开始上报数据了：

```javascript
import analytics from "../../mp_sdk/build/analytics.wx";
// 初始化配置
var config = {
  appId: "your-app-id", // 项目的 App ID（必填）
  serverUrl: "https://your.serverurl.com", // 数据上报地址（必填）
  autoTrack: {
    // 自动追踪配置（可选）
    appShow: true, // 自动追踪应用显示事件
    appHide: true, // 自动追踪应用隐藏事件
    appLaunch: true, // 自动追踪应用启动事件
    pageShow: true, // 自动追踪页面显示事件
    pageLeave: true, // 自动追踪页面离开事件
    mpClick: true, // 自动追踪小程序点击事件
    pageShare: true, // 自动追踪页面分享事件
    mpFavorite: true, // 自动追踪小程序收藏事件
    properties: {}, // 自动追踪事件的公共属性
    callback: function (eventType) {
      // 自动追踪事件回调
      return {}; // 返回额外属性
    }
  },
  enableLog: true, // 启用日志打印（可选）
  debugMode: "none", // 调试模式：'none', 'debug', 'debugOnly'
  strict: true, // 严格模式，验证参数格式
  disablePresetProperties: [], // 禁用的预置属性列表
  zoneOffset: 8 // 时区偏移量
};

analytics.init(config);

Page({
  data: {},
  onReady: function () {
    // 初始化
  },
  // 设置访客 ID, 对应上报数据中的 #distinct_id
  identify: function () {
    analytics.setDistinctId("your_own_anonymous_id");
  },
  // 设置账号 ID，对应上报数据里的 #account_id
  login: function () {
    analytics.login("ABC_123456");
  },
  // 去除上报数据里的 #account_id 字段
  logout: function () {
    analytics.logout();
  },
  // 设置公共事件属性
  setSuperProperties: function () {
    analytics.setSuperProperties({ channel: "渠道" });
  },
  // 上报事件
  track: function () {
    analytics.track(
      "Purchase", //追踪事件的名称
      {
        Item: "商品A",
        ItemNum: 1,
        Cost: 100
      } //需要上传的事件属性
    );
  }
});
```

## 三、发送事件

### 3.1 普通事件追踪 - track

```javascript
// 基础调用方式
Analytics.track(
  {
    eventName: "product_buy", // 事件名称，必填
    properties: {
      // 事件属性，可选
      product_name: "钻石",
      price: 100
    },
    time: new Date(), // 事件时间，可选
    onComplete: function (result) {
      // 回调函数，可选
      console.log("事件上报结果:", result);
    }
  },
  "appId"
); // appId 可选
```

### 3.2 首次事件追踪 - trackFirst

```javascript
Analytics.trackFirst({
  eventName: "first_login",
  firstCheckId: "device_id", // 首次检查ID，默认为设备ID
  properties: { channel: "wechat" },
  time: new Date(),
  onComplete: callback
});
```

### 3.3 可更新事件追踪 - trackUpdate

```javascript
Analytics.trackUpdate({
  eventName: "game_level",
  eventId: "unique_event_id", // 事件ID，必填
  properties: { level: 5 },
  time: new Date(),
  onComplete: callback
});
```

### 3.4 可覆写事件追踪 - trackOverwrite

```javascript
Analytics.trackOverwrite({
  eventName: "user_profile",
  eventId: "profile_update_id", // 事件ID，必填
  properties: { age: 25 },
  time: new Date(),
  onComplete: callback
});
```

## 四、用户属性

### 4.1 设置用户属性 - userSet

```javascript
Analytics.userSet({
  properties: {
    // 用户属性，必填
    username: "tiki",
    age: 25,
    vip_level: "gold"
  },
  time: new Date(), // 时间，可选
  onComplete: callback // 回调，可选
});
```

### 4.2 设置用户属性（仅首次） - userSetOnce

```javascript
// 如果属性已存在，则忽略新值
Analytics.userSetOnce({
  properties: {
    first_login_time: new Date(),
    register_channel: "wechat"
  }
});
```

### 4.3 数值类型用户属性累加 - userAdd

```javascript
Analytics.userAdd({
  properties: {
    total_purchase: 100, // 累加购买金额
    login_count: 1 // 累加登录次数
  },
  time: new Date(),
  onComplete: callback
});
```

### 4.4 重置用户属性 - userUnset

```javascript
Analytics.userUnset({
  property: "temp_data", // 要重置的属性名
  time: new Date(),
  onComplete: callback
});
```

### 4.5 删除用户 - userDel

```javascript
// 删除用户数据，不可逆操作，请谨慎使用
Analytics.userDel({
  time: new Date(),
  onComplete: callback
});
```

### 4.6 追加列表类型用户属性 - userAppend

```javascript
Analytics.userAppend({
  properties: {
    favorite_games: ["game1", "game2"] // 追加到列表
  }
});
```

### 4.7 去重追加列表属性 - userUniqAppend

```javascript
Analytics.userUniqAppend({
  properties: {
    visited_pages: ["home", "profile"] // 去重后追加
  }
});
```

### 4.8 用户身份管理

```javascript
// 设置访客ID
Analytics.setDistinctId("unique_visitor_id");

// 用户登录
Analytics.login("user_account_id");

// 用户登出
Analytics.logout();
```

## 五、公共属性设置

### 5.1 设置公共事件属性

设置后，所有事件都会包含这些属性：

```javascript
Analytics.setSuperProperties({
  channel: "wechat",
  app_version: "1.0.0"
});
```

### 5.2 设置动态公共属性

每次上报事件时，动态获取最新值：

```javascript
Analytics.setDynamicSuperProperties(function () {
  return {
    current_time: new Date().getTime(),
    network_type: getCurrentNetworkType()
  };
});
```

## 六、其他重要方法

### 6.1 设置事件上报状态

控制事件上报行为：

| 状态值      | 说明               |
| ----------- | ------------------ |
| `NORMAL`    | 正常上报           |
| `PAUSE`     | 暂停上报           |
| `STOP`      | 停止上报并清除缓存 |
| `SAVE_ONLY` | 仅保存不上报       |

```javascript
Analytics.setTrackStatus("NORMAL");
```

### 6.2 立即上报缓存数据

立即尝试上报缓存队列中的数据：

```javascript
Analytics.flush();
```

### 6.3 用户登录 / 登出

```javascript
// 用户登录
Analytics.login("user_account_id");

// 用户登出
Analytics.logout();
```

---

## 七、自动采集事件

### 7.1 自动采集配置

```javascript
autoTrack: {
  appLaunch: true,      // 自动采集应用启动事件 ta_mp_launch
  appShow: true,        // 自动采集应用显示事件 ta_mp_show
  appHide: true,        // 自动采集应用隐藏事件 ta_mp_hide
  pageShow: true,       // 自动采集页面浏览事件 ta_mp_view
  pageLeave: true,      // 自动采集页面离开事件 ta_page_leave
  pageShare: true,      // 自动采集页面分享事件 ta_mp_share
  mpClick: true,        // 自动采集小程序点击事件 ta_mp_click
  mpFavorite: true,     // 自动采集小程序收藏事件 ta_add_favorite
  properties: {},       // 自动采集事件的公共属性
  callback: function(eventType) {
    // 自动采集事件回调，返回额外属性
    return {};
  }
}
```

```javascript
import analytics from "../../mp_sdk/build/analytics.wx";
var config = {
  appId: "your_app_id", // 项目的 APP ID
  serverUrl: "https://deapi.adsgreat.cn/v1/wechat/report/json", // 数据上报地址
  autoTrack: {
    appLaunch: true, // 自动采集 ta_mp_launch
    appShow: true, // 自动采集 ta_mp_show
    appHide: true, // 自动采集 ta_mp_hide
    pageShow: true, // 自动采集 ta_mp_view
    pageShare: true // 自动采集 ta_mp_share
  }
};
analytics.init(config);

Page({
  data: {},
  onReady: function () {
    // 初始化
  },
  // 设置访客 ID, 对应上报数据中的 #distinct_id
  identify: function () {
    analytics.setDistinctId("your_own_anonymous_id");
  },
  // 设置账号 ID，对应上报数据里的 #account_id
  login: function () {
    analytics.login("ABC_123456");
  },
  // 去除上报数据里的 #account_id 字段
  logout: function () {
    analytics.logout();
  },
  // 设置公共事件属性
  setSuperProperties: function () {
    analytics.setSuperProperties({ channel: "渠道" });
  },
  // 上报事件
  track: function () {
    analytics.track(
      "Purchase", //追踪事件的名称
      {
        Item: "商品A",
        ItemNum: 1,
        Cost: 100
      } //需要上传的事件属性
    );
  }
});
```

### 7.2 属性说明

#### 7.2.1 通用属性

- **#url_path**  
  通过 `getCurrentPages()` 获取当前页面路径。
- **#scene**  
  从小程序启动参数中获取场景值（微信提供的场景值）。

- **#utm**  
  从 URL query 参数中解析 UTM 营销参数。

- **#start_reason**  
  小程序启动参数的 JSON 字符串。

#### 7.2.2 时长相关属性

- **#duration**  
  通过 `timeEvent()` 方法计算的事件持续时间（秒）。
  - 应用隐藏事件会计算**应用使用时长**。
  - 页面离开事件会计算**页面停留时长**。

#### 7.2.3 元素相关属性（点击事件）

| 属性名               | 数据来源                        |
| -------------------- | ------------------------------- |
| **#element_id**      | `currentTarget.id`              |
| **#element_type**    | `currentTarget.dataset.type`    |
| **#element_content** | `currentTarget.dataset.content` |
| **#element_name**    | `currentTarget.dataset.name`    |

---

### 7.3 采集事件

#### 7.3.1 小程序初始化

| 项目             | 说明                                                                   |
| ---------------- | ---------------------------------------------------------------------- |
| **事件名**       | `ta_mp_launch`                                                         |
| **触发时机**     | 首次打开小程序，或用户杀死进程后重新启动；整个进程生命周期仅触发一次。 |
| **自动采集属性** | `#scene`：场景值，取自微信提供的场景值。                               |
| **典型分析场景** | 计算每日使用次数、人均使用次数；按场景值分组查看不同场景的使用情况。   |

#### 7.3.2 小程序启动

| 项目             | 说明                                                        |
| ---------------- | ----------------------------------------------------------- |
| **事件名**       | `ta_mp_show`                                                |
| **触发时机**     | 小程序启动，或从后台调回前台。                              |
| **自动采集属性** | - `#scene`：场景值<br>- `#url_path`：启动后展示页面的路径。 |
| **典型分析场景** | 在行为路径中标记一次使用起点，作为用户行为路径的初始行为。  |

#### 7.3.3 小程序隐藏

| 项目             | 说明                                                                      |
| ---------------- | ------------------------------------------------------------------------- |
| **事件名**       | `ta_mp_hide`                                                              |
| **触发时机**     | 小程序被调入后台。                                                        |
| **自动采集属性** | - `#scene`：场景值<br>- `#duration`：本次启动到隐藏的**持续时长（秒）**。 |
| **典型分析场景** | 计算总使用时长、人均时长；除以初始化次数可得单次使用时长。                |

#### 7.3.4 小程序页面浏览

| 项目             | 说明                                                                                                         |
| ---------------- | ------------------------------------------------------------------------------------------------------------ |
| **事件名**       | `ta_mp_view`                                                                                                 |
| **触发时机**     | 页面打开，或从后台调回前台时页面重新展示。                                                                   |
| **自动采集属性** | - `#scene`：场景值<br>- `#url_path`：被展示页面的路径<br>- `#referrer`：前向路径，若首页打开则为“直接打开”。 |
| **典型分析场景** | 计算各页面 PV/UV；分析用户访问路径。                                                                         |

#### 7.3.5 小程序页面转发分享

| 项目             | 说明                                                        |
| ---------------- | ----------------------------------------------------------- |
| **事件名**       | `ta_mp_share`                                               |
| **触发时机**     | 点击转发按钮（右上角导航栏按钮或页面内按钮）。              |
| **自动采集属性** | - `#scene`：场景值<br>- `#url_path`：转发时所在的页面路径。 |
| **典型分析场景** | 分析页面分享率，优化转发功能。                              |

#### 7.3.6 小程序页面卸载

| 项目             | 说明                                                                   |
| ---------------- | ---------------------------------------------------------------------- |
| **事件名**       | `ta_page_leave`                                                        |
| **触发时机**     | 页面卸载（例如跳转到其他页面）。                                       |
| **自动采集属性** | - `#duration`：页面停留时长（秒）<br>- `#url_path`：卸载时的页面路径。 |

#### 7.3.7 小程序页面收藏

| 项目             | 说明                            |
| ---------------- | ------------------------------- |
| **事件名**       | `ta_add_favorite`               |
| **触发时机**     | 页面被收藏。                    |
| **自动采集属性** | `#url_path`：被收藏页面的路径。 |

以下是将表格内容转换为 Markdown 格式后的结果：

### 系统预置字段

#### 核心标识字段

| 字段名       | 简介                                  | 示例值                        |
| ------------ | ------------------------------------- | ----------------------------- |
| #distinct_id | 访客唯一标识，UUID 自动生成或手动设置 | 1234-5678-9012-3456-789012345 |
| #account_id  | 用户账户 ID，登录时设置               | user_123456                   |
| #device_id   | 设备唯一标识                          | device_abc123                 |

#### 设备信息字段

| 字段名         | 简介             | 示例值                  |
| -------------- | ---------------- | ----------------------- |
| #os            | 操作系统类型     | iOS, Android            |
| #os_version    | 操作系统版本     | 14.5, 11.0              |
| #device_model  | 设备型号         | iPhone 12, Xiaomi Mi 11 |
| #manufacturer  | 设备制造商       | Apple, Xiaomi           |
| #screen_width  | 屏幕宽度（像素） | 375, 414                |
| #screen_height | 屏幕高度（像素） | 812, 896                |
| #network_type  | 网络连接类型     | wifi, 4g, 3g            |

#### 自动收集的数据

| 字段名           | 简介                            | 示例值             |
| ---------------- | ------------------------------- | ------------------ |
| #device_id       | 设备唯一标识符（UUID 生成）     | abc123-def456-789  |
| #device_model    | 设备型号                        | iPhone 8           |
| #manufacturer    | 设备制造商                      | Apple              |
| #screen_width    | 屏幕宽度（像素）                | 375                |
| #screen_height   | 屏幕高度（像素）                | 667                |
| #os              | 操作系统名称                    | iOS、Android       |
| #os_version      | 操作系统版本号                  | 14.5、11.0         |
| #system_language | 系统语言                        | zh-CN、en-US       |
| #network_type    | 当前网络类型（wifi、4g、3g 等） | wifi、4g、3g       |
| #lib             | SDK 名称                        | FunsData Analytics |
| #lib_version     | SDK 版本号                      | 1.0.0              |
| #mp_platform     | 小程序平台名称                  | wechat_mp          |
| #app_version     | 小程序版本号                    | 2.3.1              |
| #zone_offset     | 时区偏移量                      | +8                 |

---

**微信`SDK`文件位置**: `@eclicktech/mp-sdk/build/analytics.wx.js`
**详细使用指南**: https://janzlz0n1f.feishu.cn/wiki/PGKqwsWGWikAXokH5rvcOqtKnGd