Bugsnag Notifier for JavaScript (Beta)

The Bugsnag Notifier for JavaScript gives you instant notification of errors and exceptions in your website's JavaScript code.

Bugsnag's JavaScript notifier is incredibly small, and has no external dependencies (not even jQuery!) so you can safely use it on any website.

This notifier is currently in beta, we're working on improving automatic error capturing and grouping very soon.

Bugsnag captures errors in real-time from your web, mobile and desktop applications, helping you to understand and resolve them as fast as possible. Create a free account to start capturing errors from your applications.

How to Install

Include bugsnag.js from our CDN in the <head> tag of your website, before any other <script> tags.

<script src="//d2wy8f7a9ursnm.cloudfront.net/bugsnag-1.0.9.min.js" data-apikey="YOUR-API-KEY-HERE"></script>

Make sure to set your Bugsnag API key in the data-apikey attribute on the script tag, or manually set Bugsnag.apiKey.

Sending Caught Exceptions or Custom Errors

You can easily tell Bugsnag about caught exceptions by calling Bugsnag.notifyException:

try {
  // Some code which might throw an exception
} catch (e) {
  Bugsnag.notifyException(e);
}

Since many exceptions in JavaScript are named simply Error, we also allow you to provide a custom error name when calling notifyException:

try {
  // Some code which might throw an exception
} catch (e) {
  Bugsnag.notifyException(e, "CustomErrorName");
}

You can also send custom errors to Bugsnag without any exception, by calling Bugsnag.notify:

Bugsnag.notify("ErrorName", "Something bad happened here");

Both of these functions can also be passed an optional metaData object as the last parameter, which should take the same format as metaData described below.

Browser Support

Some browsers, notably IE9 and below, don't support stacktraces on exceptions. In these situations we'll attempt to construct an approximate stacktrace, which will unfortunately not contain URL or line number information.

Additional Configuration

###apiKey

Set your Bugsnag API key. You can find your API key on your dashboard.

Bugsnag.apiKey = "YOUR-API-KEY-HERE";

###metaData

Set additional meta-data to send to Bugsnag with every error. You can use this to add custom tabs of data to each error on your Bugsnag dashboard.

This function should return an object of objects, the outer object should represent the "tabs" to display on your Bugsnag dashboard, and the inner objects should be the values to display on each tab, for example:

Bugsnag.metaData = {
  user: {
    name: "James",
    email: "james@example.com"
  }
};

###releaseStage

If you would like to distinguish between errors that happen in different stages of the application release process (development, production, etc) you can set the releaseStage that is reported to Bugsnag.

Bugsnag.releaseStage = "development";

By default this is set to be "production".

###notifyReleaseStages

By default, we will only notify Bugsnag of errors that happen when your releaseStage is set to be "production". If you would like to change which release stages notify Bugsnag of errors you can set notifyReleaseStages:

Bugsnag.notifyReleaseStages = ["development", "production"];

###notifyFilesWhiteList

By default, we notify Bugsnag of errors that happen in any file. But you can provide a white list regexp expression to the variable notifyFilesWhiteList. So it will notify only if filename matches this expression.

Bugsnag.notifyFilesWhiteList = /app\.js|vendor\.js/i;

###autoNotify

By default, we will automatically notify Bugsnag of any JavaScript errors that get sent to window.onerror. If you want to stop this from happening, you can set autoNotify to false:

Bugsnag.autoNotify = false;

Reporting Bugs or Feature Requests

Please report any bugs or feature requests on the github issues page for this project here:

https://github.com/bugsnag/bugsnag-js/issues

Contributing

Fork the notifier on github
Edit only src/bugsnag.js. The files in dist and docs are autogenerated.
Make sure your changes support older browsers, avoid any unsupported methods
Make sure all tests pass by building (npm install, grunt), then opening test/index.html in your browser
Commit only changes you make in test and src, please don't commit dist or doc
Commit and push until you are happy with your contribution
Make a pull request
Thanks!

License

The Bugsnag JavaScript notifier is free software released under the MIT License. See LICENSE.txt for details.

refiito/bugsnag-js