sentry-miniapp 1.8.1 → 1.9.0

package/README.en.md

@@ -5,6 +5,7 @@
 [![github forks](https://img.shields.io/github/forks/lizhiyao/sentry-miniapp?style=social)](https://github.com/lizhiyao/sentry-miniapp/network/members)
 [![github stars](https://img.shields.io/github/stars/lizhiyao/sentry-miniapp?style=social)](https://github.com/lizhiyao/sentry-miniapp/stargazers)
 ![test coverage](https://img.shields.io/badge/test%20coverage-100%25-brightgreen.svg)
+[![Sentry Community SDK](https://img.shields.io/badge/Sentry-Community%20SDK-362d59?logo=sentry)](https://docs.sentry.io/platforms/#sdks-supported-by-our-community)
 [![license](https://img.shields.io/github/license/lizhiyao/sentry-miniapp)](./LICENSE)
 
 [简体中文](./README.md) | English
@@ -13,7 +14,7 @@ A **mini program monitoring SDK** built on `@sentry/core`, providing **error mon
 
 > **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.
 
-> **📰 Featured Article (Chinese)**: [《我把 Sentry 接进了 7 端小程序：从异常捕获、Breadcrumb 到 Source Map 定位》](https://juejin.cn/post/7621871037853843465) — multi-platform integration, Breadcrumb context, offline buffering, and Source Map workflow walked through end-to-end. If you find this project useful, please consider giving it a ⭐ Star.
+> **📰 Featured Article (Chinese)**: [《我给 Sentry 提了个 PR，后来 sentry-miniapp 进了官方文档》](https://juejin.cn/post/7636106283963760681) — How sentry-miniapp got listed in Sentry's official community-supported SDKs documentation. If you find this project useful, please consider giving it a ⭐ Star.
 
 <details>
 <summary><b>🆕 What's New: v1.3 → v1.8 (click to expand)</b></summary>
@@ -38,7 +39,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.
 - **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 navigation paths.
+- **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.
 - **Offline Caching for Weak Networks**: Designed for mini program network conditions. Automatically caches events to local storage on network failure, silently retries when connectivity is restored.
 - **Deep Performance Monitoring**: Integrates mini program Performance API for navigation timing (FCP/LCP), render performance, resource loading, and custom performance marks.
@@ -57,8 +58,6 @@ See [CHANGELOG.md](./CHANGELOG.md) for full details.
 npm install sentry-miniapp
 ```
 
-> **Note:** Starting from `v1.1.0`, the build strategy has been optimized (dependencies are inlined), so there is **no need** to install `@sentry/core` separately.
-
 *Tip: If you don't use npm, you can also copy `examples/wxapp/lib/sentry-miniapp.js` from this repository directly into your mini program project.*
 
 ---
@@ -95,11 +94,10 @@ Sentry.init({
   release: 'my-project-name@1.0.0',
 
   // --- Mini Program Configuration ---
-  platform: 'wechat', // Current platform (wechat | alipay | bytedance | dd | swan, etc.)
-  enableSystemInfo: true, // Auto-collect system and device info
+  platform: 'wechat', // Optional event platform label; runtime platform is auto-detected
   enableUserInteractionBreadcrumbs: true, // Auto-record user tap events
-  enableNavigationBreadcrumbs: true, // Auto-record page navigation
-  traceNetworkBody: true, // Record request/response bodies in breadcrumbs (default: false)
+  enableConsoleBreadcrumbs: false, // Record console output as breadcrumbs (default: false)
+  traceNetworkBody: false, // Record request/response bodies in breadcrumbs (default: false)
 
   // --- Offline Cache & Reliability ---
   enableOfflineCache: true, // Enable offline caching with retry (default: true)
@@ -118,15 +116,6 @@ Sentry.init({
   // --- Session & Network Monitoring ---
   enableAutoSessionTracking: true, // Auto session lifecycle management (default: true)
   enableNetworkStatusMonitoring: true, // Real-time network status monitoring (default: true)
-
-  // Optional: Performance monitoring
-  integrations: [
-    Sentry.performanceIntegration({
-      enableNavigation: true, // Navigation timing
-      enableRender: true, // Render timing
-      enableResource: true, // Resource loading timing
-    }),
-  ]
 });
 
 App({
@@ -136,6 +125,8 @@ App({
 });
 ```
 
+Default integrations already include automatic exception capture, performance monitoring, SourceMap path normalization, network breadcrumbs, session tracking, and network status monitoring. Only pass `integrations` when you intentionally want to take over the full integration list, because it replaces the defaults.
+
 ---
 
 ## Advanced Usage
@@ -322,6 +313,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

@@ -5,13 +5,14 @@
 [![github forks](https://img.shields.io/github/forks/lizhiyao/sentry-miniapp?style=social)](https://github.com/lizhiyao/sentry-miniapp/network/members)
 [![github stars](https://img.shields.io/github/stars/lizhiyao/sentry-miniapp?style=social)](https://github.com/lizhiyao/sentry-miniapp/stargazers)
 ![test coverage](https://img.shields.io/badge/test%20coverage-100%25-brightgreen.svg)
+[![Sentry Community SDK](https://img.shields.io/badge/Sentry-Community%20SDK-362d59?logo=sentry)](https://docs.sentry.io/platforms/#sdks-supported-by-our-community)
 [![license](https://img.shields.io/github/license/lizhiyao/sentry-miniapp)](./LICENSE)
 
 简体中文 | [English](./README.en.md)
 
 一个基于 `@sentry/core` 核心构建的**小程序监控 SDK**，提供**异常监控**、**性能监控**、离线缓存、分布式追踪等能力。支持微信、支付宝、字节跳动、百度、QQ、钉钉、快手等多端小程序及 Taro / uni-app 等跨端框架。
 
-> **📰 最新文章**：[《我把 Sentry 接进了 7 端小程序：从异常捕获、Breadcrumb 到 Source Map 定位》](https://juejin.cn/post/7621871037853843465) — 多端统一接入、Breadcrumb 上下文、弱网兜底、Source Map 实战，一篇串完整套方案。觉得有用请帮忙点个 ⭐ Star，让更多小程序团队找到它。
+> **📰 最新文章**：[《我给 Sentry 提了个 PR，后来 sentry-miniapp 进了官方文档》](https://juejin.cn/post/7636106283963760681) — sentry-miniapp 已被收录进 Sentry 官方文档的 community-supported SDK 列表，这篇文章记录这件事的来龙去脉。觉得有用请帮忙点个 ⭐ Star，让更多小程序团队找到它。
 
 <details>
 <summary><b>🆕 v1.3 → v1.8 What's New（点击展开）</b></summary>
@@ -36,11 +37,11 @@
 - **🚀 现代架构**：基于最新的 Sentry JavaScript V10 SDK 核心模块构建。
 - **📱 真正的多端支持**：内置 API 抹平引擎，一套代码无缝兼容**微信、支付宝、字节、百度、QQ、钉钉、快手**等主流小程序平台。
 - **🎯 全自动异常捕获**：无需侵入业务代码，自动监听并上报生命周期异常（`onError`、`onUnhandledRejection`、`onPageNotFound`、`onMemoryWarning`）。
-- **🍞 丰富的上下文面包屑**：自动记录设备信息、用户点击/触摸操作、网络请求（XHR/Fetch）、以及页面路由导航路径。
+- **🍞 丰富的上下文面包屑**：自动记录设备信息、用户点击/触摸操作、网络请求（XHR/Fetch）以及页面生命周期。
 - **🗺️ 内置 SourceMap 路径抹平**：自动处理微信、支付宝、字节等多端小程序的虚拟堆栈路径，配合 sentry-cli 极简实现 SourceMap 解析。
 - **📡 弱网离线缓存机制**：专为小程序网络环境设计，断网或发送失败时自动缓存 Event 到本地 Storage，网络恢复后静默重试上报，确保数据不丢失。
 - **⚡ 深度性能监控**：集成小程序 Performance API，全面采集导航性能（FCP/LCP）、渲染性能、资源加载耗时及用户自定义性能标记。
-- **�️ 智能降噪与过滤**：内置强大的错误去重和采样率控制机制，避免日志风暴。
+- **🛡️ 智能降噪与过滤**：内置强大的错误去重和采样率控制机制，避免日志风暴。
 - **🔧 跨端框架友好**：完美支持在 Taro、uni-app 等第三方多端编译框架中集成使用。
 - **🔗 分布式追踪**：自动在网络请求中注入 `sentry-trace` / `baggage` 头，串联小程序与后端服务的完整调用链。
 - **📊 Session 健康监控**：自动管理会话生命周期，在 Sentry Release Health 面板展示崩溃率和会话健康数据。
@@ -57,8 +58,6 @@
 npm install sentry-miniapp
 ```
 
-> **注意：** `v1.1.0` 及以上版本已优化构建策略（内联依赖），**无需**再额外安装 `@sentry/core`。
-
 *提示：如果您不使用 npm，也可以直接将项目仓库中 `examples/wxapp/lib/sentry-miniapp.js` 文件复制到小程序项目中引入。*
 
 ---
@@ -95,11 +94,10 @@ Sentry.init({
   release: 'my-project-name@1.0.0', // 版本号，建议与 sourcemap 配合使用
   
   // --- 小程序特性配置 ---
-  platform: 'wechat', // 当前平台 (wechat | alipay | bytedance | dd | swan 等)
-  enableSystemInfo: true, // 自动采集系统与设备信息
+  platform: 'wechat', // 可选：用于标识事件平台；SDK 会自动识别运行时平台
   enableUserInteractionBreadcrumbs: true, // 自动记录用户点击行为
-  enableNavigationBreadcrumbs: true, // 自动记录页面路由跳转
-  traceNetworkBody: true, // [新增] 是否在面包屑中记录网络请求的请求体和响应体 (默认 false)
+  enableConsoleBreadcrumbs: false, // 是否记录 console 输出为面包屑（默认 false）
+  traceNetworkBody: false, // 是否在面包屑中记录网络请求/响应体（默认 false，按需开启）
   
   // --- 离线缓存与可靠性 ---
   enableOfflineCache: true, // 开启断网离线缓存与重试机制 (默认开启)
@@ -112,21 +110,12 @@ Sentry.init({
   sampleRate: 1.0, // 异常上报采样率 (0.0 - 1.0)
 
   // --- 分布式追踪 ---
-  enableTracePropagation: true, // [新增] 自动在请求头中注入 sentry-trace/baggage（默认 true）
-  tracePropagationTargets: ['api.example.com'], // [新增] 仅对指定域名注入追踪头（为空则全部注入）
+  enableTracePropagation: true, // 自动在请求头中注入 sentry-trace/baggage（默认 true）
+  tracePropagationTargets: ['api.example.com'], // 仅对指定域名注入追踪头（为空则全部注入）
 
   // --- Session 与网络监控 ---
-  enableAutoSessionTracking: true, // [新增] 自动管理 Session 生命周期（默认 true）
-  enableNetworkStatusMonitoring: true, // [新增] 实时监控网络状态变化（默认 true）
-
-  // 可选：性能监控配置
-  integrations: [
-    Sentry.performanceIntegration({
-      enableNavigation: true, // 导航耗时监控
-      enableRender: true, // 渲染耗时监控
-      enableResource: true, // 资源加载耗时
-    }),
-  ]
+  enableAutoSessionTracking: true, // 自动管理 Session 生命周期（默认 true）
+  enableNetworkStatusMonitoring: true, // 实时监控网络状态变化（默认 true）
 });
 
 // 初始化完成后，再调用 App
@@ -137,6 +126,8 @@ App({
 });
 ```
 
+默认集成已经包含自动异常捕获、性能监控、Source Map 路径归一化、网络面包屑、Session 和网络状态监控。只有在需要完全接管集成列表时才传入 `integrations`，否则会覆盖默认集成。
+
 ---
 
 ## 📚 常用进阶用法
@@ -225,8 +216,8 @@ SDK 内置了多端堆栈路径归一化能力（`enableSourceMap: true`，默
 **快速上传示例：**
 
 ```bash
-sentry-cli releases files “my-miniapp@1.0.0” upload-sourcemaps ./dist \
-  --url-prefix “app:///” \
+sentry-cli releases files "my-miniapp@1.0.0" upload-sourcemaps ./dist \
+  --url-prefix "app:///" \
   --ext js --ext map
 ```
 
@@ -337,6 +328,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'` 判断分端引入。
+
 ---
 
 ## 📖 文档导航