文档

Web SDK

更新时间:

SDK接入流程

步骤

集成内容

本文中的位置

是否必选

附加说明

第一步

SDK获取

查看文档「第一步SDK接入说明」

必选

提供NPM和CDN两种方式,根据自身环境选择其一即可

第二步

设置初始化参数

查看文档 [第二设置初始化参数-设置应用唯一标识(appkey)」

必选

设置初始化参数

查看文档 [第二步设置初始化参数-设置收数服务地址」

必选

设置初始化参数

查看文档 [第二步设置初始化参数

黑白名单设置pageFilter

可选

通过设置pageFilter完成对日志的过滤

设置初始化参数

查看文档 [第二步设置初始化参数输出日志等级」

可选

附录

兼容性说明

查看文档 [附录兼容性说明」

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

第一步SDK接入说明

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

注意:

  1. CDN下载地址:https://g.alicdn.com/jssdk/apm/2.0.10/es5/uapm.iife.js

  2. npm命令 npm install @umengfe/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/jssdk/apm/2.0.10/es5/uapm.iife.js", "_apm");
 _apm('create',{
   pid:'appkey',
   dsn:'https://example.com',
   pageFilter: { mode: 'ignore', rules: [] },
 });
</script>
 

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

<script>
  window._apm = window._apm || {
   p: [
   [
   'create',
   {

   //注意:域名前需要添加"https://"
   dsn:'https://example.com',
   pid:'appkey',
   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/jssdk/apm/2.0.10/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:'https://example.com',
   pid:'appkey',
   pageFilter: {
   mode: 'ignore',
   rules: [],
   },
   },
  ]);
</script>
<script src="https://g.alicdn.com/jssdk/apm/2.0.10/es5/uapm.iife.js" crossorigin></script>

方式二:通过npm集成

在终端执行如下命令安装SDK @umengfe/apm@联系产品获取SDK版本号

npm install @umengfe/apm --save
ESM方式使用
import { init } from '@umengfe/apm';
init({
 pageFilter: { mode: 'ignore', rules: [] },
 pid:'appkey',
 dsn:'https://example.com',
});
CJS调用方式
const APM = require('@umengfe/apm');
APM.init({
 pageFilter: { mode: 'ignore', rules: [] },
 pid:'appkey',
 dsn:'https://example.com',
});

第二步设置/(修改)初始化参数

如您使用CDN方式,则已复制完毕初始化代码,可按照下面方式进行参数修改;

如您使用npm方式,则需要复制下面的初始化代码,并按照下面方式进行参数设置

初始化说明

初始化方法,调用示意

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

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

参数如下

设置应用唯一标识(appkey)

必填

属性

含义

默认

类型

pid

接入应用唯一标识(appkey)

-

string

设置用户产品线标志tag(可选)

属性

含义

默认

类型

tag

设置产品线标识id,可以在同一个appkey下区分不同的产品线,方便开发者排查问题

-

string

设置SDK采集服务地址

私有化部署时必填

属性

含义

默认

类型

dsn

SDK采集服务地址

string

黑白名单设置pageFilter(可选)

用于设置采集的H5页面黑白名单,可以在黑名单和白名单中选择其一,如果选择白名单的方式,那么只有符合标准的页面会被采集,如果选择的是黑名单的方式,那么符合标准的页面不会被采集

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

属性

含义

默认

类型

mode

匹配模式

当值为ignore,表示黑名单模式,命中规则的不上报 、当值为match,表示白名单模式命中规则的上报

ignore

枚举值 ignore|match

rules

匹配规则集合,当类型为string时,表示包含当页面URL包含该字符串时命中规则;当类型为Funtion,该函数返回true表示命中规则,false表示未命中规则;当类型为数组时,表示规则集合,规则之间为或的关系,只要任意一个规则命中,则规则集命中。

[],该默认值表示黑名单为空,日志全部上报

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

黑白名单设置errorFilter(可选)

用于设置采集的H5页面错误黑白名单,可以在黑名单和白名单中选择其一,如果选择白名单的方式,那么只有符合匹配条件的错误日志会被采集,如果选择的是黑名单的方式,那么符合匹配条件的错误日志将不会被采集

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

属性

含义

默认

类型

mode

匹配模式

当值为ignore,表示黑名单模式,命中规则的不上报 、当值为match,表示白名单模式命中规则的上报

ignore

枚举值 ignore|match

rules

匹配规则集合,当类型为string时,表示包含当页面URL包含该字符串时命中规则;当类型为Funtion,该函数返回true表示命中规则,false表示未命中规则;当类型为数组时,表示规则集合,规则之间为或的关系,只要任意一个规则命中,则规则集命中。

[],该默认值表示黑名单为空,日志全部上报

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

输出日志等级(可选)

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

属性

含义

默认

类型

logLevel

日志等级

0

枚举值

0 表示ERROR日志

1 表示WARN日志

2 表示INFO日志

3 表示DEBUG日志

第三步方法说明

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

captureException

调用方法,通过CDN引入的使用以下方式调用
_apm && _apm('captureException', new Error('手动捕捉'));
通过npm引入的使用以下方式来调用
import { captureException } from '@umengfe/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 '@umengfe/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 '@umengfe/apm';

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

属性

含义

必填项

类型

举例

url

请求地址

必填

string

https://u.shujupie.com/d

method

请求方法

1: 'GET'

2: 'POST'

3: 'PUT'

4: 'HEAD'

5: 'DELETE'

6: 'CONNECT'

7: 'OPTIONS'

8: 'TRACE'

9: 'PATCH'

必填

int

2

rt

请求耗时(毫秒)

必填

long

3000

rc

响应编码

必填

int

200

traceid

请求追踪id

选填

string

abcdef

req_query

入参query

选填

string

string

req_body

入参body (仅状态码>400 且不等于0 采集上报,其它状态为空)

选填

string

string

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/jssdk/apm/2.0.10/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/jssdk/apm/2.0.10/es5/uapm.iife.js" crossorigin></script>

<script>
  window[_um_apm_namespace].p.push([
      'set',
      'puid',
      '用户账号'
  ]);
</script>
通过npm引入
import { setUserConfig } from '@umengfe/apm';
setUserConfig({puid:"用户账号"});

附录:兼容性说明

浏览器和平台兼容性

浏览器/平台

支持版本

Safari

Safari 9+

Chrome

Chrome 49+

IE

IE 9+

Edge

Edge 12+

Firefox

Firefox 36+

Opera

Opera 43+

Safari for iOS

Safari for iOS 9.3.2+

Android Browser

android_webkit 4.4.2+

  • 本页导读 (0)