本文介绍如何在WebPro中使用SDK调用API。 ## **注意事项** 全文的`client`代表的是SDK实例。如何获取SDK实例，请参见[SDK接入](https://www.volcengine.com/docs/6431/104857)。 ### 初始化初始化client实例，初始化配置中可以包含通用事件上下文，通用事件上下文以外的配置只生效一次。 init调用后会开始拉取服务端配置，并拉取异步加载的插件。 **client('init', c: InitConfig) =\> void** ```TypeScript interface InitConfig { aid: number; // 项目唯一标识，必传 token: string; // 项目 token，必传 // 通用事件上下文 pid?: string; userId?: string; deviceId?: 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; // 上报域名。中国发布的应用：上报到中国大陆服务器，域名为https://apmplus.volces.com。海外发布的应用，上报到马来西亚柔佛服务器，域名为https://apmplus.ap-southeast-1.volces.com。如不配置，默认上报到中国大陆服务器。 } ``` #### 示例 ```TypeScript client('init', { aid: 123456, // 你的 aid token:'xxx-xxx', // 替换成你的token env: 'boe', release: '1.0.221' }) ``` ### 更新配置更改通用上下文，仅对更新后发送的事件生效。如果需要对所有事件生效，请确保在start之前调用。 **client('config', c?: Partial) =\>WebConfig** ```TypeScript // 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不需要配置, 私有化部署时需要配制成具体环境的上报域名 } ``` #### 示例 ```TypeScript // 更新配置 client('config', { userId: 'test_user', }) // 获取SDK当前配置，如果SDK还未init，则会返回undefined const config = client('config') ``` ### 开启上报 ```JavaScript client('start') ``` ### 设置全局上下文设置自定义维度。context是一个全局维度的上下文，对所有事件生效。更新的context只对之后发生的事件生效。 ```TypeScript 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](https://www.volcengine.com/docs/6431/108981#refreshPreStartContext)插件。 ### 上报PV 上报一次PV，若pid与当前pid相同则会忽略此次PV。 **client('sendPageview',pid: string) =\> void** #### 示例 ```JavaScript client('sendPageview', '/test/pageA') ``` ### 上报自定义事件上报一个自定义事件。注意格式，格式不符合的事件将会试图转换，无法转换的事件将会被忽略。具体消费方式可以查看[自定义监控](https://www.volcengine.com/docs/6431/104917)。 **client('sendEvent', data: CustomEventPayload) =\> void** ```TypeScript interface CustomEventPayload { /** 自定义事件名称 */ name: string; /** metrics 上报的是可以被度量的值，也就是数值 */ metrics?: { [key: string]: number }; /** categories 上报的是分类，维度，用来做筛选，分组 */ categories?: { [key: string]: string }; } ``` #### 示例 ```TypeScript 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** ```TypeScript interface CustomLogPayload { /** 额外的附加信息，在上报的时候 number会被分流到metric string会被分流到categories */ extra?: { [key: string]: string | number }; // /** 自定义事件内容，任意字符串，可以是日志或者对象的 JSON 字符串等等 */ content: string; /** 自定义事件级别，默认是 info, 可枚举项 debug | info | warn | error */ level?: "debug" | "info" | "warn" | "error"; } ``` #### 示例 ```TypeScript 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** ```TypeScript export interface ReactInfo { version: string; componentStack: string; } ``` #### 示例 ```TypeScript // 上报一个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** ```TypeScript 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 }; } ``` #### 示例 ```TypeScript client('sendCustomPerfMetric', { name: 'fcp', value: 3500 } ``` ### 销毁实例调用此方法可以去掉所有监听和副作用，包括hook或者内存对象。当前实例本身还是可用的，所以手动调用API依然可以上报数据。 ```TypeScript client('destroy') ``` ### 上报任意事件直接上报一个事件，具体格式见[上报格式](https://www.volcengine.com/docs/6431/104865)。 **client('report', ev: ReportEvent) =\> void** #### 示例 ```TypeScript client('report', { ev_type: 'pageview', payload: { source: 'history', pid: '/pageB' } }) ``` ### 自定义补充面包屑面包屑主要在JS错误上报时会携带，如果业务想要自定义一些面包屑，可以使用下面的方式。 **client('addBreadcrumb',breadcrumb: Breadcrumb) =\> void** ```TypeScript 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 }; } ``` #### 示例 ```TypeScript 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。既然选择手动包装，那么就要避免自动包装带来的其他无关请求的监控上报。 #### 示例 ```TypeScript import client from '@apmplus/web' client('init', { ... plugins: { autoWrap: false, }, ... }) const fetchAfterWrap = client('wrapFetch', window.fetch) // then, use fetchAfterWrap to request ``` ### 手动检测白屏 **client('detectBlankScreen')** #### 示例 ```TypeScript import client from '@apmplus/web' client('init', { ... plugins: { blankScreen: { // 关闭自动检测，改为下方的手动检测 autoDetect: false }, }, ... }) client('detectBlankScreen') ``` ### 立即上报数据默认情况下，在页面关闭时SDK会使用sendBeacon强制发送缓存队列的数据，但是如果在页面关闭时，用户再手动调用某些API上报数据，可能因为时机问题导致漏发，可以使用以下方式强制发送数据： ```TypeScript import client from '@apmplus/web' // 写在回调里时为了确保SDK已经初始化完成，避免报错 onPageUnload(() => { client('on', 'init', () => { client.getSender().flush() }) }) ```

API访问密钥（Access Key）