应用性能监控全链路版
应用性能监控全链路版
文档指南
请输入
- 文档首页
应用性能监控全链路版用户指南客户端监控WebPro 端监控SDK 接入使用 SDK 调用 API
复制全文
下载 pdf使用 SDK 调用 API
文档反馈
问问助手本文介绍如何在WebPro中使用SDK调用API。
注意事项
初始化
初始化client实例，初始化配置中可以包含通用事件上下文，通用事件上下文以外的配置只生效一次。
init调用后会开始拉取服务端配置，并拉取异步加载的插件。
client('init', c: InitConfig) => void
interface InitConfig {
aid: number; // 项目唯一标识，必传
token: string; // 项目 token，必传
// 通用事件上下文
pid?: string;
userId?: string; // 不传时将会生成uuid作为userId。（请勿显示传入undefined,显示传入undefined代表不传userId并拒绝生成uuid，所有上传请求中将不包含userId）
deviceId?: string; // 不传时将会生成uuid作为deviceId。如果业务自行传入请确保传入值尽量不含特殊字符。（可含有点，斜杠，横杠，下划线，逗号）。（请勿显示传入undefined,显示传入undefined代表不传deviceId并拒绝生成uuid，所有上传请求中不包含deviceId）
release?: string; // 用于区分不同版本。如果传入，请确保传入值长度小于17且尽量不含特殊字符。（可含有点，斜杠，横杠，下划线，逗号）
env?: string; // 用于区分不同环境。如果传入，请确保传入值尽量不含特殊字符。（可含有点，斜杠，横杠，下划线，逗号）
useLocalConfig?: boolean; // 是否只使用本地配置，默认为关
storageExpires?: number | boolean;// 配置 storage 的过期时间，默认为 90 天
// 采样配置 和 插件配置 的具体配置可在详细配置中查看
sample?: SampleConfig; // 采样配置
plugins?: { ... }; // 具体可以查看 【配置插件】
// 特殊配置
pluginBundle?: {
name: string;
plugins: string[];
}; // 插件打包加载配置，非定制插件不需要配置
pluginPathPrefix?：string; // 插件加载路径前缀，调试用（比如 http://localhost:8081/cn/plugins）或加载定制插件用
domain?: string; // 上报域名。中国发布的应用：上报到中国大陆服务器，域名为https://apmplus.volces.com。海外发布的应用，上报到马来西亚柔佛服务器，域名为https://apmplus.ap-southeast-1.volces.com。如不配置，默认上报到中国大陆服务器。
}
示例
client('init', {
aid: 123456, // 你的 aid
token:'xxx-xxx', // 替换成你的token
env: 'boe',
release: '1.0.221'
})
更新配置
更改通用上下文，仅对更新后发送的事件生效。如果需要对所有事件生效，请确保在start之前调用。
client('config', c?: Partial) =>WebConfig
// config 可以改动的配置
interface UserConfig {
pid: string;
userId: string;
deviceId: string;
sessionId：string;
release: string;
env: string;
}
// config 获取的配置
interface WebConfig {
aid: number; // 项目唯一标识，必传
token: string; // 项目 token，必传
// 通用事件上下文
pid: string;
userId: string;
deviceId: string;
sessionId: string; // 区分不同会话
release: string;// 区分不同版本
env: string;// 区分不同环境
useLocalConfig: boolean; // 是否只使用本地配置，默认为关
storageExpires?: number | boolean; // 配置 storage 的过期时间，默认为 90 天
// 采样配置 和 插件配置 的具体配置可在详细配置中查看
sample: SampleConfig; // 采样配置
plugins: { ... }; // 插件配置
// 特殊配置
pluginBundle: {
name: string;
plugins: string[];
}; // 插件打包加载配置，非定制插件不需要配置
pluginPathPrefix：string; // 插件加载路径前缀，调试用（比如 http://localhost:8081/cn/plugins）或加载定制插件用
domain?: string; // 上报域名，Saas不需要配置, 私有化部署时需要配制成具体环境的上报域名
}
示例
// 更新配置
client('config', {
userId: 'test_user',
})
// 获取SDK当前配置，如果SDK还未init，则会返回undefined
const config = client('config')
开启上报
client('start')
设置全局上下文
设置自定义维度。context是一个全局维度的上下文，对所有事件生效。更新的context只对之后发生的事件生效。
client("context.set", "key", "value"); // 设置context中的单个key
client("context.merge", { key: "value" }); // 将context 和 传入的对象合并，生成新的context
client("context.delete", "key"); // 删除context中的某个key
client("context.clear"); // 清空context
- 如果想要给一些初始化的上下文，需要在init之前设置context。因为init的时候会发送一些事件，例如pageview。
- 如果需要在init之后设置context，又希望能对所有上报生效，可以使用refreshPreStartContext插件。
上报PV
上报一次PV，若pid与当前pid相同则会忽略此次PV。
client('sendPageview',pid: string) => void
示例
client('sendPageview', '/test/pageA')
上报自定义事件
client('sendEvent', data: CustomEventPayload) => void
interface CustomEventPayload {
/** 自定义事件名称 */
name: string;
/** metrics 上报的是可以被度量的值，也就是数值 */
metrics?: { [key: string]: number };
/** categories 上报的是分类，维度，用来做筛选，分组 */
categories?: { [key: string]: string };
}
示例
client('sendEvent', {
name: 'login_event',
metrics: {
login_count: 1,
login_api_duration: 1000,
server_timing: 3456,
login_level: 23,
},
categories: {
where: 'login_page',
},
})
上报自定义日志
上报一个自定义日志。注意格式，格式不符合的事件将会试图转换，无法转换的事件将会被忽略。
client('sendLog', data: CustomLogPayload) => void
interface CustomLogPayload {
/** 额外的附加信息， 在上报的时候 number会被分流到metric string会被分流到categories */
extra?: { [key: string]: string | number }; //
/** 自定义事件内容，任意字符串，可以是日志或者对象的 JSON 字符串等等 */
content: string;
/** 自定义事件级别，默认是 info, 可枚举项 debug | info | warn | error */
level?: "debug" | "info" | "warn" | "error";
}
示例
client('sendLog', {
level: 'error',
content: `user loggedin from ${prev}`,
extra: {
where: 'login_page',
},
})
上报JS错误
client('captureException', error: any, extra?: { [key: string]: string }, react?: ReactInfo) => void
export interface ReactInfo {
version: string;
componentStack: string;
}
示例
// 上报一个error
client('captureException', new Error('test error'))
// 上报一个错误信息
client('captureException', 'custom error')
// 上报一个error，同时附带一些错误的上下文
client('captureException', new Error('login error'), { loginId: 'xxxxx' })
上报性能指标
- 如果是默认集成的指标，例如FP、FCP，可以在Performance插件中关闭上报，通过这种自定义上报的方式上报上去，平台自动消费。
- 如果不是默认集成的指标，通过这种自定义上报的方式上报上去后，在性能指标管理中注册指标，即可在平台消费。
client('sendCustomPerfMetric', metric: PerformancePayload) => void
interface PerformancePayload {
/** 指标名称 */
name: string;
/** 当前值 */
value: number;
/** 性能指标类型， perf => 传统性能, spa => SPA 性能, mf => 微前端性能 */
type?: string = "perf";
/** 是否支持 */
isSupport?: boolean;
/** 是否是Polyfill */
isPolyfill?: boolean;
/** 是否跳出 */
isBounced?: boolean;
/** 是否自定义 */
isCustom?: boolean;
/** 指标的相关信息 */
extra?: { [key: string]: string };
}
示例
client('sendCustomPerfMetric', { name: 'fcp', value: 3500 }
销毁实例
调用此方法可以去掉所有监听和副作用，包括hook或者内存对象。当前实例本身还是可用的，所以手动调用API依然可以上报数据。
client('destroy')
上报任意事件
client('report', ev: ReportEvent) => void
示例
client('report', {
ev_type: 'pageview',
payload: {
source: 'history',
pid: '/pageB'
}
})
自定义补充面包屑
面包屑主要在JS错误上报时会携带，如果业务想要自定义一些面包屑，可以使用下面的方式。
client('addBreadcrumb',breadcrumb: Breadcrumb) => void
export interface Breadcrumb {
/** dom | http */
type: string;
/** xpath, keyvalue | url */
message: string;
/** ui.click, ui.keypress | post,get */
category: string;
/** status: 400 for http */
data?: { [key: string]: string };
}
示例
client('addBreadcrumb', { type: 'custom', message: 'user login', category: 'webview' })
手动包装Fetch
client('wrapFetch', fetch: typeof window.fetch) => typeof window.fetch ｜ undefined
如果需要手动包装，需要注意以下内容：
- 需要在init之后执行。因为wrapFetch是动态挂载的，挂载的时机是在init时，所以需要在init后执行。
- 需要使用npm的接入方式。script接入会先加载主脚本，在这之前所有的调用都只是缓存起来，并没有真正运行，所以提前运行拿到的返回值会是undefined。
- 需要将fetch插件的autoWrap配置为false。既然选择手动包装，那么就要避免自动包装带来的其他无关请求的监控上报。
示例
import client from '@apmplus/web'
client('init', {
...
plugins: {
autoWrap: false,
},
...
})
const fetchAfterWrap = client('wrapFetch', window.fetch)
// then, use fetchAfterWrap to request
手动检测白屏
client('detectBlankScreen')
示例
import client from '@apmplus/web'
client('init', {
...
plugins: {
blankScreen: {
// 关闭自动检测，改为下方的手动检测
autoDetect: false
},
},
...
})
client('detectBlankScreen')
立即上报数据
默认情况下，在页面关闭时SDK会使用sendBeacon强制发送缓存队列的数据，但是如果在页面关闭时，用户再手动调用某些API上报数据，可能因为时机问题导致漏发，可以使用以下方式强制发送数据：
import client from '@apmplus/web'
// 写在回调里时为了确保SDK已经初始化完成，避免报错
onPageUnload(() => {
client('on', 'init', () => {
client.getSender().flush()
})
})
最近更新时间：2025.10.23 17:10:38
这个页面对您有帮助吗？
有用
有用
无用
无用