sentry-miniapp 1.8.0 → 1.8.2

package/README.en.md

@@ -1,22 +1,36 @@
 # Sentry Miniapp SDK — Mini Program Monitoring SDK
 
-![npm version](https://img.shields.io/npm/v/sentry-miniapp)
-![npm downloads/month](https://img.shields.io/npm/dm/sentry-miniapp)
-![github forks](https://img.shields.io/github/forks/lizhiyao/sentry-miniapp?style=social)
-![github stars](https://img.shields.io/github/stars/lizhiyao/sentry-miniapp?style=social)
+[![npm version](https://img.shields.io/npm/v/sentry-miniapp)](https://www.npmjs.com/package/sentry-miniapp)
+[![npm downloads/month](https://img.shields.io/npm/dm/sentry-miniapp)](https://www.npmjs.com/package/sentry-miniapp)
+[![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)
-![license](https://img.shields.io/github/license/lizhiyao/sentry-miniapp)
+[![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
 
-A **mini program monitoring SDK** built on `@sentry/core` (v10.45.0), 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 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.
 
-> **Version Notes**
->
-> - `v1.x.x`: New architecture based on Sentry V10 core. Full support for WeChat, Alipay, ByteDance, Baidu, QQ, DingTalk, Kuaishou mini programs and cross-platform frameworks (Taro / uni-app).
-> - `v0.x.x`: Legacy version, no longer maintained.
+> **📰 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>
+
+| Version | Highlights |
+|---|---|
+| **v1.8.0** | AI-assisted integration skill — auto onboarding via Claude Code / Cursor |
+| **v1.7.0** | New `tracesSampler` for dynamic sampling; complete Source Map configuration guide |
+| **v1.6.0** | 13 enhancements + 16 fixes; enabled esbuild minification — bundle size reduced by ~**59%** |
+| **v1.5.0** | Performance enhancements (configurable thresholds / slow `setData` detection / memory sampling); new page lifecycle, user interaction, and Console breadcrumbs; route integration covers all platforms |
+| **v1.4.0** | `NetworkBreadcrumbs` captures Request / Response body; configurable offline cache limit; deprecated `showReportDialog` in favor of `captureFeedback` |
+| **v1.3.0** | 🎯 Build pipeline rewrite (Vite + bundle-inline): **zero external deps**, fully resolves the `miniprogram_npm` module-resolution issue; 🎯 built-in Source Map path normalization across all platforms |
+
+See [CHANGELOG.md](./CHANGELOG.md) for full details.
+
+</details>
 
 ---
 
@@ -25,7 +39,7 @@ A **mini program monitoring SDK** built on `@sentry/core` (v10.45.0), providing
 - **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.
@@ -44,8 +58,6 @@ A **mini program monitoring SDK** built on `@sentry/core` (v10.45.0), providing
 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.*
 
 ---
@@ -82,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)
@@ -105,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({
@@ -123,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
@@ -167,13 +171,15 @@ Sentry.addBreadcrumb({
 ### Custom Performance Measurement
 
 ```javascript
-// Mark start point
-Sentry.addPerformanceMark('api-request-start');
-// ... perform operation
-Sentry.addPerformanceMark('api-request-end');
-
-// Measure the interval
-Sentry.measurePerformance('fetch-user-data', 'api-request-start', 'api-request-end');
+await Sentry.startSpan(
+  {
+    name: 'fetch-user-data',
+    op: 'http.client',
+  },
+  async () => {
+    await fetchUserData();
+  },
+);
 ```
 
 ### Dynamic Sampling (tracesSampler)

package/README.md

@@ -1,20 +1,34 @@
 # Sentry Miniapp SDK — 小程序监控 SDK
 
-![npm version](https://img.shields.io/npm/v/sentry-miniapp)
-![npm download](https://img.shields.io/npm/dm/sentry-miniapp)
-![github forks](https://img.shields.io/github/forks/lizhiyao/sentry-miniapp?style=social)
-![github stars](https://img.shields.io/github/stars/lizhiyao/sentry-miniapp?style=social)
+[![npm version](https://img.shields.io/npm/v/sentry-miniapp)](https://www.npmjs.com/package/sentry-miniapp)
+[![npm download](https://img.shields.io/npm/dm/sentry-miniapp)](https://www.npmjs.com/package/sentry-miniapp)
+[![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)
-![license](https://img.shields.io/github/license/lizhiyao/sentry-miniapp)
+[![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` (v10.45.0) 核心构建的**小程序监控 SDK**，提供**异常监控**、**性能监控**、离线缓存、分布式追踪等能力。支持微信、支付宝、字节跳动、百度、QQ、钉钉、快手等多端小程序及 Taro / uni-app 等跨端框架。
+一个基于 `@sentry/core` 核心构建的**小程序监控 SDK**，提供**异常监控**、**性能监控**、离线缓存、分布式追踪等能力。支持微信、支付宝、字节跳动、百度、QQ、钉钉、快手等多端小程序及 Taro / uni-app 等跨端框架。
 
-> **💡 版本说明**
->
-> - `v1.x.x`：全新架构，基于 Sentry V10 核心，全面支持微信、支付宝、字节跳动、百度、QQ、钉钉、快手等多端小程序及主流跨端框架（Taro / uni-app 等）。
-> - `v0.x.x`：旧版本，已停止维护。
+> **📰 最新文章**：[《我给 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>
+
+| 版本 | 亮点 |
+|---|---|
+| **v1.8.0** | AI 辅助接入 skill — Claude Code / Cursor 自动引导集成 |
+| **v1.7.0** | 新增 `tracesSampler` 动态采样；新增 Source Map 完整配置指南 |
+| **v1.6.0** | 13 项功能优化 + 16 项问题修复；启用 esbuild 压缩，包体积减少约 **59%** |
+| **v1.5.0** | Performance 增强（可配阈值 / setData 慢渲染检测 / 内存采集）；新增页面生命周期、用户交互、Console 三类 Breadcrumb；Route 集成全平台适配 |
+| **v1.4.0** | NetworkBreadcrumbs 抓 Request / Response Body；离线缓存上限可配；废弃 `showReportDialog` 引导至 `captureFeedback` |
+| **v1.3.0** | 🎯 重构构建（迁移 Vite + bundle-inline）：对外**零依赖**，彻底修掉「`miniprogram_npm` 模块解析」问题；🎯 内置 Source Map 路径自动抹平，跨端堆栈统一映射 |
+
+完整变更见 [CHANGELOG.md](./CHANGELOG.md)。
+
+</details>
 
 ---
 
@@ -23,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 面板展示崩溃率和会话健康数据。
@@ -44,8 +58,6 @@
 npm install sentry-miniapp
 ```
 
-> **注意：** `v1.1.0` 及以上版本已优化构建策略（内联依赖），**无需**再额外安装 `@sentry/core`。
-
 *提示：如果您不使用 npm，也可以直接将项目仓库中 `examples/wxapp/lib/sentry-miniapp.js` 文件复制到小程序项目中引入。*
 
 ---
@@ -82,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, // 开启断网离线缓存与重试机制 (默认开启)
@@ -99,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
@@ -124,6 +126,8 @@ App({
 });
 ```
 
+默认集成已经包含自动异常捕获、性能监控、Source Map 路径归一化、网络面包屑、Session 和网络状态监控。只有在需要完全接管集成列表时才传入 `integrations`，否则会覆盖默认集成。
+
 ---
 
 ## 📚 常用进阶用法
@@ -168,13 +172,15 @@ Sentry.addBreadcrumb({
 ### 自定义性能测速 (Performance)
 
 ```javascript
-// 标记起始点
-Sentry.addPerformanceMark('api-request-start');
-// ... 执行耗时操作
-Sentry.addPerformanceMark('api-request-end');
-
-// 测量并记录该区间
-Sentry.measurePerformance('fetch-user-data', 'api-request-start', 'api-request-end');
+await Sentry.startSpan(
+  {
+    name: 'fetch-user-data',
+    op: 'http.client',
+  },
+  async () => {
+    await fetchUserData();
+  },
+);
 ```
 
 ### 动态采样 (tracesSampler)
@@ -210,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
 ```