WeChat Mini Program SDK

The HealthGuard Mini Program SDK (@health-guard/sdk-miniprogram) captures errors, requests, and page lifecycle events in WeChat/Alipay mini-program runtimes.

Installation

npm install @health-guard/sdk-miniprogram

Basic Usage

import { createMiniProgramClient } from '@health-guard/sdk-miniprogram';

const client = createMiniProgramClient({
  appKey: 'your-app-key',
  endpoint: 'https://your-server.com/api/events/batch',
  wx: wx,
  autoCapture: true
});

Domain Allowlist

Mini-program runtimes require an HTTPS endpoint and the Collector domain must be added to the platform's request allowlist.

Configuration

Option	Type	Required	Default	Description
appKey	string	Yes	-	Unique app identifier
endpoint	string	Yes	-	Collector endpoint URL
wx	MiniProgramWxLike	Yes	-	The global wx / my runtime object
platform	string	No	wechat-miniprogram	Platform identifier, e.g. alipay-miniprogram
release	string	No	-	App version
environment	string	No	-	Environment: development / test / production
userId	string	No	-	Business user identifier
autoCapture	boolean | object	No	false	Auto-capture errors and requests
flushIntervalMs	number	No	5000	Batch flush interval in milliseconds
maxBatchSize	number	No	10	Max events per batch
transportFailureRetryDelayMs	number	No	30000	Backoff delay before retrying a failed transport (ms)

autoCapture Options

When autoCapture is true, all auto-capture features are enabled:

autoCapture: {
  request: true   // Intercept wx.request
}

Manual API

captureException(error, errorType?, context?)

Manually report an error:

try {
  riskyOperation();
} catch (err) {
  client.captureException(err);
}

You can also specify the error type and context:

client.captureException('custom error', 'native', { page: 'pages/order/detail' });

captureHttp(input)

Manually report an HTTP request:

client.captureHttp({
  method: 'POST',
  url: '/api/order',
  status: 500,
  duration: 240,
  success: false,
  errorMessage: 'Internal Server Error'
});

addBreadcrumb(breadcrumb)

Add a breadcrumb:

client.addBreadcrumb({
  type: 'click',
  message: 'User tapped submit button',
  data: { formId: 'checkout' }
});

wrapPage(route, definition)

Automatically add breadcrumbs for page lifecycle events:

Page(client.wrapPage('pages/index/index', {
  data: { ... },
  onLoad() { ... },
  onShow() { ... }
}));

wrapApp(definition)

Automatically add breadcrumbs for App lifecycle events:

App(client.wrapApp({
  onLaunch() { ... },
  onShow() { ... }
}));

flush()

Immediately flush the queue and send all pending events (including events requeued after a transport failure):

await client.flush();

Request Annotations

When using wx.request, you can attach context via the healthGuard field to avoid sending sensitive data:

wx.request({
  url: '/api/order',
  healthGuard: {
    page: 'pages/order/detail',
    scene: 'checkout',
    context: { orderId: '123' },
    requestData: { sku: 'abc' }   // Only sent if explicitly provided
  }
});

Privacy & Sanitization

• URL query parameters such as authorization, password, token, secret, and cookie are filtered by default.
• Request and response bodies are not collected automatically; use healthGuard.requestData if needed.
• Uses the business-provided userId or an anonymous ID; no real identity data is collected.