DocsICP FilingConsole
Documentation
Home Page Quick Tracking Developer Reference SDK Reference Performance Experience SDK Mini program SDK

Mini program SDK

Updated at:
Copy as MD
Product
My Favorites

SDK integration overview

Step

Task

Reference

Required

Step 1

Download the SDK

See 1. Download the SDK.

Yes

Step 2

Development configuration

See 2. Development configuration.

Yes

Step 3

SDK integration

See 3. SDK integration.

Yes

Step 4

Set initialization parameters

See 4. Initialization parameters.

Yes

See 4. Initialization parameters.

Yes

Before you begin, obtain an appKey for your application.

1. Download the SDK

Download and decompress the SDK package. Place the contents in your mini program's source code directory.

2. Development configuration

2.1 WeChat backend configuration

    1. Add your APM service's data collection domain to the domain whitelist.

      To do this, navigate to Development Management > Development Settings > Server Domain Name > Modify, and then enter the domain in the request valid domain name field.

    2. image

    3. image

    4. image

    1. If you cannot configure the domain whitelist for now, you can select the Do not validate domains option in the Mini Program editor panel during the development phase.

      image.png

2.2 Alipay configuration

  1. Add your APM service's data collection domain to the domain whitelist. image.png

  2. If you cannot configure the domain whitelist for now, you can check the 'Do not verify valid domain names' option in the mini program editor panel during the development phase.image.png

3. SDK integration

Initialize the SDK by importing it at the top of your app.js file. Use the wx-prefixed file for WeChat and the alipay-prefixed file for Alipay. Follow one of the integration methods below.

The SDK provides two module formats: cjs (CommonJS) and esm (ES Modules). For a native mini program, use require to import the cjs module. For other projects, use import for the esm module.

3.1 Method 1: Declarative method for native mini programs

ESM import

// Import using ESM
import { init } from './build/wx.esm';

init({
  appKey: 'YOUR_APP_KEY',
  dsn: 'YOUR_DATA_COLLECTION_DOMAIN',
  debug: true, // Enable the debug log
  version:'x.y.z' // Set the application version
})

CommonJS import

// Import using CommonJS
require('./build/wx.cjs');
App({
  umengConfig: {
    appKey: 'YOUR_APP_KEY',
    dsn:'YOUR_DATA_COLLECTION_DOMAIN',
    debug: true, // Enable the debug log
    version:'x.y.z' // Set the application version
  }
});

3.2 Method 2: Imperative method

This method is suitable for third-party frameworks like uni-app and Taro.

// Import using CommonJS
const uapm = require('./build/wx.cjs');
uapm.init({
  appKey: 'YOUR_APP_KEY',
  dsn:'YOUR_DATA_COLLECTION_DOMAIN',
  debug: true, // Enable the debug log
  version:'x.y.z' // Set the application version
});

4. Initialization parameters

Name

Required

Description

Type

Supported platforms

appKey

Yes

Unique identifier for your application.

string

WeChat, Alipay

dsn

Yes

Data collection domain for your APM service.

string

WeChat, Alipay

debug

No

Whether to print the debug log.

boolean

WeChat, Alipay

version

No

Application version. If omitted, the SDK uses the mini program's published version.

string

WeChat, Alipay

pageFilter

No

Filters page logs by blacklist or whitelist. If a page matches a rule, all its logs, including errors and requests, are filtered.

IFilter

WeChat, Alipay

errorFilter

No

Filters error logs by blacklist or whitelist.

IFilter

WeChat, Alipay

apiFilter

No

Filters request logs by blacklist or whitelist.

IFilter

WeChat, Alipay

rumConfig

No

Configures end-to-end request header injection.

RumConfig

WeChat, Alipay

IFilter type

pageFilter, errorFilter, and apiFilter all use the IFilter interface. Each filters a different target:

  • pageFilter: Filters page paths (path).

  • errorFilter: Filters stack traces.

  • apiFilter: Filters request URLs.

Configure either a whitelist or a blacklist policy for data collection. You cannot use both at the same time.

  • If you choose the whitelist policy, only items that match the rules are collected.

  • If you choose the blacklist policy, items that match the rules are excluded from collection.

This optional parameter controls log filtering and includes the following properties.

Property

Description

Default

Type

mode

ignore enables blacklist mode, where matching items are not reported. match enables whitelist mode, where only matching items are reported.

ignore

'ignore' | 'match'

rules

Array of matching rules. A match occurs if any rule is satisfied. A rule can be a string (substring match), RegExp (pattern test), or a Function that returns true.

