Installation

npm install @inceptionpad/frontend-monitor-web-sdk --save

import webMonitorSdk from '@inceptionpad/frontend-monitor-web-sdk';
const monitor = webMonitorSdk({
    appId: "xxx",
    api: "localhost:3000/api/v1/report/web",
    filterUrls: ['api/xxxx/xx'],
    errcodeReport(res) {
      if (Object.prototype.toString.call(res) === '[object Object]' && res.hasOwnProperty('errcode') && res.errcode !== 0) {
        return { isReport: true, errMsg: res.errmsg,code: res.errcode };
      }
      return { isReport: false };
    },
    isTraceId: true,
    traceIdHeaderName: 'x-trace-id';
})

Parameters

| Init Param | Type | Required | Default | Example | Description | | ------ | ------ | ------ | ------ | ------ | ------ | | appId | String | Required | - | - | The appId of the application | | api | String | Required | '' | https://localhost/web-monitor/api/v1/wx/report/wx | - | | filterUrls | Array | Optional | - | ['api/xx'] | Filter certain endpoints from being reported, e.g. polling requests. Uses fuzzy string matching (try to keep paths complete, fuzzy matching may affect other endpoints) | | errcodeReport (business error reporting) | Function | Optional | - | See example below | For requests where httpStatus is 200 but the business logic returns an error in the response body. E.g. errcode=1 means a backend error, which should be reported to the monitor | | isTraceId | boolean | Optional | false | - | Whether to enable traceId retrieval | | traceIdHeaderName (traceId field name in server response headers) | string | Optional | x-trace-id | - | The response headers need 2 fields: access-control-expose-headers: x-trace-id (allow frontend access); x-trace-id:bdDq1a.a123.12 |

Default filtered domains by SDK

Third-party analytics requests can generate a large amount of noise data. The monitor will not collect data from such endpoints by default. If you need to filter out specific endpoints that don't need monitoring, use filterUrls.

errcodeReport:

  webMonitorSdk({
    errcodeReport(res) {
      if (Object.prototype.toString.call(res) === '[object Object]' && res.hasOwnProperty('errcode') && res.errcode !== 0) {
        return { isReport: true, errMsg: res.errmsg,code: res.errcode };
      }
      return { isReport: false };
    }
  });

Note on positive vs. negative checks

We may use fetch or xmlHttpRequest to request any resource such as APIs, CSS, JS (or framework-initiated requests). The res received by errcodeReport could be a string, object, or other types. Stricter checks may be needed to correctly determine whether a business error should be reported.

For example:

Positive check: res.errcode===1

errcodeReport(res) {
  if (Object.prototype.toString.call(res) === '[object Object]' && res.errcode == 1) {
    return { isReport: true, errMsg: res.errmsg,code: res.errcode };
  }
  return { isReport: false };
}

Negative check: res.errcode!==0 — if hasOwnProperty is not used, responses without an errcode property would also be reported as errors (some business endpoints may not follow a strict response format)

errcodeReport(res) {
  if (Object.prototype.toString.call(res) === '[object Object]' && res.hasOwnProperty('errcode') && res.errcode !== 0) {
    return { isReport: true, errMsg: res.errmsg,code: res.errcode };
  }
  return { isReport: false };
}

Methods

setConfig: Set user info

You can set any one or more properties.

monitor.setConfig({
  p: '8877661112', // phone number
  uid: '100017' // user id
});

addError: Manually report an error

let message = 'js add error';
let col = 20;
let line = 20;
let resourceUrl = 'http://www.xxx.com/01.js';

monitor.addError({
  msg: message,
  col: col,
  line: line,
  resourceUrl: resourceUrl
});

addCustom: Custom event tracking

const monitor = webMonitorSdk({
    appId: "xxx",
    env: 'dev'
})
// Executes immediately by default. If you don't want it to execute immediately, set reportNow to false.
// The event will be queued and reported when report() is called elsewhere, on page change, or on the next API request.
// reportNow defaults to true, optional parameter
monitor.addCustom({
    customName: 'mgStart-getUserInfo',
    customContent: {
      userId: 123,
      system: {
        version: '1.2'
      }
    },
    /*
      Optional field. Custom filter conditions, must be an object (otherwise invalid).
      Manually select specific fields to upload.
      The monitor backend uses the filter fields to query custom parameters.
      Fields in customContent that you want to filter by later should be passed here.
      Note: customFilter only supports 1 level of nesting.
    */
    customFilter: {
      userId: 123,
      version: '1.2'
    }
}, reportNow);

Cross-origin error details unavailable

When loading cross-origin script resources that contain JS errors, the SDK's global window.onerror cannot capture detailed error info — it will only receive Script error. The fix is to add the crossorigin attribute to the cross-origin <script> tag, and configure the server to set the appropriate CORS headers for the resource.

SDK reports the following performance data

• url: The current page URL
• preUrl: The URL of the previous page
• performance: Page performance details — see field descriptions below
• errorList: Page error details including js, img, ajax, fetch errors — see field descriptions below
• resoruceList: Resource performance details for all resources on the current page — see field descriptions below
• markUv: UV tracking identifier
• markUser: Tracks the user from site entry until they leave; can be used for funnel analysis
• time: Current report timestamp
• screenWidth: Screen width
• screenHeight: Screen height
• isFristIn: Whether this is the first entry of a session
• type: Report type — 1: page-level performance, 2: page ajax performance, 3: page error reporting