Plugin guide

Instructions for writing a plugin to use with your Bugsnag configuration.

There are two ways you can tell Bugsnag to use a plugin:

bugsnag(opts, plugins)

When you configure your notifier, pass an array of plugins along as the second parameter:

window.bugsnagClient = bugsnag('API_KEY', [ myCoolPlugin ])

bugsnagClient.use(plugin)

If for some reason you don’t have access to Bugsnag’s initial configuration, or it’s not convenient to load your plugin at that point, you can provide a plugin to a client instance:

bugsnagClient.use(myCoolPlugin)

If you are unsure – prefer the first method. This enables plugins to define extra configuration options for the opts object, which they cannot do if opts has already been provided.

For plugin creators

If you want to augment Bugsnag’s behaviour, write a plugin! Plugins are powerful – in fact most of the platform-specific functionality of the notifier is added internally via the same interface.

Plugins get:

  • access to the client instance
  • the ability to specify additional configuration opts, including validation and default values

Additionally, anything that does any of the following behaviour, which happens to be available externally, but is conventionally private belongs in a plugin. That includes:

  • using the BugsnagReport constructor
  • using the BugsnagBreadcrumb constructor

Interface

var plugin = {
  /*
   * Initializes the plugin.
   * client: is a client is a freshly configured client instance
   * BugsnagReport: is a constructor for the report data structure
   */
  init: function (client) {
    // the following constructors are available:
    // client.BugsnagReport and client.BugsnagBreadcrumb

    // aditionally plugins might want to append functions to:
    // client.config.beforeSend[]

    // or call notify
    // client.notify(err)
  },

  /*
   * An (optional) object whose keys define additional config
   * options with defaults, validation and error messages.
   */
  configSchema: {}
}

Example

Here’s an example of a plugin that would report an unhandled error any time the user presses ESC multiple times.

var escPlugin = {
  init: function (client) {
    var lastPress = null
    window.addEventListener('keydown', function (e) {
      if (e.keyCode !== 27) return
      if (lastPress === null) {
        lastPress = Date.now()
        return
      }
      if (Date.now() - lastPress > client.config.escPressesTimeout) {
        lastPress = Date.now()
        return
      }
      var stacktrace = client.BugsnagReport.getStacktrace(new Error())
      var handledState = {
        severity: 'error',
        unhandled: true,
        severityReason: { type: 'unhandledException' }
      }
      var report = new client.BugsnagReport(
        'UserEscapeAttempt',
        'Detected multiple escape presses',
        stacktrace,
        handledState
      )
      client.notify(report)
    })
  },
  configSchema: {
    escPressesTimeout: {
      defaultValue: function () { return 1000 },
      validate: function (val) { return typeof val === 'number' },
      message: '(number) escPressesTimeout must be a number'
    }
  }
}

bugsnag({ apiKey: 'API_KEY', escPressesTimeout: 2000 }, [ escPlugin ])