@shuyun-ep-team/monitor-track-weapp

v2.5.7

Published

3 days ago

微信小程序埋点SDK

0High
0Medium
0Low

weapp wechat monitor track sdk

数云微信小程序埋点 SDK

支持框架

微信原生小程序、Wepy、Uniapp、Taro、Mpvue

安装

npm install @shuyun-ep-team/monitor-track-weapp -S

基本使用

方式一：立即启用埋点（推荐）

import Track from '@shuyun-ep-team/monitor-track-weapp';

export const track = new Track();

track.init({
  reportUrl: '您的数据接收地址',
  projectID: '您创建的项目ID',
  appid: 'wx123456789',
  appname: '我的小程序',
  enableSiteMerge: true, // 启用站点合并监测
  enable: true, // 立即启用埋点
});

方式二：延迟启用埋点（适用于需要用户授权的场景）

import Track from '@shuyun-ep-team/monitor-track-weapp';

export const track = new Track();

// 先初始化但不启用埋点
track.init({
  reportUrl: '您的数据接收地址',
  projectID: '您创建的项目ID',
  appid: 'wx123456789',
  appname: '我的小程序',
  enableSiteMerge: true, // 启用站点合并监测
  enable: false, // 先不启用
});

// 在用户授权后启用埋点
async function onUserAuthorized() {
  await track.enableTracking(); // 启用埋点上报，如有待补发缓存会等待补发完成
}

// 如需禁用埋点（如用户退出登录）
function onUserLogout() {
  track.disableTracking(); // 禁用埋点上报
}

重要说明：

SDK 实例化后立即调用 init() 方法，通过 enable 参数和动态方法控制是否上报
通过 enableTracking()/disableTracking() 控制的是数据是否实际上报，而非事件监听
延迟启用埋点，建议初始化时设置 enableUtmCache:true，开启 UTM 参数缓存，防止延迟初始化导致丢失 UTM 信息

API 文档

构造函数

const track = new Track();

创建埋点 SDK 实例，会立即注册事件监听器。

init(config)

初始化 SDK 配置。

参数：

| 参数名 | 类型 | 必填 | 默认值 | 说明 | | ---------------- | ----------- | ---------------------- | ------- | ----------------------------------------------------------------------------- | | reportUrl | string | 是 | - | 数据上报地址 | | projectID | string | 是 | - | 项目 ID，由监控平台后台生成 | | appid | string | 站点合并监测模式下必填 | - | 小程序 appid，上报时转换为 _appid | | appname | string | 站点合并监测模式下必填 | - | 站点名称，只允许包含数字、字母、中文字符，上报时转换为 _appname | | enableSiteMerge | boolean | 否 | false | 是否启用站点合并监测模式，默认 false（兼容老用户） | | enable | boolean | 否 | false | 是否开启埋点上报 | | enableUtmCache | boolean | 否 | false | 是否启用 UTM 参数缓存处理 | | enableUniqueId | boolean | 否 | false | 是否使用唯一标识上报机制 | | enableLocalCache | boolean | 否 | false | 是否启用本地缓存；发送前置条件未满足时暂存事件 | | maxCacheSize | number | 否 | 100 | 本地缓存最大数量 | | framework | Framework | 否 | - | 小程序框架类型，可选值：'Native'、'Taro'、'UniApp'、'Wepy'、'Mpvue' | | ignore | object | 否 | - | 忽略上报的配置 |

Framework 类型说明：

| 枚举值 | 说明 | 对应框架 | | ---------- | -------------- | ---------- | | 'Native' | 微信原生小程序 | 原生小程序 | | 'Taro' | Taro 框架 | Taro | | 'UniApp' | Uni-app 框架 | Uni-app | | 'Wepy' | Wepy 框架 | Wepy | | 'Mpvue' | Mpvue 框架 | Mpvue |

ignore 配置：

| 参数名 | 类型 | 必填 | 默认值 | 说明 | | ------ | ---------- | ---- | ------ | -------------- | | urls | string[] | 否 | [] | 忽略的页面路径 | | errors | string[] | 否 | [] | 忽略的异常信息 | | apis | string[] | 否 | [] | 忽略的接口 |

示例：

track.init({
  reportUrl: 'https://your-api.com/track',
  projectID: 'your-project-id',
  appid: 'wx123456789',
  appname: '我的小程序',
  enableSiteMerge: true, // 启用站点合并监测
  enable: true,
  framework: 'Taro', // 指定使用的小程序框架
  ignore: {
    urls: ['/pages/debug'],
    errors: ['Script error'],
    apis: ['/api/test'],
  },
});

enableTracking()

