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 project.tt.json project.swan.json project.qq.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

DingTalk and Kuaishou do not have a stable project-file signal in this guide. Confirm them from platform globals, framework configuration, dependencies, or the user's stated target instead of guessing from a filename.

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, and can optionally add W3C traceparent, 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: '[email protected]',
  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: '[email protected]',
  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: '[email protected]',
  environment: 'production',
});

Step 3: Configure Platform (if needed)

The SDK auto-detects the platform at runtime. When multiple platform globals are present, it uses platform-specific host names, data paths, and App IDs to disambiguate them. Set platform only when those runtime signals are unavailable, conflicting, or the detected event label still does not match the release target.

If you need to override the event's miniapp platform label:

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

The configured value is written to contexts.miniapp.platform; it does not switch the underlying runtime API. The top-level Sentry event platform always remains the standard value javascript so stack parsing, grouping, and Source Maps follow official JavaScript SDK semantics. Error handlers, requests, and storage continue using the compatible global detected automatically.

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

The built-in transport defaults to requestTimeout: 3000 and maxConcurrentRequests: 2 so Sentry cannot occupy all mini program network slots when the service is unavailable. Additional envelopes wait in the bounded @sentry/core buffer. A timed-out request is aborted when the host returns an abortable request task, then handed to offline caching. Keep these defaults unless real-device testing shows a need to adjust them; transportOptions.headers remains available for custom envelope headers.

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)
     • Top-level platform: javascript
     • Mini program context (host platform and host SDK version)
     • App context (app_version from miniProgram.version when available)
     • 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