[]. The default value is an empty blacklist, meaning all logs are reported.

string | RegExp | Function | Array<string | RegExp | Function>

RumConfig type

This optional parameter configures end-to-end tracing and includes the following properties.

Property

Description

Default

Type

injectTraceHeader

Request header format to inject into network requests. The SDK automatically generates the required protocol fields.

undefined

Enum

'traceparent' | 'b3' | 'sw8' | 'sentry-trace' | undefined

needTracedUrls

A whitelist of URLs for end-to-end trace header injection.

null. This indicates an empty whitelist. If a list of URLs is provided, headers are injected only into requests for those URLs.

Array<string | RegExp>

ignoredUrls

A blacklist of URLs to exclude from end-to-end trace header injection.

null. This indicates an empty blacklist. If a list of URLs is provided, headers are not injected into requests for those URLs.

Array<string | RegExp>

injectSDKRequest

Whether to inject request headers into the SDK's internal requests.

false. The SDK's internal requests do not have headers injected.

boolean

Instance methods

After initialization, the SDK creates a global $umapm instance. Call its methods through wx.$umapm for WeChat or my.$umapm for Alipay.

Method

Description

Type

Example

Supported platforms

setUserid

Sets the user ID.

Function

$umapm.setUserid('xxxx')

WeChat, Alipay

setPageFilter

Sets a blacklist or whitelist to filter which pages are reported.

Function

$umapm.setPageFilter({

mode: 'match',

rules: ['/home']

})

WeChat, Alipay

setApiFilter

Sets a blacklist or whitelist to filter which API requests are reported.

Function

$umapm.setApiFilter({

mode: 'ignore',

rules: ['/getUserInfo']

})

WeChat, Alipay

setErrorFilter

Sets a blacklist or whitelist for error collection.

Function

$umapm.setErrorFilter({

mode: 'ignore',

rules: ["script error"]

})

WeChat, Alipay

captureException

Manually captures and reports an exception.

Function

try {

throw new Error('Something went wrong') } catch (exception) { $umapm.captureException(exception);

}

WeChat, Alipay

5. Examples

Example 1

Set configuration parameters with the umengConfig property in App.

// wechat
const umapm = require('./wx.cjs');

App({
  umengConfig: {
    appKey: 'YOUR_APP_KEY',
    dsn:'YOUR_DATA_COLLECTION_DOMAIN',
    debug: true,
    version:'x.y.z',
    pageFilter: {
      mode: 'match',
      rules: ['/home']
    }
  },
  onLaunch: function () {
    wx.request({
      url: "https://xxx/getUserId",
      method: "post",
      success: (res) => {
        wx.$umapm.setUserid(res.data.userid);
      }
    })
  }
});

Example 2

Initialize the SDK by calling the init method directly.

// wechat
var umapm = require('./wx.cjs');
umapm.init({
  appKey: 'YOUR_APP_KEY',
  dsn:'YOUR_DATA_COLLECTION_DOMAIN',
  debug: true,
  version:'x.y.z',
  pageFilter: {
    mode: 'match',
    rules: ['/home']
  }
});

App({
  onLaunch: function () {
    wx.request({
      url: "https://xxx/getUserId",
      method: "post",
      success: (res) => {
        wx.$umapm.setUserid(res.data.userid);
      }
    });
  }
});

Example 3

Integrate the SDK with the uni-app framework using conditional compilation.

// Initialization parameter configuration
// #ifdef MP-WEIXIN
import { init } from "./wx.esm";
init({
  appKey: 'YOUR_APP_KEY',
  dsn: 'YOUR_DATA_COLLECTION_DOMAIN',
  version:'x.y.z',
  pageFilter: {
    mode: "ignore", 
    rules: []
  },
});
// #endif

// #ifdef MP-ALIPAY
import { init } from "./alipay.esm";
init({
  appKey: 'YOUR_APP_KEY',
  dsn: 'YOUR_DATA_COLLECTION_DOMAIN',
  version:'x.y.z',
  pageFilter: {
    mode: "ignore", 
    rules: [] 
  },
});
// #endif

// #ifdef H5
import { init } from "./apm";
init({
  pageFilter: { mode: "ignore", rules: [] },
  pid: "YOUR_H5_APP_KEY",
  logLevel:3,
});
// #endif

Import uapm.js in your main.js file.

import Vue from 'vue'
import App from './App'
import './uapm';

Vue.config.productionTip = false

App.mpType = 'app'

const app = new Vue({
  ...App
})
app.$mount()
Previous：Web SDKNext：JS Exception Capture Interpolation Tool