启用埋点上报。

await track.enableTracking();

disableTracking()

禁用埋点上报。

track.disableTracking();

isEnabled()

检查当前埋点是否启用。

返回值： boolean

const enabled = track.isEnabled();
console.log('埋点状态:', enabled);

getUtmInfo()

获取当前存储的 UTM 信息。

返回值： Partial<IReferrerInfo>

const utmInfo = track.getUtmInfo();
console.log('当前 UTM 信息:', utmInfo);

setUtmInfo(utmInfo)

手动设置 UTM 信息。

参数： Partial<IReferrerInfo>

| 参数名 | 类型 | 必填 | 说明 | | ----------- | -------- | ---- | ---------- | | utmCampaign | string | 否 | 广告活动 | | utmContent | string | 否 | 广告内容 | | utmMedium | string | 否 | 广告媒介 | | utmSource | string | 否 | 广告来源 | | utmTerm | string | 否 | 广告关键词 | | scene | number | 否 | 场景值 | | sceneName | string | 否 | 场景名称 | | sceneType | string | 否 | 场景类型 |

示例：

track.setUtmInfo({
  utmSource: 'wechat',
  utmMedium: 'social',
  utmCampaign: 'spring_sale',
  utmContent: 'banner',
});

setUserInfo(profile)

设置用户属性信息。

参数：

| 参数名 | 类型 | 必填 | 说明 | | ----------- | ------------------ | ---- | ------------ | | loginId | string \| null | 否 | 用户登录 ID | | unionId | string \| null | 否 | 微信 unionId | | openId | string \| null | 否 | 微信 openId | | phone | number \| string | 否 | 手机号 | | email | string | 否 | 邮箱 | | user | string | 否 | 用户名 | | memberId | number \| string | 否 | 会员 ID | | gender | string | 否 | 性别 | | yearOfBirth | string | 否 | 出生年份 | | birthday | string | 否 | 生日 |

示例：

await track.setUserInfo({
  loginId: 'user123',
  openId: 'wx_openid_123',
  phone: '13800138000',
  gender: '男',
});

注意：

setUserInfo() 可安全 await；如本地已有待补发缓存且满足上报条件，会等待补发完成。
openId、unionId、loginId 会统一规范化：undefined、null、空字符串和纯空白字符串在没有旧有效值时上报为 null，已有旧有效值时无效输入不会覆盖。
enableUniqueId=true 且传入有效 openId 时，setUserInfo({ openId }) 也会建立 _deviceId=openId。
SDK 只维护当前最新有效用户信息，不按 openId 记录历史映射；openId 与 unionId/loginId 不自动绑定。

setUserUniqueId(openId)

设置用户唯一标识。重要：调用此方法后，所有上报数据的 deviceId 字段将使用传入的用户 ID，而不是随机生成的设备 UUID。

参数：

| 参数名 | 类型 | 必填 | 说明 | | ------ | -------- | ---- | ------------------------------------------- | | openId | string | 是 | 用户唯一标识（如微信 openId 或其他用户 ID） |

使用场景：

当需要将埋点数据与具体用户关联时
替代随机生成的设备 ID，使用业务系统中的用户标识
便于在后台系统中按用户维度分析数据

示例：

// 在获取到用户 openId 后调用
await track.setUserUniqueId('wx_user_openid_123456');

// 之后的所有上报数据的 deviceId 字段都将是 'wx_user_openid_123456'
// 而不是客户端随机生成的 UUID

注意：

建议在获取到用户唯一标识信息后尽早调用此方法
如果不调用此方法，deviceId 将始终是客户端随机生成的 UUID
一旦调用此方法，后续的 deviceId 都会使用设置的用户 ID
setUserUniqueId() 可安全 await；enableUniqueId=false、openId 无效或无缓存事件时会直接完成且不触发补发
enableUniqueId=true 时，setUserInfo({ openId }) 也会建立 _deviceId=openId，不要求必须先调用 setUserUniqueId(openId)
setUserInfo({ openId }) 与 setUserUniqueId(openId) 先后传入不同有效 openId 时，后写入者作为后续 _openId/_deviceId

sendCustomEvent(eventName, data)

发送自定义事件。

参数：

| 参数名 | 类型 | 必填 | 说明 | | --------- | -------- | ---- | ------------------------------ | | eventName | string | 是 | 事件名称（不能与预置事件重复） | | data | object | 是 | 事件数据 |

示例：

track.sendCustomEvent('button_click', {
  button_name: '购买按钮',
  page: 'product_detail',
  product_id: '12345',
});

sendOrderInfo(orderData)

发送订单事件。

