Quick Tracking:Web SDK

SDK access process

Note: Before you connect to the web, you must obtain the web appkey.

SDK access description

There are two ways to access the web SDK: Alibaba Cloud Content Delivery Network and NPM

Note:

1. Alibaba Cloud Content Delivery Network download address: APM H5 SDK

2. npm command: npm install lydaas_apm --save

3. In the internal network environment, upload the js file in the SDK to the static resource server on the internal network and replace the Alibaba Cloud Content Delivery Network URL in the integration code with the URL of the js file on the internal network.

Through Alibaba Cloud Content Delivery Network Online Deployment

Differences between synchronous loading and asynchronous loading

Asynchronous loading: indicates that the browser continues to process subsequent pages after the JS is downloaded and executed. If you have very high requirements on page performance, we recommend that you use this mode. (JS errors and resource loading errors before the SDK loading initialization is completed cannot be captured in asynchronous loading

Synchronous loading: This method is also known as blocking loading. It indicates that subsequent processing is performed only after the current JS is loaded. If you want to capture JS errors and resource loading errors during the entire process from page opening to page closing, we recommend that you use this method.

Asynchronous loading

Scenario 1: Set the initialization parameters after you asynchronously introduce the SDK by using the Alibaba Cloud Content Delivery Network.

<script>
  void (function (e, t, n, a, o, i, m) {
    (e._um_apm_namespace = o),
    (e[o] = e[o] || function () {
          (e[o].q = e[o].q || []).push(arguments);
    }),
    (e[o].l = e[o].l || +new Date()),
    (i = t.createElement(n)),
    i.setAttribute('crossorigin', ''),
    (i.src = a),
    (m = t.getElementsByTagName(n)[0]),
    m.parentNode.insertBefore(i, m);
  })(
    window,
    document,
    'script',
    'https://g.alicdn.com/QTSDK/oxm-web-apm/2.1.1/es5/uapm.iife.js',
    '_apm',
  );
  _apm('create', {
    pid: 'Unique identifier of the application',
    // Note: You need to add "https://" before the domain name. 
    dsn: 'Collection domain name',
    pageFilter: { mode: 'ignore', rules: [] },
    // For more information, see Step 2.
  });
</script>

Scenario 2: Set initialization parameters before the SDK is introduced

<script>
  window._apm = window._apm || {
    p:[[
      'create', {
       pid: 'Unique identifier of the application',
       // Note: You need to add "https://" before the domain name.
       dsn: 'Collection domain name',
       pageFilter: {
         mode: 'ignore',
         rules: [],
       },
       // For more information, see Step 2.
    }]],
  };
</script>

<script>
  void (function (e, t, n, a, o, i, m) {
    (e._um_apm_namespace = o),
    (e[o] = e[o] || function () {
      (e[o].q = e[o].q || []).push(arguments);
    }),
    (e[o].l = e[o].l || +new Date()),
    (i = t.createElement(n)),
     i.setAttribute('crossorigin', ''),
    (i.src = a),
    (m = t.getElementsByTagName(n)[0]),
     m.parentNode.insertBefore(i, m);
  })(
    window,
    document,
    'script',
    'https://g.alicdn.com/QTSDK/oxm-web-apm/2.1.1/es5/uapm.iife.js',
    '_apm',
  );
</script>

Synchronous loading

<script>
  window._um_apm_namespace = '_apm';
  window[_um_apm_namespace] = window[_um_apm_namespace] || {
    p: [],
  };
  window[_um_apm_namespace].p.push([
    'create',
    {
      // Note: You need to add "https://" before the domain name.
      dsn: 'Collection domain name',
      pid: 'Unique identifier of the application',
      pageFilter: {
        mode: 'ignore',
        rules: [],
      },
      // For more information, see Step 2.
    },
  ]);
</script>

<script src="https://g.alicdn.com/QTSDK/oxm-web-apm/2.1.1/es5/uapm.iife.js" crossorigin></script>

Integrate the SDK by using NPM

Initialization call example

Note: Add "https://" before the domain name.

import { init } from 'lydaas_apm';

init({
  pid: 'Unique identifier of the application',
  // Note: You need to add "https://" before the domain name.
  dsn: 'Collection domain name',
  pageFilter: {
    mode: 'ignore',
    rules: []
  },
  errorFilter: {
    mode: 'ignore',
    rules: []
  },
  puid: "user@example.com", // The account of the user on the accessing platform.
  tag: "", // The custom tag.
  logLevel: 0, // The log level. 0 indicates error, 1 indicates warn, 2 indicates info, and 3 indicates debug.
  enableBlankScreen: true, // Specifies whether to enable white screen statistics.
  blankConfig: {
    blank_target: 'body', // Detect the root node of the white screen DOM.
    blank_timeout: 6000, // The waiting time for the root node of the white DOM to check whether pixels are displayed. Unit: milliseconds.
    screenshot: true, // Specifies whether to send a snapshot of a white screen.
    X: 1.5, //Determine whether to send screenshots. If DOM score is less than the set value, screenshots will be sent.
    Y: 6, // Determine whether to send a white screen log. If the DOM score is less than the specified value, a white screen log is sent.
  }
});

Set or modify initialization parameters

The unique identifier (appkey) of the application.

Required

Optional. Set the product line tag

Set the SDK collection service address

Required

(Optional) Set the pageFilter parameter for the blacklist and whitelist.

You can set the blacklist and whitelist mode on the H5 page. You can select one of the blacklist and whitelist modes.

• If you select the whitelist mode, only pages that meet the rules are collected.

• If you select the blacklist mode, pages that meet the rules are not collected.

This optional parameter is used to determine whether to filter logs based on the page address. The following properties are included

(Optional) Set errorFilter for the blacklist and whitelist.

This feature is used to configure the collection blacklist and whitelist on the H5 page. You can select the whitelist or blacklist mode:

• If you select the whitelist mode, only pages that meet the configured rules are collected.

• If the blacklist mode is selected, the pages that meet the configured rules will be excluded and will not be collected.

This optional parameter is used to determine whether to filter logs based on custom conditions. The following properties are included

(Optional) Set the apiFilter parameter for the blacklist and whitelist

This function is used to configure the blacklist and whitelist of API request logs. Based on the configured blacklist and whitelist, the request URLs of xhr and fetch are filtered. This function takes effect only for API logs.

Set API request parameters (optional)

xhrConfig

fetchConfig

Output log level (optional)

Optional. This indicates the output log level of js logs.

White screen detection (optional)

Optional. This field is used to set the white screen detection standard and screen capture function.

blankConfig

Enable end-to-end request injection (optional)

Optional. This field is used to inject httpHeader to service requests in H5 applications.

Note: Requests initiated by using sendAPILog do not support httpHeader injection.

rumConfig

Method description

1. Users manually capture and report error log

captureException

method, which is introduced by the Alibaba Cloud Content Delivery Network using the

_apm && _apm ('Capture', new captureException ('Manual Capture'));

Invoking the

import { captureException } from 'lydaas_apm';
try {
  throw new Error ('Error caught manually by developer');
} catch (error) {
  captureException(error);
}

The use of vue is demonstrated as follows, taking the project created by vite as an example, in main.js

import { createApp } from 'vue';
import './style.css';
import App from './App.vue';
import { init, captureException } from 'lydaas_apm';

init({
  pageFilter: {
    mode: 'ignore',
    rules: [],
  },
  pid: 'test124',
  dsn: '//aplus2-portal-lite.emas-poc.com',
  logLevel: 4,
});

const app = createApp(App);
app.config.errorHandler = (err, instance, info) => {
    // Handle errors, e.g. report to a service
    captureException(err);
};
app.mount('#app');

2. Manually report API request logs

sendAPILog

(The API version must be 2.0.10 or later.)

method, which is introduced by the Alibaba Cloud Content Delivery Network using the

_apm && _apm('sendAPILog', {
    url: 'https://example.com/getUserName',
    method: 5,
    rc: 500,
    rt: 2000,
    traceid: '1234567',
    req_body: '{a:1}',
    req_query: '&aaa=1'
});

Invoking the

import { sendAPILog } from 'lydaas_apm';

sendAPILog({
    url: 'https://example.com/getUserName',
    method: 5,
    rc: 500,
    rt: 2000,
    traceid: '1234567',
    req_body: '{a:1}',
    req_query: '&aaa=1'
});

3. Optional. Set the user ID.

Introduced by Alibaba Cloud Content Delivery Network, asynchronous loading

<script>
  void (function (e, t, n, a, o, i, m) {
    (e._um_apm_namespace = o),
    (e[o] = e[o] || function () {
      (e[o].q = e[o].q || []).push(arguments);
    }),
    (e[o].l = e[o].l || +new Date()),
    (i = t.createElement(n)),
     i.setAttribute('crossorigin', ''),
    (i.src = a),
    (m = t.getElementsByTagName(n)[0]),
     m.parentNode.insertBefore(i, m);
  })(
    window,
    document,
    'script',
    'https://g.alicdn.com/QTSDK/oxm-web-apm/2.1.1/es5/uapm.iife.js',
    '_apm',
  );
  _apm('create', {
    pid: 'appkey',
    dsn: 'https://example.com',
    pageFilter: { mode: 'ignore', rules: [] },
  });
</script>

<script>
  // You can set this in your own business code.
  _apm('set', 'puid', 'user account');
</script>

Through Alibaba Cloud Content Delivery Network introduction, synchronous loading

<script>
  window._um_apm_namespace = '_apm';
  window[_um_apm_namespace] = window[_um_apm_namespace] || {
    p: [],
  };
  window[_um_apm_namespace].p.push([
    'create',
    {
      // Note: You need to add "https://" before the domain name.
      dsn: 'https://example.com',
      pid: 'appkey',
      pageFilter: {
        mode: 'ignore',
        rules: [],
      },
    },
  ]);
</script>
<script src="https://g.alicdn.com/QTSDK/oxm-web-apm/2.1.1/es5/uapm.iife.js" crossorigin></script>

<script>
  window[_um_apm_namespace].p.push(['set', 'puid', 'user account']);
</script>

Introduced by npm

import { setUserConfig } from 'lydaas_apm';
setUserConfig({puid:"user account"}); 

Appendix: Compatibility description

Browser and platform compatibility