FlashCat 小程序 RUM（Real User Monitoring）SDK，用于监控小程序的性能、错误和用户行为。
- 🚀 自动追踪：自动监控页面访问、用户交互、网络请求、错误和性能
- 📊 丰富指标：采集完整的 RUM 数据，包括页面加载时间、请求耗时等
- 🎯 灵活配置：支持采样率、功能开关、数据过滤等配置
- 💡 易于使用：类似 DataFlux 的单例导出方式，无需手动关联事件
- 📦 TypeScript：完整的类型定义支持
本仓库包含以下小程序 SDK 包：
| 包名 | npm | 说明 |
|---|---|---|
| core | @flashcatcloud/miniprogram-core |
SDK 通用核心能力，包括配置、会话、传输和批量上报 |
| miniprogram-platform | @flashcatcloud/miniprogram-platform |
小程序平台适配层，包括网络请求、生命周期和平台 API 封装 |
| miniprogram-rum | @flashcatcloud/miniprogram-rum |
小程序 RUM 入口包，业务方通常只需要安装这个包 |
npm install @flashcatcloud/miniprogram-rum安装后在微信开发者工具中点击 工具 → 构建 npm。
// app.js
const { flashcatRum } = require("@flashcatcloud/miniprogram-rum");
// 在 App() 之前初始化
flashcatRum.init({
clientToken: "your-client-token",
applicationId: "your-app-id",
// 方式一：使用默认 FlashCat 站点（推荐）
// 默认上报到：https://browser.flashcat.cloud/api/v2/rum
// 方式二：自定义站点域名
// site: 'custom.flashcat.cloud', // 上报到：https://custom.flashcat.cloud/api/v2/rum
// 方式三：通过代理转发数据
// proxy: 'https://proxy.example.com/path', // 拼接为：{proxy}?ddforward={encodedPath}
service: "my-miniprogram",
env: "production",
version: "1.0.0",
});
App({
onLaunch() {
console.log("App launched");
},
});就这么简单！SDK 会自动追踪：
- ✅ 页面访问和生命周期
- ✅ 用户交互（点击、长按等）
- ✅ 网络请求（wx.request 等）
- ✅ 错误和异常
- ✅ 性能指标
除了自动追踪，还可以手动上报业务事件：
const { flashcatRum } = require("@flashcatcloud/miniprogram-rum");
// 上报自定义事件
flashcatRum.addCustomEvent("商品购买", {
productId: "12345",
price: 99.99,
});
// 上报用户操作
flashcatRum.addAction("点击分享按钮", "share");
// 上报错误
flashcatRum.addError("加载失败", "custom");
// 上报性能指标
flashcatRum.addTiming("数据加载完成", 1500);
// 设置用户信息
flashcatRum.setUser({
id: "user-123",
name: "Zhang San",
});
// 设置全局上下文
flashcatRum.setGlobalContext({
platform: "wechat",
channel: "official",
});SDK 通过以下机制实现自动追踪，无需手动关联 APP 事件：
- 重写全局
Page函数 - 自动拦截所有页面生命周期（onLoad、onShow、onHide 等） - 拦截事件处理函数 - 自动捕获用户交互（tap、longpress 等）
- 封装平台 API - 自动监听网络请求（wx.request）
- 监听 App 生命周期 - 自动捕获应用前后台切换、错误等
所有这些都在 flashcatRum.init() 时自动完成，开发者无需编写额外代码。
自动采集的 action（tap / longpress / longtap）按以下优先级确定名称：
- 触发元素的
data-name（其次data-content、data-type） mark:name（微信 mark 机制，事件冒泡路径上的标记会聚合）- 元素
id - 事件委托场景下
event.target的 dataset / id
都取不到时 action 名称显示为 unknown。小程序事件对象拿不到元素文本，建议给关键交互元素加 data-name：
<button bindtap="handleBuy" data-name="购买按钮">购买</button>业务关键动作也可以直接用 flashcatRum.addAction('purchase_submitted') 手动上报。
| 配置项 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
clientToken |
string | ✅ | - | 客户端 Token |
applicationId |
string | ✅ | - | 应用 ID |
site |
string | ❌ | browser.flashcat.cloud |
FlashCat 站点域名，自动拼接为 https://{site}/api/v2/rum |
proxy |
string | ❌ | - | 代理地址，SDK 拼接为 {proxy}?ddforward={encodedPath}（优先级高于 site） |
service |
string | ❌ | - | 服务名称 |
env |
string | ❌ | - | 环境（dev/test/prod） |
version |
string | ❌ | - | 应用版本号 |
sessionSampleRate |
number | ❌ | 100 | 会话采样率（0-100） |
flushInterval |
number | ❌ | 15000 | 上报间隔（毫秒） |
trackPages |
boolean | ❌ | true | 是否追踪页面 |
trackActions |
boolean | ❌ | true | 是否追踪用户交互 |
trackRequests |
boolean | ❌ | true | 是否追踪网络请求 |
trackErrors |
boolean | ❌ | true | 是否追踪错误 |
trackPerformance |
boolean | ❌ | true | 是否追踪性能 |
debug |
boolean | ❌ | false | 是否开启调试模式 |
beforeSend |
function | ❌ | - | 数据过滤钩子 |
flashcatRum.init(config)- 初始化 SDK
flashcatRum.startPage(name?)- 手动上报页面访问flashcatRum.addAction(name, type?)- 手动上报用户操作flashcatRum.addError(message, source?, stack?)- 手动上报错误flashcatRum.addTiming(name, value?)- 手动上报性能指标flashcatRum.addCustomEvent(name, context?)- 上报自定义事件
flashcatRum.setGlobalContext(context)- 设置全局上下文flashcatRum.setUser(context)- 设置用户信息
flashcatRum.stopSession()- 结束当前会话flashcatRum.getInitConfiguration()- 获取初始化配置
如果接入后没有数据上报，开启调试模式：
flashcatRum.init({
// ...
debug: true, // 开启调试模式，会在控制台输出详细日志
flushInterval: 5000, // 可选：缩短上报间隔方便测试
});查看控制台中 [FlashCat RUM] 开头的日志来诊断问题。
yarn install
yarn build
yarn test如需在本地小程序 demo 中验证未发布版本，可以先构建并打包：
yarn pack:all打包产物会生成在各 package 目录中：
packages/core/flashcatcloud-miniprogram-core.tgzpackages/miniprogram-platform/flashcatcloud-miniprogram-platform.tgzpackages/miniprogram-rum/flashcatcloud-miniprogram-rum.tgz
MIT