参数： IOrderProfile

| 参数名 | 类型 | 必填 | 说明 | | ------------------- | --------- | ---- | -------------- | | orderID | string | 否 | 订单 ID | | totalFee | number | 否 | 订单金额 | | payment | number | 否 | 订单实付金额 | | orderDiscountAmount | number | 否 | 订单优惠金额 | | orderSource | string | 否 | 订单来源 | | sku | string | 否 | 商品 SKU | | spu | string | 否 | 商品 SPU | | totalQuantity | number | 否 | 商品购买总数量 | | freight | number | 否 | 运费 | | isUseCoupons | boolean | 否 | 是否使用优惠券 | | couponName | string | 否 | 优惠券名称 | | couponProjectId | string | 否 | 优惠券项目 ID | | couponNo | string | 否 | 优惠券券码 | | couponFee | number | 否 | 优惠券金额 | | isUsePoint | boolean | 否 | 是否使用积分 | | bonusPointsAmount | number | 否 | 积分优惠金额 | | pointsQuantity | number | 否 | 积分数量 | | receiverAddress | string | 否 | 收货地址 | | receiverProvince | string | 否 | 收货人省份 | | receiverCity | string | 否 | 收货人城市 | | receiverDistrict | string | 否 | 收货人地区 | | receiverName | string | 否 | 收货人姓名 | | receiverMobile | string | 否 | 收货人电话 | | isCashBackAmount | boolean | 否 | 是否有返现金额 | | cashBackAmount | number | 否 | 返现金额 | | VIPlevel | string | 否 | VIP 等级 | | shopCode | string | 否 | 店铺编码 | | shopName | string | 否 | 店铺名称 | | discountRate | number | 否 | 折扣率 | | isInternal | boolean | 否 | 是否是内部订单 | | orderStatus | string | 否 | 订单状态 | | description | string | 否 | 下单备注 |

示例：

track.sendOrderInfo({
  orderID: 'ORDER_123456',
  totalFee: 99.9,
  payment: 89.9,
  orderDiscountAmount: 10.0,
  sku: 'SKU001',
  totalQuantity: 2,
  isUseCoupons: true,
  couponFee: 10.0,
});

setGlobalReport(key, value)

设置全局上报数据。

参数：

| 参数名 | 类型 | 必填 | 说明 | | ------ | -------- | ---- | -------- | | key | string | 是 | 数据键名 | | value | any | 是 | 数据值 |

示例：

track.setGlobalReport('customField', {
  version: '1.0.0',
  channel: 'official',
});

唯一标识上报机制

SDK 支持基于用户唯一标识的智能上报策略

核心概念

enableUniqueId: 启用唯一标识上报机制
enableLocalCache: 启用本地事件缓存
maxCacheSize: 本地缓存最大数量（默认 100，最大不超过 100）

工作流程

发送前置条件未满足：enableLocalCache=true 时暂存事件，包括当前不允许上报、唯一 ID 模式缺有效 openId、传统模式未设置用户信息
设置唯一标识：enableUniqueId=true 时更新后续事件的 _deviceId，并可作为 _openId 来源
设置用户信息：await setUserInfo({ openId, unionId, loginId }) 会补齐已有缓存事件的 _openId、_unionId、_loginId 并补发

使用场景

场景一：不启用缓存（推荐用于对隐私要求不高的场景）

track.init({
  reportUrl: 'https://your-api.com/behavior-sense/event/receiver',
  projectID: 'your-project-id',
  appid: 'wx123456789',
  appname: '我的小程序',
  enableSiteMerge: true, // 启用站点合并监测
  enable: true,
  enableUniqueId: true, // 启用唯一标识
  enableLocalCache: false, // 不启用缓存
});

// 事件会立即上报，deviceId使用随机生成的UUID
track.sendCustomEvent('page_view', { page: 'home' });

// 用户设置唯一标识，后续事件使用openId作为deviceId
await track.setUserUniqueId('user_openid_123');

// 后续事件直接上报，deviceId为user_openid_123
track.sendCustomEvent('button_click', { button: 'purchase' });

场景二：启用缓存

track.init({
  reportUrl: 'https://your-api.com/behavior-sense/event/receiver',
  projectID: 'your-project-id',
  appid: 'wx123456789',
  appname: '我的小程序',
  enableSiteMerge: true,
  enable: true,
  enableUniqueId: true, // 启用唯一标识
  enableLocalCache: true, // 启用缓存
  maxCacheSize: 80, // 最大缓存80条
});

// enableUniqueId=true 且当前缺有效 openId 时，这个事件会暂存等待 openId
track.sendCustomEvent('page_view', { page: 'login' });

