You need to enable JavaScript to run this app.
导航

按需集成插件

最近更新时间2024.03.18 17:07:31

首次发布时间2022.04.19 16:33:33

一些不常用的需求由于使用场景少,无法默认集成在SDK中,您可以通过自定义插件的方式按需集成。

基础使用

client('init',{
  ...
  integrations: [{
    name: 'name', // 插件名称,用于去重
    setup: (client) => void, // 初始化代码, 传入的client是SDK的实例
    tearDown: () => void, // 可选,有副作用时需要提供,会在SDK被调用destroy的时候执行
  }],
  ...
})

使用插件包

refreshPreStartContext

插件包模块

说明

版本要求

apmplus/integrations version >=1.2.2

功能说明

以start时的conext刷新start之前预发送队列里的context。

应用场景

如果希望设置一些context能对所有的上报生效,但是有的context只能异步获取时,可以使用此插件。插件会以start时的conext刷新start之前预发送队列里的context。

示例代码

import { refreshPreStartContext } from '@apmplus/integrations/refreshPreStartContext'
import client from '@apmplus/web'

client('init', {
  ...
  integrations: [refreshPreStartContext()]
  ...
})

captureConsole

插件包模块

说明

版本要求

apmplus/integrations version >=1.2.2

功能说明

在调用全局console对象的时候,将调用参数包装成JS错误并上报到平台上。

参数说明

指定需要hook的levels数组,包括'log','info','warn','error','debug','assert'等。

风险说明

由于hook了全局的console对象,所以在控制台中调用console相关方法也会触发上报。

示例代码

import { captureConsole } from '@apmplus/integrations/captureConsole'
import client from '@apmplus/web'

client('init', {
  ...
  // levels 必填, 如下指定需要hook console的哪些方法,所示的功能则是hook console.error并将调用参数包装成JS 错误 并上报到平台上
  integrations: [captureConsole({ levels: ['error'] })]
  ...
})

actionPlugin

插件包模块

说明

版本要求

  • apmplus/integrations version >=2.0.0
  • apmplus/web version >=1.7.0

功能说明

监听用户操作以衡量操作的性能。

应用场景

如果业务方希望还原完整的用户操作路径,衡量操作的性能情况,可以使用此插件。

示例代码

import client from '@apmplus/web'
import { actionPlugin } from '@apmplus/integrations/action'

// 示例一:集成action插件
client('init',{
  ...
  integrations: [actionPlugin()],
  ...
})

// 示例2: 集成action插件但是并不监听任何事件
client('init',{
  ...
  integrations: [actionPlugin({ types: false })],
  ...
})

// 示例3: 集成action插件但是并监听指定的事件类型
client('init',{
  ...
  integrations: [actionPlugin({ types: ['click'] })],
  ...
})

// API支持: 可以手动开始一个行为
client("startAction", "action name", "action type");

自定义插件

如果插件包里的插件无法满足业务需求,您可以自行发布一个插件包。

  1. 发布插件包。
    插件的实现可以是直接返回一个对象,或一个方法。您可以传入一些配置,返回一个对象,只要这个对象满足integrations类型约定。

    import client from '@apmplus/web'
    client('init',{
      ...
      integrations: [{
        name: 'name', // 插件名称,用于去重
        setup: (client) => void, // 初始化代码, 传入的client 是监控实例
        tearDown: () => void, // 可选,有副作用时需要提供,会在SDK被调用destroy的时候执行
      }],
      ...
    })
    

    示例代码如下:

    import client from '@apmplus/web'
    
    // 一个自定义插件
    // 功能:以start时的context 刷新预收集队列的context
    const refreshPreStartContext = () => ({
      name: 'refreshPreStartContext',
      setup: (client: WebClient) => {
        client.on('start', () => {
          const preStartQueue = client.getPreStartQueue()
          preStartQueue.forEach((ev: WebReportEvent, index: number) => {
            preStartQueue[index] = {
              ...ev,
              overrides: {
                ...(ev.overrides ?? {}),
                context: client?.context?.toString() || {},
              },
            }
          })
        })
      },
    })
    
    client('init',{
      ...
      // 使用此插件
      integrations: [refreshPreStartContext()],
      ...
    })
    
  2. 集成到插件包。
    如果您的自定义插件适用于大部分业务,请联系开发人员集成在apmplus/integrations中。

    // 从官方的插件包中引入某一个插件
    import { refreshPreStartContext } from '@apmplus/integrations'
    import client from '@apmplus/web'
    
    client('init', {
      ...
      integrations: [refreshPreStartContext()]
      ...
    })
    

Script方式接入如何按需集成插件

按需集成插件需要在init的时候配置插件,而script接入方式一般会在html中进行init 。所以只要将init相关代码从html中移动到业务代码里即可。
在html引入预收集脚本后, 在业务代码里初始化。以action插件为例:

import { actionPlugin } from '@apmplus/integrations/action'

window.{{GlobalName}}('init', {
  aid: xxx,
  token: 'xxx', 
  integrations: [actionPlugin()],
})
window.{{GlobalName}}('start')

这样操作基本没有副作用,预收集脚本的存在,保证初始化之前的错误和异常不会遗漏。但是初始时间较晚,可能会导致较早发出的请求收集不到,所以请确保初始化代码在业务代码中的较早位置执行。