Bugsnag Notifier for JavaScript
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!), and works in all browsers (even mobile browsers!), so you can
safely use it on any website.
Learn more about Bugsnag's JavaScript error monitoring solution. 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-2.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.
Now all uncaught exceptions will be sent to Bugsnag, without any further
work from you.
Sending Caught Exceptions or Custom Errors
You can easily tell Bugsnag about caught exceptions by calling
Bugsnag.notifyException
:
try {
} 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 {
} 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.
Severity
You can set the severity of an error in Bugsnag by including the severity option when
notifying bugsnag of the error,
Bugsnag.notify("ErrorName", "Something bad happened here", {}, "error");
Valid severities are error
, warning
and info
.
Severity is displayed in the dashboard and can be used to filter the error list.
By default all crashes (or unhandled exceptions) are set to error
and all
Bugsnag.notify
calls default to warning
.
Cross-domain errors
Browsers obscure some error messages that happen when scripts are loaded
cross-domain. This is for security, but is annoying when hosting javascript on
a CDN. You can tell if this happens because Bugsnag will log to your console:
[Bugsnag] Ignoring cross-domain script error.
You can fix this by loading your javascript using CORS. We have detailed
instructions for setting this up.
Browser Support
Bugsnag can automatically notify you of unhandled exceptions in all versions of
all browsers (yes, even IE 6!). Some browsers let us do even more, and
internally we have 3 tiers of higher quality support:
| Tier A | Tier B | Tier C | Supported
-----------|:------:|:------:|:------:|:---------:
iOS | 7+ | 6 | 3-5 | all
Android | 4.0+ | | 2.2-3 | all
Blackberry | | 10 | | all
IE | 8+ | | | all
Firefox | 17+ | 6-16 | 3-5 | all
Safari | 7+ | 6 | 5 | all
Chrome | 14+ | | | all
Opera | 13+ | 10-12 | | all
Cumulative | 82.9% | 91.2% | 96.4% | 100%
Most users are on tier A or B browsers (91.2%), errors from these browsers are
deduplicated most effectively, and there's lots of debugging information
available.
A number of people are still on tier C (%5.2%) or worse (3.6%) browsers (though
those proportions will diminish over time). We can still notify you of problems
in these browsers, though the quality is significantly lower.
If you're only targetting up-to-date users, you can tell Bugsnag to only report
errors from modern browsers by going to "Settings -> Error Handling"
Configuration
###apiKey
Set your Bugsnag API key. You can find your API key on your dashboard.
<script src="//d2wy8f7a9ursnm.cloudfront.net/bugsnag-2.min.js"
data-apikey="YOUR-API-KEY-HERE"></script>
In situations where Bugsnag is not in its own script tag, you can set
this with:
Bugsnag.apiKey = "YOUR-API-KEY-HERE";
###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
:
<script src="//d2wy8f7a9ursnm.cloudfront.net/bugsnag-2.min.js"
data-apikey="YOUR-API-KEY-HERE"
data-autonotify="false"></script>
In situations where Bugsnag is not in its own script tag, you can set
this with:
Bugsnag.autoNotify = false;
###notifyHandler
By default, the notify request will be made via temporary javascript image object.
This does not work in Chrome apps and extensions where XHR needs to be used.
If you want to use Bugsnag with XHR, just set notifyHandler
to xhr
:
<script src="//d2wy8f7a9ursnm.cloudfront.net/bugsnag-2.min.js"
data-apikey="YOUR-API-KEY-HERE"
data-notifyhandler="xhr"></script>
In situations where Bugsnag is not in its own script tag, you can set
this with:
Bugsnag.notifyHandler = "xhr";
###user
Information about the current user. This data will be sent to Bugsnag with
exception reports so that you can see who was affected by a particular error
and search for problems seen by a given user.
Bugsnag.user = {
id: 7,
name: "Conrad Irwin",
email: "conrad@bugsnag.com"
};
###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 to help you
debug.
This should be 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 = {
account: {
name: "Bugsnag",
plan: "premium",
beta_access: true
}
};
###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 notify Bugsnag of exceptions that happen in any
releaseStage
. If you would like to change which release stages notify
Bugsnag of errors you can set notifyReleaseStages
:
Bugsnag.notifyReleaseStages = ["development", "production"];
###appVersion
Setting the appVersion
lets you see at a glance when errors first and last
happened in your code. You can do this either in the script-tag:
<script src="//d2wy8f7a9ursnm.cloudfront.net/bugsnag-2.min.js"
data-apikey="YOUR-API-KEY-HERE"
data-appversion="2.0.14"></script>
Or in javascript:
Bugsnag.appVersion = "2.0.14";
###beforeNotify
To have more fine grained control over what errors are sent to Bugsnag, you can
implement a beforeNotify
function. If you want to halt the notification completely,
return false
from this function.
Bugsnag.beforeNotify = function(payload) {
var match = payload.file.match(/app\.js|vendor\.js/i);
return !!(match && match[0].length > 0);
}
You can modify the payload
or metaData
by editing the parameters.
Bugsnag.beforeNotify = function(payload, metaData) {
payload.url = "http://redacted.com";
}
The payload
parameter contains the error's name
, message
, file
and
lineNumber
where available, as well as some additional fields that we either
show on your Bugsnag dashboard, or use for grouping.
###groupingHash
If the metaData hash has a key groupingHash
it will be used to override the
default grouping on Bugsnag.com. Exceptions with the same grouping hash will be
grouped together into one error. You should not normally need to change this.
Bugsnag.notifyException(e, {groupingHash: e.message});
By default errors will be grouped by the statement in your code that raised the
error. We try to fetch the javascript and use the surrounding code to identify
the statement, but if that's not possible we fall back to using line number and
filename as an approximation.
###endpoint
The endpoint option causes the Bugsnag notifier to send errors to a different
web address. By default the address is set to https://notify.bugsnag.com/js
,
but you can change it to point to an on-premise installation of Bugsnag:
Bugsnag.endpoint = "https://bugsnag.local:49000/js";
###projectRoot
By default, Bugsnag sets the projectRoot to the current host address (protocol
& the domain). For example, https://example.com
is the projectRoot for all
errors that occur within the example.com
domain.
Bugsnag.projectRoot = "http://example.com";
###context
By default, Bugsnag sets the context to the current page's pathname, otherwise
referred to as location.pathname
. Note: location.pathname
does not include
any search parameters or the page's fragment identifier.
Bugsnag.context = "/path/to/my/page.php";
noConflict Support
Bugsnag has a noConflict
function for removing itself from the window
object
and restoring the previous binding. This is intended for use in environments
where developers can't assume that Bugsnag isn't in use already (such as 3rd
party embedded javascript) and want to control what gets reported to their
Bugsnag account.
The object returned from noConflict()
is the full Bugsnag object so can be
used in the same way:
var myBugsnag = Bugsnag.noConflict();
myBugsnag.apiKey = "my-special-api-key";
try {
} catch (e) {
myBugsnag.notifyException(e, "OhNoes");
}
AMD/CommonJS support
Bugsnag can be loaded as-is using an AMD or CommonJS compatible loader. This means
you can use it with tools like RequireJS and Browserify directly. If you want to
load Bugsnag from the CDN but load the rest of your code using AMD, then
you should ensure Bugsnag is required before the rest of your code.
If you load Bugsnag after the rest of your code, and your AMD loader leaks the global
define
function then you may see the (harmless) error message:
"Mismatched anonymous define() module". To fix this, load Bugsnag before the
rest of your code.
Script tag support
By default Bugsnag sends the contents of inline script tags on the page to our
servers to help with analysis and debugging. If you don't want this to happen,
set inlinescript
to false.
<script src="//d2wy8f7a9ursnm.cloudfront.net/bugsnag-2.min.js"
data-inlinescript="false"></script>
Notifying Bugsnag about jQuery Ajax errors
If you're using jQuery to send Ajax requests, we recommend hooking Bugsnag up to notify about ajaxError
's.
$( document ).ajaxError(function(event, jqxhr, settings, thrownError) {
Bugsnag.notify("AjaxError", thrownError);
});
Source Maps
Bugsnag supports source
maps to
reverse JavaScript minification. These can either be fetched automatically
or manually uploaded using the Bugsnag Source Map API.
See the Bugsnag source map documentation for details.
Advanced hosting
We will occasionally update bugsnag-2.js on the CDN to improve the quality of
our notifier without breaking backward compatibility. If you need assurance
that the javascript will never change, feel free to include the specific version
directly.
<script src="//d2wy8f7a9ursnm.cloudfront.net/bugsnag-2.5.0.min.js"
data-apikey="YOUR-API-KEY-HERE"></script>
If you have specific requirements for Javascript, you're welcome to host
versions of bugsnag-js on your own site or CDN.
If you'd like to avoid an extra blocking request, you can include the javascript
in your asset compilation process so that it is inlined into your existing script
files. The only thing to be sure of is that Bugsnag is included before your
onload handlers run. This is so that we can report stacktraces reliably.
Rate limiting
By default only 10 errors are allowed per page load. This is to prevent wasting
a user's bandwidth sending thousands of exceptions to Bugsnag. If you have a long-running
single page app, you can reset this rate-limit from your router by using:
Bugsnag.refresh()
Browser Extensions
Bugsnag's backend automatically ignores errors if they appear to come from
browser extensions, since these errors usually aren't actionable for site owners and often
aren't related the current page's code at all.
If you have a special case where you want to know about errors that come from
extensions — for example, if you are attempting to monitor a browser extension
itself — you may need to modify the error stacktrace you send to Bugsnag to work
around this feature. For example, for a Chrome extension, you might add something
like this to your beforeNotify function:
Bugsnag.beforeNotify = function (error, metaData) {
error.stacktrace = error.stacktrace.replace(/chrome-extension:/g, "chromeextension:");
}
To monitor an extension, you may also need to
use XHR
to notify Bugsnag of errors to work around content security policy restrictions
for images loaded by extensions.
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
License
The Bugsnag JavaScript notifier is free software released under the MIT License.
See LICENSE.txt for details.