// 设置用户信息；enableUniqueId=true 且 openId 有效时，会建立 _deviceId=openId
// 如有待补发缓存事件，会带上 _openId/_unionId/_loginId 后补发
await track.setUserInfo({
  openId: 'user_openid_123',
  unionId: 'user_unionid_123',
  loginId: 'login_123',
});

// 后续事件直接上报，deviceId为user_openid_123
track.sendCustomEvent('purchase_success', { order_id: 'order_123' });

场景三：传统模式

track.init({
  reportUrl: 'https://your-api.com/behavior-sense/event/receiver',
  projectID: 'your-project-id',
  // 不传 appid 和 appname（兼容老用户）
  // enableSiteMerge 默认为 false，不强制校验
  enable: true,
  // 不设置enableUniqueId或设置为false，使用传统模式
  enableUniqueId: false,
});

// 所有事件立即上报，deviceId始终使用随机生成的UUID
track.sendCustomEvent('page_view', { page: 'home' });

// 在传统模式下调用setUserUniqueId方法会显示警告并且不生效，但可以安全 await
await track.setUserUniqueId('user_openid_123');
// 控制台输出警告：未启用唯一标识上报机制(enableUniqueId: false)，setUserUniqueId() 方法不生效，将继续使用随机生成的 UUID 作为 deviceId

// 如果本地已有待补发缓存事件，setUserInfo 仍可补发身份字段，但不会替换 _deviceId
await track.setUserInfo({
  openId: 'user_openid_123',
  unionId: 'user_unionid_123',
  loginId: 'login_123',
});

错误配置示例

track.init({
  reportUrl: 'https://your-api.com/behavior-sense/event/receiver',
  projectID: 'your-project-id',
  appid: 'wx123456789',
  appname: '我的小程序',
  enableSiteMerge: true,
  enable: true,
  enableUniqueId: false, // 未启用唯一标识
  enableLocalCache: true, // 发送前置条件未满足时暂存事件
  maxCacheSize: 50,
});
// setUserUniqueId(openId) 不生效；当前允许上报时 _deviceId 仍保持 UUID

缓存机制特性

先进先出：当缓存超过最大数量时，自动移除最早的事件
数量限制：最大缓存 100 条，超出时使用默认值
缓存范围：发送前置条件未满足时暂存事件，包括当前不允许上报、唯一 ID 模式缺有效 openId、传统模式未设置用户信息；已发起上报但发送失败的实时事件不会写入缓存
批量上报：一次性上报所有缓存事件，提高性能
批次清理：缓存批量补发一旦发起请求，无论成功或失败，本批已尝试发送的缓存都不继续保留
身份补发：已有缓存补发会写入当前规范化后的 _openId、_unionId、_loginId
deviceId 规则：enableUniqueId=true 且已有有效 openId 时，缓存补发可使用 _deviceId=openId；enableUniqueId=false 时保持缓存事件原 _deviceId
空值规范化：_openId、_unionId、_loginId 未获取到有效值时上报为 null，不会出现空字符串或纯空白字符串

UTM 缓存

SDK 支持可选的 UTM 信息缓存处理，解决延迟初始化可能导致的 UTM 信息丢失问题：

核心能力（仅在启用时生效）

提前捕获：在 App.onLaunch/App.onShow 中提取 UTM 并存储到本地
SDK 配合：初始化后主动读取存储的 UTM 并关联到事件
页面补充：新页面加载时补充当前 UTM 信息
自动清理：退出小程序时清空本地存储，不做持久化

启用 UTM 缓存

通过 enableUtmCache: true 配置启用 UTM 缓存功能（默认为 false）：

track.init({
  reportUrl: '您的数据接收地址',
  projectID: '您创建的项目ID',
  appid: 'wx123456789',
  appname: '我的小程序',
  enableSiteMerge: true,
  enable: false,
  enableUtmCache: true, // 启用 UTM 缓存
});

手动操作 UTM

// 获取当前存储的 UTM 信息
const utmInfo = track.getUtmInfo();

// 手动设置 UTM 信息
track.setUtmInfo({
  utmSource: 'google',
  utmMedium: 'cpc',
  utmCampaign: 'brand_keywords',
});

UTM 参数说明

预置事件

SDK 会自动收集以下预置事件：

| 事件名 | 说明 | 触发时机 | | ------------- | ---------- | ------------ | | _MPLaunch | 小程序启动 | App.onLaunch | | _MPAppShow | 小程序显示 | App.onShow | | _MPAppHide | 小程序隐藏 | App.onHide | | _MPPageShow | 页面显示 | Page.onShow | | _MPPageview | 页面浏览 | 页面切换时 |

