sentry-miniapp 1.8.2 → 1.10.0

package/README.en.md

@@ -10,7 +10,7 @@
 
 [简体中文](./README.md) | English
 
-A **mini program monitoring SDK** built on `@sentry/core`, providing **error monitoring**, **performance monitoring**, offline caching, and distributed tracing. Supports WeChat, Alipay, ByteDance, Baidu, QQ, DingTalk, Kuaishou mini programs and cross-platform frameworks (Taro / uni-app).
+A **mini program monitoring SDK** built on `@sentry/core`, providing **error monitoring**, **performance monitoring**, offline caching, and distributed tracing. Supports WeChat, Alipay, ByteDance, Baidu, QQ, DingTalk, Kuaishou mini programs, **WeChat / Douyin mini games**, and cross-platform frameworks (Taro / uni-app).
 
 > **What are Mini Programs?** Mini programs (小程序) are lightweight apps that run inside super-apps like WeChat, Alipay, and ByteDance/Douyin. They form a massive ecosystem in China with **hundreds of millions of daily active users**, but have no direct equivalent in the Western tech stack. Think of them as a hybrid between PWAs and native apps, but hosted within a platform's sandbox.
 
@@ -38,6 +38,7 @@ See [CHANGELOG.md](./CHANGELOG.md) for full details.
 
 - **Modern Architecture**: Built on the latest Sentry JavaScript V10 SDK core modules.
 - **True Multi-Platform Support**: Built-in API abstraction engine — one codebase seamlessly supports **WeChat, Alipay, ByteDance, Baidu, QQ, DingTalk, and Kuaishou** mini program platforms.
+- **Mini Game Support**: Auto-detects mini-game environments — error / network / device monitoring works out of the box, plus mini-game-specific **cold-start first-frame timing** and **frame-rate / jank (FPS) monitoring** (see "Mini Game Support" below).
 - **Automatic Exception Capture**: No business code intrusion required. Automatically hooks into lifecycle error listeners (`onError`, `onUnhandledRejection`, `onPageNotFound`, `onMemoryWarning`).
 - **Rich Context Breadcrumbs**: Automatically records device info, user tap/touch interactions, network requests (XHR/Fetch), and page lifecycle events.
 - **Built-in SourceMap Path Normalization**: Handles virtual stack paths across WeChat, Alipay, ByteDance and other platforms. Works with sentry-cli for seamless SourceMap resolution.
