微信小程序埋点上报工具 WxTrack 完全指南
一个功能全面、使用简便的微信小程序埋点上报插件，支持元素点击自动埋点、函数调用埋点、滚动曝光埋点、页面访问埋点等多种埋点方式，让你的小程序数据分析能力提升一个档次！
📌 猛戳 GitHub 查看完整代码
项目介绍
WxTrack 是为微信小程序量身定制的埋点SDK，它能够帮助开发者轻松实现以下功能：
- 元素点击自动埋点，无需手动在每个点击事件中添加埋点代码
- 页面访问埋点，自动追踪用户进出页面行为
- 函数调用埋点，监控关键业务函数执行
- 视图区域曝光埋点，追踪内容展示情况
- 丰富的用户属性设置功能，满足个性化分析需求
- 兼容插件模式，适应各种小程序开发场景
目录结构
├── _tests_ # 单元测试
├── dist # 打包文件
│ ├── wxtrack-es.js # ES 模块文件
│ ├── wxtrack.min.js # 通用模块化
├── src # 源代码
│ ├── helper.js # 页面操作
│ ├── report.js # 埋点数据操作
│ ├── wrapper.js # Page/App对象操作
│ ├── index.js # 入口文件
├── .gitignore # git的忽略配置文件
├── package.json # npm 包配置文件，依赖包信息
├── .babelrc # babel 配置
├── rollup.config.js # rollup 配置
├── README.md # SDK介绍
使用指南
1. 安装引入
从 GitHub 下载源码，将 dist 目录下的文件复制到你的项目中。
2. 在 app.js 中初始化
// 引入埋点SDK
import Tracker from './tracks/wxtrack.min';
// 引入埋点配置信息，请自行参考tracks目录下埋点配置修改
import { eventConfig } from './tracks/config.js';
// 初始化
const report = new Tracker({
tracks: eventConfig, // 埋点配置
base_url: 'https://xxxxxx', // 上报接口地址
appid: 'xxxxxx', // 小程序appid
appkey: 'xxxxxx', // 小程序appkey
debug: '0' // 是否开启调试模式，1-开启，0-关闭
});
// 小程序需要设置openid
getToken() {
// 请求接口后设置
// ...
report.openid = openid || '' // 设置openid作为埋点用户唯一标识
}
// 导出report，方便其他页面使用
report() {
return report
}
3. 配置埋点信息
在 tracks/config.js 文件中配置埋点信息：
/**
* 埋点配置说明:
* path: 页面路径
* elementTracks: 页面元素埋点
* - element: 目标元素选择器
* - eventName: 上报事件名称
* - dataKeys: 目标埋点数据,传数组第一个参数为页面元素定义的数据data-xxx，第二个参数为上传参数，非数组默认传data
* methodTracks: 执行函数埋点
* - method: 函数名
* - eventName: 上报事件名称
* - dataKeys: 目标埋点数据
*
* 注意: 如果配置了元素获取埋点，则需要最外层包裹view并加上方法catchtap="elementTracker"
*/
export const eventConfig = [
{
path: 'pages/newHome/newHome',
elementTracks: [
{
element: '.banner',
eventName: 'bannertest',
dataKeys: ['imgUrls', ['$dataset.src', 'url_var']],
}
],
methodTracks: [
{
method: 'goToAd',
eventName: 'bannertest',
dataKeys: ['data'],
}
],
}
]
4. 在页面WXML中添加埋点监听
为了使元素点击埋点生效，需要在页面最外层添加监听方法：
<view catchtap='elementTracker'>
<!-- 页面内容 -->
<view class="banner" data-src="banner1.jpg">Banner 1</view>
<view class="banner" data-src="banner2.jpg">Banner 2</view>
</view>
5. 单独使用埋点上报
除了自动埋点外，你还可以在任何地方手动调用埋点上报：
// 简单上报埋点数据
report.track("点击banner图", { banner_id: "123", position: "home" })
// 链式调用，上报用户属性
report.userSetOnce({"address":"井湾子街道"}) // 只设置一次，已有值时忽略
.userSet({ name_test:"张三", age:18 }) // 设置/覆盖用户属性
.userUnset("name_test") // 清空指定用户属性
.userAdd({age:1}) // 数值属性累加操作
.trackUserData() // 最终上报
6. 滚动视图区域曝光埋点
监控用户滚动时元素进入视图区域的曝光事件：
// 页面js头部引入方法并初始化
const report = getApp().report()
Page({
data: {
listData: []
},
onLoad() {
// 加载数据后初始化监听
this.getListData().then(() => {
this.initObserver(this.data.listData);
})
// 初始化监听
report.initObserver()
},
/**
* 初始化监听元素
* 在接口返回数据并渲染后调用
*/
initObserver(data) {
report.delObserver() // 断开之前的监听
data.forEach(item => {
// 参数1: 元素节点选择器
// 参数2: 上报事件名称
// 参数3: 自定义上报参数
report.ElObserver('#img'+item.id, 'case_browse', {
url_var: item.oss_thumb_photo_url
})
})
},
/**
* 监听页面滚动事件，更新 IntersectionObserver 实例
*/
onPageScroll: function (e) {
this.initObserver(this.data.listData);
}
})
7. 页面进出自动埋点
监听页面跳转，自动上报页面进入和退出事件：
// 在app.js中加入以下代码
report.track("view_access") // 埋点上报，进入小程序
// 监听页面进入和退出
report.watchRoute({
pageIn: 'view_access', // 进入页面上报事件名
pageOut: 'view_address' // 离开页面上报事件名
})
8. HTML/CSS内容过滤
如果你的数据库不支持HTML和CSS，可以使用内置的过滤方法：
const content = report.filterHTMLandCSS(this.data.content)
9. 特殊前缀说明
在埋点数据中，可以使用以下特殊前缀获取数据：
$APP- 表示读取App下定义的数据$DATASET.xxx- 表示获取点击元素，定义data-xxx中的xxx值$INDEX- 表示获取列表，当前点击元素的索引
需要获取$INDEX时，需要在wxml中加入data-index={{index}}标记
<view class='playing-item' data-index="{{index}}" wx:for='{{playingFilms}}'></view>
10. 兼容插件模式
由于SDK会改写Page对象，如果使用了插件，微信会禁止改写，可以通过以下方式改造：
// 初始化插件模式
const tracker = new Tracker({
tracks: trackConfig,
isUsingPlugin: true
});
// 将原来的App包装
tracker.createApp({
// 原App对象
onLaunch() {
// 启动逻辑
}
})
// 将原Page包装
tracker.createPage({
// 原Page对象
data: {},
onLoad() {
// 页面加载逻辑
}
})
高级功能示例
1. 用户行为路径分析
通过组合使用页面埋点和元素点击埋点，可以构建完整的用户行为路径：
// 定义埋点配置
export const eventConfig = [
{
path: 'pages/home/home',
elementTracks: [
{
element: '.category-item',
eventName: 'category_click',
dataKeys: [['$dataset.id', 'category_id'], ['$dataset.name', 'category_name']],
},
{
element: '.search-bar',
eventName: 'search_click',
}
]
},
{
path: 'pages/product/detail',
elementTracks: [
{
element: '.buy-now',
eventName: 'buy_click',
dataKeys: ['productInfo'],
},
{
element: '.add-cart',
eventName: 'cart_add',
dataKeys: ['productInfo'],
}
]
}
]
2. 自定义维度分析
你可以添加自定义维度来丰富埋点数据：
// 在每次上报前添加公共属性
report.registerPreProperties({
channel: 'wx_mini',
version: '1.2.3'
})
// 设置用户动态属性
report.registerDynamicProperties(() => {
return {
timestamp: Date.now(),
network_type: getNetworkType() // 假设有获取网络类型的函数
}
})
3. A/B测试分组埋点
结合A/B测试功能，可以实现不同方案数据对比：
// 根据用户ID分配A/B测试组
const abTestGroup = report.openid.charCodeAt(0) % 2 === 0 ? 'A' : 'B';
// 设置为公共属性
report.registerPreProperties({
ab_test_group: abTestGroup
})
// 在代码中根据分组展示不同内容
if (abTestGroup === 'A') {
// 展示方案A
} else {
// 展示方案B
}
// 埋点上报时会自动带上分组信息
report.track('feature_usage', { feature_name: 'new_ui' })
性能考量
WxTrack SDK经过优化，将对小程序性能的影响降至最低：
- 采用懒加载策略，仅在需要时初始化埋点组件
- 数据上报采用批量处理和节流控制，减少网络请求
- 自动过滤敏感信息，保护用户隐私
- 支持离线缓存，在网络恢复后自动上报
结语
WxTrack 埋点SDK为微信小程序提供了完整的用户行为分析解决方案，通过简单配置就能实现全面的数据采集。无论是产品迭代优化，还是用户行为分析，都能提供有力的数据支持。
如果你在使用过程中遇到任何问题，欢迎提交 Issue 或联系作者。
别忘了给项目点个 Star ⭐，你的支持是我持续更新的动力！
作者：corn
