如何接入WebSDK,接入流程是什么_全域采集与增长分析(Quick Tracking)-阿里云帮助中心

SDK接入流程

步骤	集成内容	本文中的位置	是否必选	附加说明
第一步	SDK获取	查看文档「第一步SDK接入说明」	必选	提供NPM和CDN两种方式，根据自身环境选择其一即可
第二步	设置初始化参数	查看文档 [第二设置初始化参数-设置应用唯一标识（appkey）」	必选
	设置初始化参数	查看文档 [第二步设置初始化参数-设置收数服务地址」	必选
	设置初始化参数	查看文档 [第二步设置初始化参数黑白名单设置pageFilter」	可选	通过设置pageFilter完成对日志的过滤
	设置初始化参数	查看文档 [第二步设置初始化参数输出日志等级」	可选
附录	兼容性说明	查看文档 [附录兼容性说明」

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

第一步SDK接入说明

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

注意：

CDN下载地址：https://g.alicdn.com/jssdk/apm/2.0.10/es5/uapm.iife.js
npm命令 npm install @umengfe/apm --save
内网环境，请将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表示未命中规则;当类型为数组时，表示规则集合,规则之间为或的关系，只要任意一个规则命中，则规则集命中。

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

黑白名单设置errorFilter（可选）

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

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

属性

含义

默认

类型

mode

匹配模式

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

ignore

枚举值 ignore|match

rules

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

输出日志等级（可选）

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

属性

含义

默认

类型

logLevel

日志等级

枚举值

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+