预置属性

SDK 会自动收集预置属性并附加到所有事件中。除了基础的设备信息、页面信息等预置属性外，还包含以下最近一次广告信息预置属性：

| 属性名 | 说明 | 采集逻辑 | | --------------------- | ------------------------------ | ------------------ | | _latest_utmCampaign | 最近一次访问时携带的广告活动 | 长期缓存，主动更新 | | _latest_utmContent | 最近一次访问时携带的广告内容 | 长期缓存，主动更新 | | _latest_utmMedium | 最近一次访问时携带的广告媒介 | 长期缓存，主动更新 | | _latest_utmSource | 最近一次访问时携带的广告来源 | 长期缓存，主动更新 | | _latest_utmTerm | 最近一次访问时携带的广告关键词 | 长期缓存，主动更新 |

最近一次广告信息特性

自动采集：无需配置，功能自动启用
长期有效：不会主动清理数据，实现长期有效的广告归因
主动更新：当检测到新的有效 UTM 参数时立即更新存储
全量上报：所有事件都会自动携带这些最近一次广告信息

注意事项

初始化时机：建议在小程序入口文件（app.js/app.ts）中立即初始化，不要放在生命周期回调中
参数校验（enableSiteMerge）：
- 默认模式 (enableSiteMerge: false，默认)：
  - appid 和 appname 为可选参数，不传也能初始化成功
  - 适用于老项目升级，保持向后兼容
  - 如果传了参数，会自动添加到所有事件的全局数据中（转换为 _appid 和 _appname）
- 站点合并监测模式 (enableSiteMerge: true)：
  - appid 和 appname 为必填参数，缺少任一参数都会导致初始化失败
  - appname 只允许包含数字、字母、中文字符，不符合格式要求会导致初始化失败
  - 推荐多站点项目使用，按站点合并统计监测数据
事件名冲突：自定义事件名不能与预置事件名重复，否则会被忽略
隐私合规：可通过 enable: false + enableTracking() 实现用户授权后再启用埋点
唯一标识配置：
- enableUniqueId 为 false 时，调用 setUserUniqueId() 方法会显示警告并且不生效，不会替换 _deviceId、不会补 _openId、不会触发缓存补发
- setUserInfo({ openId }) 在 enableUniqueId=true 时也会建立 _deviceId=openId；与 setUserUniqueId(openId) 先后传入不同有效 openId 时，后写入者生效
- enableLocalCache 为 false 时，当前不允许上报或身份前置条件未满足的事件不会缓存
- enableLocalCache 为 true 时，发送前置条件未满足的事件会暂存：当前不允许上报、enableUniqueId=true 且缺有效 openId、enableUniqueId=false 且未设置用户信息；已发起请求但发送失败的实时事件不会写入缓存
- 传统模式下，有效 setUserInfo(profile) 指入参显式包含 openId、unionId、loginId 任一身份字段；setUserInfo({}) 或仅包含昵称等非身份字段不会释放登录前缓存
- 缓存最大数量限制为 100 条，超出时会使用默认值
批量上报：
- 缓存批量补发一旦发起请求，无论成功或失败，本批已尝试发送的缓存都不继续保留
- 补发期间新增且未进入本批请求的缓存事件会继续保留，等待下一次补发
缓存机制：
- 缓存数据存储在微信小程序本地存储中
- 小程序卸载时或手动清除缓存时数据会自动清除
- 缓存采用先进先出策略，超出数量限制时自动移除最早的事件
性能考虑：
- 启用缓存模式会增加本地存储的使用
- 批量上报最多一次性上报 100 个事件，网络请求大小适中

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

数云微信小程序埋点 SDK

支持框架

安装

基本使用

方式一：立即启用埋点（推荐）

方式二：延迟启用埋点（适用于需要用户授权的场景）

API 文档

构造函数

init(config)

enableTracking()

disableTracking()

isEnabled()

getUtmInfo()

setUtmInfo(utmInfo)

setUserInfo(profile)

setUserUniqueId(openId)

sendCustomEvent(eventName, data)

sendOrderInfo(orderData)

setGlobalReport(key, value)

唯一标识上报机制

核心概念

工作流程

使用场景

场景一：不启用缓存（推荐用于对隐私要求不高的场景）

场景二：启用缓存

场景三：传统模式

错误配置示例

缓存机制特性

UTM 缓存

核心能力（仅在启用时生效）

启用 UTM 缓存

手动操作 UTM

UTM 参数说明

预置事件

预置属性

最近一次广告信息特性

注意事项