SDK Integration Guide

The WeChat Mini Program RUM SDK provides the flashcatRum instance through @flashcatcloud/miniprogram-rum. After initialization, the SDK automatically collects page lifecycle events, user actions, network requests, app errors, and performance metrics, then reports them to Flashduty RUM.

Prerequisites

Before integrating the SDK, complete these steps:

Create or select a RUM application in the Flashduty console, then obtain the Application ID and Client Token
Confirm that your Mini Program can access the RUM intake URL. The default URL is https://browser.flashcat.cloud/api/v2/rum; configure proxy if your network policy requires forwarding
Configure the request domain allowlist in the WeChat Official Platform: go to Development > Development Management > Development Settings > Server Domain and add https://browser.flashcat.cloud (or your proxy domain) to the request legal domains. Without this, WeChat blocks all reporting requests on real devices; during development, you can temporarily check the “Do not verify legal domains” option in WeChat DevTools
If you use WeChat DevTools, build npm so miniprogram_npm can reference the SDK package

Install the SDK

Install the RUM SDK in the Mini Program project root:

npm install @flashcatcloud/miniprogram-rum

After installation, run Tools > Build npm in WeChat DevTools.

Initialize the SDK

Initialize the SDK as early as possible in the Mini Program entry file. The SDK wraps page lifecycle hooks, request methods, and app error listeners during initialization, so initializing it in app.js is recommended.

app.js

import { flashcatRum } from "@flashcatcloud/miniprogram-rum";

flashcatRum.init({
  applicationId: "<YOUR_APPLICATION_ID>",
  clientToken: "<YOUR_CLIENT_TOKEN>",
  service: "wechat-miniprogram",
  env: "production",
  version: "1.0.0",
  sessionSampleRate: 100
});

Do not use server-side keys in client code. clientToken is the token for client-side reporting, and applicationId identifies the RUM application.

Initialization Parameters

Required Parameters

string

required

RUM application ID. The SDK writes it to application.id so Mini Program data is associated with the correct application.

string

required

Client reporting token. The SDK appends this value to RUM intake requests as the dd-api-key parameter.

Basic Optional Parameters

string

default:"browser.flashcat.cloud"

RUM intake site. When proxy is not configured, the SDK sends events to https://{site}/api/v2/rum.

string | function

Custom reporting proxy. A string proxy produces {proxy}?ddforward={encodedPath}. A function proxy receives { path, parameters } and returns the full intake URL.

string

Service name. The SDK writes it as the service:<value> tag so you can filter RUM data by service.

string

Environment name. The SDK writes it as the env:<value> tag, such as production or staging.

string

Application version. The SDK writes it as the version:<value> tag for release-based error and performance analysis.

number

default:"100"

Session sample rate. The value represents the percentage of sessions to collect. 100 collects all sessions, while 0 collects no session events.

For production environments, a lower sample rate (for example, 10 for 10% sampling) is typically recommended to reduce storage cost.

number

default:"15000"

Batch flush interval in milliseconds. By default, the SDK tries to flush event batches every 15 seconds and also flushes when the Mini Program moves to the background.

(event: unknown) => boolean | void

Callback executed before an event is sent. Return false to prevent the current event from being sent to Flashduty.

boolean

default:"false"

Enables debug logs. When enabled, the SDK logs initialization, monitoring startup, event collection, and batch reporting details to the console.

boolean

default:"true"

Controls whether the SDK generates an anonymous user ID when no user information is set. When enabled, the SDK writes the anonymous ID to usr.id and usr.anonymous_id.

Collection Toggles

The following toggles control automatic collection. They are all enabled by default:

Parameter	Type	Default	Description
`trackPages`	boolean	`true`	Collects page lifecycle data and creates view events
`trackActions`	boolean	`true`	Collects user actions from page event handlers and creates action events
`trackRequests`	boolean	`true`	Collects `wx.request`, `wx.uploadFile`, and `wx.downloadFile` calls and creates resource events
`trackErrors`	boolean	`true`	Collects errors from `wx.onError`, `wx.onUnhandledRejection`, page-not-found events, subpackage lazy-load failures, and failed network requests
`trackPerformance`	boolean	`true`	Collects page rendering, startup, and script execution metrics through `wx.getPerformance`

Use User Information and Global Context

After sign-in, use setUser() to associate events with the current user. The SDK writes these fields to the usr object on subsequent RUM events.

app.js

flashcatRum.setUser({
  id: "user-123",
  name: "Alice",
  email: "alice@example.com"
});

You can also use setGlobalContext() to add business context. Global context is written to the context field on subsequent events.

app.js

flashcatRum.setGlobalContext({
  tenant: "acme",
  release_channel: "stable"
});

Manually Report Events

In addition to automatic collection, you can add business events, errors, actions, and custom timings manually.

pages/order/detail.js

import { flashcatRum } from "@flashcatcloud/miniprogram-rum";

Page({
  onPayTap() {
    flashcatRum.addAction("pay_button_tap", "tap");

    try {
      // Run business logic
    } catch (error) {
      flashcatRum.addError(error.message, "custom", error.stack);
    }
  },

  onCouponLoaded(couponId) {
    flashcatRum.addCustomEvent("coupon_loaded", { couponId });
    flashcatRum.addTiming("coupon_loaded");
  }
});

Method	Description
`addAction(name, type?)`	Manually reports an action event. The default type is `custom`
`addError(message, source?, stack?)`	Manually reports an error event. The public API uses `custom` as the source
`addTiming(name, time?)`	Records a custom timing on the current page view. Invalid characters in the name are replaced with `_`
`addCustomEvent(name, context?)`	Reports a custom event with optional context
`startPage(name?)`	Manually starts a page view, useful for overriding the automatic page name or recording a virtual page
`stopSession()`	Clears the current session. The next event creates a new session
`getInitConfiguration()`	Returns the latest initialization configuration

Next Steps

Advanced Configuration

Configure proxying, distributed tracing, sessions, and manual instrumentation.

Compatibility

Learn about Mini Program base library, development tool, and platform API requirements.

Data Collection

Learn which event types, fields, and platform APIs the SDK collects automatically.

Quick Start

Analytics

SDK Integration

Performance

Error Tracking

Explorer

Session Replay

Best Practices

Others

Prerequisites

Install the SDK

Initialize the SDK

Initialization Parameters

Required Parameters

Basic Optional Parameters

Collection Toggles

Use User Information and Global Context

Manually Report Events

Next Steps

Advanced Configuration

Compatibility

Data Collection

​Prerequisites

​Install the SDK

​Initialize the SDK

​Initialization Parameters

​Required Parameters

​Basic Optional Parameters

​Collection Toggles

​Use User Information and Global Context

​Manually Report Events

​Next Steps

Advanced Configuration

Compatibility

Data Collection

Prerequisites

Install the SDK

Initialize the SDK

Initialization Parameters

Required Parameters

Basic Optional Parameters

Collection Toggles

Use User Information and Global Context

Manually Report Events

Next Steps