Web SDK

SDK接入流程

注意：在完成Web端接入前，需要先获取Web端appkey。

SDK接入说明

Web 端SDK接入方式有两种：CDN和NPM

注意：

1. CDN下载地址：APM H5 SDK

2. npm命令：npm install lydaas_apm --save

3. 内网环境，请将SDK中的js文件上传到内网的静态资源服务器上，并将集成代码中的CDN地址替换为内网js文件的URL地址

通过CDN在线部署

同步加载和异步加载区别

异步加载：又称为非阻塞加载，表示浏览器在下载执行JS之后还会继续处理后续页面。若对页面性能的要求非常高，建议使用此方式。（异步加载无法捕捉到SDK加载初始化完成之前的JS错误和资源加载错误）

同步加载：又称为阻塞加载，表示当前JS加载完毕后才会进行后续处理。如需捕捉从页面打开到关闭的整个过程中的JS错误和资源加载错误，建议使用此方式

异步加载

情景一：通过CDN异步引入SDK后，设置初始化参数。

<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: '应用唯一标识',
    //注意：域名前需要添加"https://" 
    dsn: '收数域名',
    pageFilter: { mode: 'ignore', rules: [] },
    //更多配置见第二步参数说明
  });
</script>

情景二：在SDK引入之前设置初始化参数

<script>
  window._apm = window._apm || {
    p:[[
      'create', {
       pid: '应用唯一标识',
       //注意：域名前需要添加"https://"
       dsn: '收数域名',
       pageFilter: {
         mode: 'ignore',
         rules: [],
       },
       //更多配置见第二步参数说明
    }]],
  };
</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>

同步加载

<script>
  window._um_apm_namespace = '_apm';
  window[_um_apm_namespace] = window[_um_apm_namespace] || {
    p: [],
  };
  window[_um_apm_namespace].p.push([
    'create',
    {
      //注意：域名前需要添加"https://"
      dsn: '收数域名',
      pid: '应用唯一标识',
      pageFilter: {
        mode: 'ignore',
        rules: [],
      },
      //更多配置见第二步参数说明
    },
  ]);
</script>

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

通过NPM方式集成SDK

初始化调用示例

注意：域名前需要添加"https://"

import { init } from 'lydaas_apm';

init({
  pid: '应用唯一标识',
  //注意：域名前需要添加"https://"
  dsn: '收数域名',
  pageFilter: {
    mode: 'ignore',
    rules: []
  },
  errorFilter: {
    mode: 'ignore',
    rules: []
  },
  puid: "user@example.com", // 接入方平台用户账号
  tag: "", // 自定义标签
  logLevel: 0, // 日志级别; 0表示error、1表示warn、2表示info、3表示debug
  enableBlankScreen: true, // 是否开启白屏统计
  blankConfig: {
    blank_target: 'body', // 检测白屏DOM根节点
    blank_timeout: 6000, // 检测设置的白屏DOM根节点是否有像素显示的等待时间，单位为毫秒(ms)
    screenshot: true, // 是否发送白屏的截图
    X: 1.5, // 判断是否发送截屏，如果DOM得分小于设定的值，会发送截屏数据
    Y: 6, // 判断是否发送白屏日志，如果DOM得分小于设定值，会发送白屏日志
  }
});

设置/修改初始化参数

设置应用唯一标识（appkey）

必填

设置用户产品线标志tag（可选）

设置SDK采集服务地址

必填

黑白名单设置pageFilter（可选）

您可以设置采集的H5页面黑白名单模式，黑名单和白名单二选一：

• 若选择白名单模式，仅符合规则的页面会被采集

• 若选择黑名单模式，则符合规则的页面不会被采集

此项非必须参数，用于根据页面地址判断是否过滤日志，包含如下属性

黑白名单设置errorFilter（可选）

该功能用于配置H5页面的采集黑白名单。您可以选择白名单或黑名单模式：

• 若选择白名单模式，仅符合配置规则的页面会被采集

• 若选择黑名单模式，符合配置规则的页面将被排除，不会被采集

此项非必须参数，用于根据自定条件判断是否过滤日志，包含如下属性

黑白名单设置apiFilter (可选)

该功能用于设置api请求日志黑白名单，根据设置的黑白名单，过滤xhr和fetch的请求url，仅对api日志生效

设置api请求参数（可选）

xhrConfig

fetchConfig

输出日志等级（可选）

非必填，表示js日志输出日志等级

白屏检测（可选）

非必填，用于设置白屏检测标准、截屏功能等相关配置

blankConfig

开启全链路请求注入（可选）

非必填，用于对H5应用内业务请求注入httpHeader。

注意：通过sendAPILog主动发起的请求日志不支持httpHeader注入

rumConfig

方法说明

1. 用户手动捕捉并上报错误日志

captureException

调用方法，通过CDN引入的使用以下方式调用

_apm && _apm('captureException', new Error('手动捕捉'));

通过npm引入的使用以下方式来调用

import { captureException } from 'lydaas_apm';
try {
  throw new Error('开发者手动捕捉到的错误');
} catch (error) {
  captureException(error);
}

在vue中的使用示范如下，以vite创建的工程为例，在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) => {
    // 处理错误，例如：报告给一个服务
    captureException(err);
};
app.mount('#app');

2. 用户手动上报API请求日志

sendAPILog

（该api调用要求版本不低于2.0.10）

调用方法，通过CDN引入的使用以下方式调用

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

通过npm引入的使用以下方式来调用

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. 设置用户标识（可选）

通过CDN引入，异步加载

<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>
  // 此处为用户可以在自己的业务代码中设置
  _apm('set', 'puid', '用户账号');
</script>

通过CDN引入，同步加载

<script>
  window._um_apm_namespace = '_apm';
  window[_um_apm_namespace] = window[_um_apm_namespace] || {
    p: [],
  };
  window[_um_apm_namespace].p.push([
    'create',
    {
      //注意：域名前需要添加"https://"
      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', '用户账号']);
</script>

通过npm引入

import { setUserConfig } from 'lydaas_apm';
setUserConfig({puid:"用户账号"});

附录：兼容性说明

浏览器和平台兼容性