@@ -298,6 +299,43 @@ App({
 
 ---
 
+## Mini Game Support
+
+`sentry-miniapp` also works in **mini games** (WeChat / ByteDance mini games, etc.). Mini games have no `App()`/`Page()`/page routing, but expose platform APIs like `wx.onError`, `wx.request`, `wx.getDeviceInfo`, and `wx.getPerformance`. Most SDK capabilities work out of the box, plus mini-game-specific cold-start and frame-rate monitoring.
+
+**Initialization is identical to mini programs** — the SDK auto-detects the mini-game environment and enables the relevant features:
+
+```js
+import * as Sentry from 'sentry-miniapp';
+
+Sentry.init({
+  dsn: 'YOUR_DSN',
+  // Enabled by default in mini-game environments; set to false to disable:
+  // enableMinigameLifecycle: true,  // cold-start first-frame timing + launch scene + onShow/onHide breadcrumbs
+  // enableMinigameFrameRate: true,  // FPS / jank monitoring
+
+  // Fine-tune frame-rate monitoring (FPS warning threshold, jank threshold, report interval, etc.):
+  // minigameFrameRateOptions: { fpsWarningThreshold: 45 },
+});
+```
+
+### Capability matrix
+
+| Capability | Mini Game | Notes |
+|------------|:---------:|-------|
+| Exception / unhandled rejection capture | ✅ | `wx.onError` / `wx.onUnhandledRejection` |
+| API request monitoring (count / duration / status) | ✅ | wraps `wx.request` |
+| Network status monitoring | ✅ | `wx.onNetworkStatusChange` |
+| Device info / context breadcrumbs | ✅ | `wx.getDeviceInfo` etc. |
+| Resource load timing | ✅ | `wx.getPerformance()` |
+| **Cold-start first-frame timing + launch scene** | ✅ New | `MinigameIntegration` (first `requestAnimationFrame` ≈ first frame) |
+| **Frame rate / jank monitoring** | ✅ New | `MinigameFrameRateIntegration` (RAF FPS sampling, long frames → jank, periodic `minigame.framerate` context) |
+| Page lifecycle / tap breadcrumbs | ➖ | No pages in mini games — auto-skipped; use `onShow/onHide` breadcrumbs or manual `addBreadcrumb` |
+
+> These two integrations are enabled by default only in mini-game environments. In particular, **frame-rate monitoring relies on a global `requestAnimationFrame`**: mini games have one (bound to the real render loop), whereas mini programs use a dual-thread architecture whose logic layer has no global `requestAnimationFrame` — so even if enabled there, it safely no-ops (it cannot measure page render frame rate).
+
+---
+
 ## FAQ
 
 ### 1. Do I need to manually report errors in `onError`?
@@ -313,6 +351,41 @@ If errors are not being reported, check:
 
 **Not currently.** Sentry's official Replay feature relies on standard browser DOM (via rrweb recording). Mini programs use a dual-thread architecture without standard DOM access. We recommend using **Breadcrumbs** combined with **custom logging** to reconstruct user action sequences.
 
+### 3. How do I monitor the H5 build of a uni-app / Taro project?
+
+`sentry-miniapp` **only adapts mini program platforms** and does not implement browser-native signals (`window.onerror`, `fetch` / `XHR` interception, `PerformanceObserver`, etc.). For the H5 build, use Sentry's official [`@sentry/browser`](https://docs.sentry.io/platforms/javascript/) directly — full feature coverage, maintained upstream.
+
+> When this SDK is initialized in a browser environment, it logs a warning suggesting you switch to `@sentry/browser`.
+
+Recommended pattern: split SDKs by platform via **uni-app conditional compilation**:
+
+```ts
+// utils/sentry.ts
+let Sentry: any;
+
+// #ifdef H5
+Sentry = require('@sentry/browser');
+Sentry.init({
+  dsn: 'YOUR_DSN',
+  environment: 'production',
+  tracesSampleRate: 0.2,
+});
+// #endif
+
+// #ifdef MP-WEIXIN || MP-ALIPAY || MP-BAIDU || MP-TOUTIAO || MP-QQ || MP-KUAISHOU || MP-DINGTALK
+Sentry = require('sentry-miniapp');
+Sentry.init({
+  dsn: 'YOUR_DSN',
+  environment: 'production',
+  tracesSampleRate: 0.2,
+});
+// #endif
+
+export default Sentry;
+```
+
+Both sides report to the same Sentry DSN so all errors land in a single project. For Taro, use `process.env.TARO_ENV === 'h5'` to branch similarly.
+
 ---
 
 ## Documentation

package/README.md

@@ -10,7 +10,7 @@
 
 简体中文 | [English](./README.en.md)
 
-一个基于 `@sentry/core` 核心构建的**小程序监控 SDK**，提供**异常监控**、**性能监控**、离线缓存、分布式追踪等能力。支持微信、支付宝、字节跳动、百度、QQ、钉钉、快手等多端小程序及 Taro / uni-app 等跨端框架。
+一个基于 `@sentry/core` 核心构建的**小程序监控 SDK**，提供**异常监控**、**性能监控**、离线缓存、分布式追踪等能力。支持微信、支付宝、字节跳动、百度、QQ、钉钉、快手等多端小程序，以及微信 / 抖音等**小游戏**，并兼容 Taro / uni-app 等跨端框架。
 
 > **📰 最新文章**：[《我给 Sentry 提了个 PR，后来 sentry-miniapp 进了官方文档》](https://juejin.cn/post/7636106283963760681) — sentry-miniapp 已被收录进 Sentry 官方文档的 community-supported SDK 列表，这篇文章记录这件事的来龙去脉。觉得有用请帮忙点个 ⭐ Star，让更多小程序团队找到它。
 
@@ -36,6 +36,7 @@
 
 - **🚀 现代架构**：基于最新的 Sentry JavaScript V10 SDK 核心模块构建。
 - **📱 真正的多端支持**：内置 API 抹平引擎，一套代码无缝兼容**微信、支付宝、字节、百度、QQ、钉钉、快手**等主流小程序平台。
+- **🎮 小游戏支持**：自动识别小游戏环境，异常 / 网络 / 设备监控开箱即用，并提供小游戏专属的**冷启动首帧耗时**与**帧率 / 卡顿（FPS / jank）监控**（详见下文「小游戏支持」）。
 - **🎯 全自动异常捕获**：无需侵入业务代码，自动监听并上报生命周期异常（`onError`、`onUnhandledRejection`、`onPageNotFound`、`onMemoryWarning`）。
 - **🍞 丰富的上下文面包屑**：自动记录设备信息、用户点击/触摸操作、网络请求（XHR/Fetch）以及页面生命周期。
 - **🗺️ 内置 SourceMap 路径抹平**：自动处理微信、支付宝、字节等多端小程序的虚拟堆栈路径，配合 sentry-cli 极简实现 SourceMap 解析。
@@ -311,6 +312,43 @@ App({
 
 ---
 
+## 🎮 小游戏支持
+
+`sentry-miniapp` 同样适用于**小游戏**（微信小游戏 / 抖音小游戏等）。小游戏没有 `App()`/`Page()`/页面路由，但具备 `wx.onError`、`wx.request`、`wx.getDeviceInfo`、`wx.getPerformance` 等平台能力，因此 SDK 的大部分能力开箱即用，并额外提供小游戏专属的冷启动与帧率监控。
+
+**初始化与小程序完全一致**，SDK 会自动检测小游戏环境并启用对应能力：
+
+```js
+import * as Sentry from 'sentry-miniapp';
+
+Sentry.init({
+  dsn: 'YOUR_DSN',
+  // 小游戏环境下，以下两项默认即为开启，可显式关闭：
+  // enableMinigameLifecycle: true,  // 冷启动首帧耗时 + 启动场景 + onShow/onHide 面包屑
+  // enableMinigameFrameRate: true,  // 帧率(FPS)/卡顿(jank)监控
+
+  // 帧率监控细调（FPS 告警阈值、卡顿阈值、上报间隔等）：
+  // minigameFrameRateOptions: { fpsWarningThreshold: 45 },
+});
+```
+
+### 能力矩阵
+
+| 能力 | 小游戏 | 说明 |
+|------|:------:|------|
+| 异常 / 未处理 Promise 捕获 | ✅ | `wx.onError` / `wx.onUnhandledRejection` |
+| API 请求监控（请求数 / 耗时 / 状态码） | ✅ | 包裹 `wx.request` |
+| 网络状态监控 | ✅ | `wx.onNetworkStatusChange` |
+| 设备信息 / 上下文面包屑 | ✅ | `wx.getDeviceInfo` 等 |
+| 资源加载耗时 | ✅ | `wx.getPerformance()` |
+| **冷启动首帧耗时 + 启动场景** | ✅ 新增 | `MinigameIntegration`（首个 `requestAnimationFrame` 近似首帧） |
+| **帧率 / 卡顿监控** | ✅ 新增 | `MinigameFrameRateIntegration`（RAF 采样 FPS，长帧记 jank，周期上报 `minigame.framerate` 上下文） |
+| 页面生命周期 / 点击面包屑 | ➖ | 小游戏无页面，自动跳过；行为追踪请用 `onShow/onHide` 面包屑或手动 `addBreadcrumb` |
+
+> 上述两个集成仅在小游戏环境默认启用。其中**帧率监控依赖全局 `requestAnimationFrame`**：小游戏有（绑定真实渲染帧），而小程序为双线程架构、逻辑层没有全局 `requestAnimationFrame`，因此在小程序中即使开启也会安全 no-op（无法测量页面渲染帧率）。
+
+---
+
 ## ❓ 常见问题 (FAQ)
 
 ### 1. 初始化后无法自动上报异常，必须在 `onError` 中手动调 API 吗？
@@ -328,6 +366,41 @@ App({
 目前 **不支持** `Sentry.replayIntegration()`。
 Sentry 官方的 Replay 功能强依赖于浏览器标准 DOM 环境（通过 rrweb 录制）。小程序采用双线程架构且没有开放标准 DOM 接口，无法直接复用。建议通过完善**Breadcrumbs（面包屑路径）**结合**自定义日志**来还原用户操作现场。
 
+### 3. uni-app / Taro 项目的 H5 端如何监控？
+
+`sentry-miniapp` **仅适配各小程序平台**，不内置浏览器原生信号（`window.onerror`、`fetch` / `XHR` 拦截、`PerformanceObserver` 等）。H5 端请直接使用 Sentry 官方的 [`@sentry/browser`](https://docs.sentry.io/platforms/javascript/)，能力完整、长期由官方维护。
+
+> SDK 在 H5 环境下被错误初始化时，会输出引导提示，提醒切换到 `@sentry/browser`。
+
+推荐通过 **uni-app 条件编译**按端引入：
+
+```ts
+// utils/sentry.ts
+let Sentry: any;
+
+// #ifdef H5
+Sentry = require('@sentry/browser');
+Sentry.init({
+  dsn: 'YOUR_DSN',
+  environment: 'production',
+  tracesSampleRate: 0.2,
+});
+// #endif
+
+// #ifdef MP-WEIXIN || MP-ALIPAY || MP-BAIDU || MP-TOUTIAO || MP-QQ || MP-KUAISHOU || MP-DINGTALK
+Sentry = require('sentry-miniapp');
+Sentry.init({
+  dsn: 'YOUR_DSN',
+  environment: 'production',
+  tracesSampleRate: 0.2,
+});
+// #endif
+
+export default Sentry;
+```
+
+两端上报同一个 Sentry DSN，可以在同一个 Project 里聚合查看错误。Taro 用户可以用类似的 `process.env.TARO_ENV === 'h5'` 判断分端引入。
+
 ---
 
 ## 📖 文档导航