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

v2.4.2

Published

3 months 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, // 先不启用
});

// 在用户授权后启用埋点
function onUserAuthorized() {
  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()

启用埋点上报。

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 | 否 | 用户登录 ID | | unionId | string | 否 | 微信 unionId | | openId | string | 否 | 微信 openId | | phone | number \| string | 否 | 手机号 | | email | string | 否 | 邮箱 | | user | string | 否 | 用户名 | | memberId | number \| string | 否 | 会员 ID | | gender | string | 否 | 性别 | | yearOfBirth | string | 否 | 出生年份 | | birthday | string | 否 | 生日 |

示例：

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

setUserUniqueId(openId)

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

参数：

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

使用场景：

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

示例：

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

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

注意：

建议在获取到用户唯一标识信息后尽早调用此方法
如果不调用此方法，deviceId 将始终是客户端随机生成的 UUID
一旦调用此方法，后续的 deviceId 都会使用设置的用户 ID

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）

工作流程

未设置唯一标识：根据缓存配置决定是否缓存事件
设置唯一标识：自动批量上报缓存事件，后续直接上报

使用场景

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

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条
});

// 用户未设置唯一标识时，事件会缓存到本地，不会上报
track.sendCustomEvent('page_view', { page: 'login' });
track.sendCustomEvent('button_click', { button: 'login_btn' });
track.sendOrderInfo({ orderID: 'order_123', totalFee: 99.9 });

// 用户设置唯一标识
// 此时会自动批量上报所有缓存的事件，然后清除缓存
await track.setUserUniqueId('user_openid_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方法会显示警告并且不生效
track.setUserUniqueId('user_openid_123');
// 控制台输出警告：未启用唯一标识上报机制(enableUniqueId: false)，setUserUniqueId() 方法不生效，将继续使用随机生成的 UUID 作为 deviceId

错误配置示例

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, // 设置了缓存数量（不生效）
});
// 控制台输出警告：未启用唯一标识上报机制(enableUniqueId: false)，enableLocalCache 和 maxCacheSize 配置不生效

缓存机制特性

先进先出：当缓存超过最大数量时，自动移除最早的事件
数量限制：最大缓存 100 条，超出时使用默认值
智能判断：根据配置和用户状态自动选择缓存或直接上报
批量上报：一次性上报所有缓存事件，提高性能
自动清理：上报成功后自动清除本地缓存

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() 方法会显示警告并且不生效
  - enableLocalCache 和 maxCacheSize 配置会被忽略并显示警告
- enableLocalCache 为 false 时，事件会直接上报，不会缓存
- 缓存最大数量限制为 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 参数说明

预置事件

预置属性

最近一次广告信息特性

注意事项