sentry-miniapp-sdk

Sentry Mini Program SDK Setup

Set up Sentry error monitoring, performance tracing, and offline caching in mini program projects using sentry-miniapp — a community SDK built on @sentry/core v10.

Invoke This Skill When

• User mentions mini program, miniapp, 小程序, WeChat, Alipay, ByteDance, Taro, uni-app alongside Sentry
• User wants to add error monitoring or performance tracking to a mini program
• User asks about Sentry support for WeChat/Alipay/ByteDance mini programs
• User imports or references sentry-miniapp in their project

Note: SDK versions and APIs reflect the current sentry-miniapp docs. Always verify against the sentry-miniapp README before implementing.

---

Phase 1: Detect

Run these commands to understand the project:

# Detect mini program platform
ls app.json project.config.json mini.project.json 2>/dev/null
cat app.json 2>/dev/null | head -20

# Detect framework (Taro / uni-app / native)
cat package.json 2>/dev/null | grep -E '"@tarojs/|"@dcloudio/uni-|"sentry-miniapp"'

# Check for existing Sentry SDK
grep -r "sentry" package.json 2>/dev/null
grep -r "Sentry.init" app.js app.ts src/app.js src/app.ts 2>/dev/null

# Detect entry point
ls app.js app.ts src/app.js src/app.ts 2>/dev/null

# Detect package manager
ls yarn.lock pnpm-lock.yaml package-lock.json 2>/dev/null

What to determine:

Platform Detection Guide

---

Phase 2: Recommend

Present this recommendation based on detection results:

Recommended (core coverage):

• ✅ Error Monitoring — always. Automatic capture of onError, onUnhandledRejection, onPageNotFound, onMemoryWarning
• ✅ Performance Tracing — always. Navigation timing, render performance, resource loading, custom spans

Recommended for production:

• ⚡ Source Map Upload — when deploying to production. Maps minified stack traces back to source code
• ⚡ Offline Cache — when users are on unreliable networks. Caches events locally, retries when connectivity returns

Optional:

• ⚡ Distributed Tracing — when mini program calls backend APIs. Injects sentry-trace/baggage headers to link frontend and backend spans
• ⚡ User Feedback — when you want to collect user-reported issues via Sentry.captureFeedback()

---

Phase 3: Guide

Step 1: Install

# npm
npm install sentry-miniapp

# yarn
yarn add sentry-miniapp

Step 2: Initialize

Create or modify the app entry point. Sentry.init() must be called before App().

Native Mini Program (app.js)

const Sentry = require('sentry-miniapp');

Sentry.init({
  dsn: 'https://<key>@<org>.ingest.sentry.io/<project>',
  release: 'my-miniapp@1.0.0',
  environment: 'production',
});

App({
  // Your app config...
  // No need to manually call Sentry in onError — SDK handles it automatically
});

Taro (app.js or app.ts)

import * as Sentry from 'sentry-miniapp';

Sentry.init({
  dsn: 'https://<key>@<org>.ingest.sentry.io/<project>',
  release: 'my-miniapp@1.0.0',
  environment: 'production',
});

// Taro App component follows...

uni-app (App.vue or main.js)

const Sentry = require('sentry-miniapp');

Sentry.init({
  dsn: 'https://<key>@<org>.ingest.sentry.io/<project>',
  release: 'my-miniapp@1.0.0',
  environment: 'production',
});

Step 3: Configure Platform (if needed)

The SDK auto-detects the platform at runtime. No explicit platform option is required in most cases.

If you need to force a specific platform:

Sentry.init({
  dsn: '...',
  platform: 'wechat', // 'wechat' | 'alipay' | 'bytedance' | 'qq' | 'swan' | 'dingtalk' | 'kuaishou'
  // Note: Baidu's global object is `swan`, so use 'swan' (there is no 'baidu' value).
});

Step 4: Add User Context

// After user login
Sentry.setUser({
  id: 'user-123',
  username: 'zhang_san',
});

// Add custom tags
Sentry.setTag('page', 'payment');
Sentry.setContext('order', { orderId: '2024001', amount: 99.9 });

Minigame (小游戏)

WeChat / ByteDance minigames have no App() / Page() / routing, so the page-based integrations (PageBreadcrumbs, Session) cannot work there. The SDK detects minigames via crossPlatform.isMinigame() and switches to dedicated integrations — enabled by default only in a minigame runtime, and a safe no-op in a regular mini program:

• MinigameIntegration (enableMinigameLifecycle) — reads the launch scene (scene / path / query) from getLaunchOptionsSync(), measures cold-start time (SDK init → first frame), and logs onShow / onHide foreground/background breadcrumbs.
• FrameRateIntegration (enableMinigameFrameRate) — samples the global requestAnimationFrame to estimate FPS and jank. Mini programs use a two-thread model with no logic-layer requestAnimationFrame, so this safely no-ops there.

No extra wiring is needed — Sentry.init() auto-enables these in a minigame. To force them on or off:

Sentry.init({
  dsn: '...',
  enableMinigameLifecycle: true,
  enableMinigameFrameRate: true,
});

For Each Agreed Feature

Walk through features one at a time. Load the corresponding reference file:

---

Configuration Reference

Key Init Options

Privacy Consent Gate

For domestic mini program / mini game privacy flows, initialize with requireConsent: true. Before the user agrees, the SDK still collects errors, breadcrumbs, and performance data, but sends no Sentry network requests; events are buffered in miniapp storage and flushed after consent.

Sentry.init({
  dsn: '...',
  requireConsent: true,
  consentCacheLimit: 100,
});

// After the user agrees to the privacy policy
Sentry.setConsent(true);

// If consent is revoked, block outbound sends again
Sentry.setConsent(false);

requireConsent implies local buffering even when enableOfflineCache is false; custom transport functions are wrapped by the consent gate too. The current store uses one storage key, so keep consentCacheMaxBytes near the default ~900KB unless the SDK adds sharded storage in a future version.

Platform Compatibility

✅ = supported through the SDK's cross-platform abstraction, not a per-host on-device certification. WeChat / Alipay / ByteDance are the most battle-tested; validate less common hosts (Kuaishou, DingTalk) in your own environment before relying on them in production.

---

Verification

After setup, verify the integration:

1. Trigger a test error:

// In any page
Sentry.captureException(new Error('Test error from mini program'));

2. Check Sentry dashboard:

   • Go to your Sentry project → Issues
   • You should see the test error with:
     • Device info (brand, model, OS)
     • Mini program context (platform, SDK version)
     • Breadcrumbs (page navigation, network requests)

3. Verify automatic capture works:

   • Throw an unhandled error in a page — it should appear in Sentry without any manual captureException call

---

Phase 4: Cross-Link

After mini program setup, check for companion services:

# Check for backend services in the same workspace
ls -d ../*/package.json ../*/requirements.txt ../*/go.mod ../*/Gemfile 2>/dev/null

Tip: Enable distributed tracing on both mini program and backend to get end-to-end request traces across services.

---

Troubleshooting