Browser integration guide

Add Bugsnag to your browser-based JavaScript projects to automatically capture and report exceptions in production.

Installation

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

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

Self-hosting

You can also host bugsnag.js yourself if you would like to avoid an additional request. Download the latest version from GitHub or use the bugsnag-js npm package and include the bugsnag script in your assets before any other javascripts. See our FAQ for more information on alternate methods of loading bugsnag.js.

Basic configuration

If you did not set the data-apikey attribute in the installation step or are compressing all of your assets, you can manually set Bugsnag.apiKey.

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

Configuring release stages

To distinguish between errors that happen in different stages of the application release process (development, production, etc), set a release stage for each environment.

Use the notifyReleaseStages configuration option if you would like to only send data to us from particular release stages.

TypeScript support

TypeScript type definitions for Bugsnag are available via DefinitelyTyped.

To use, include a line like so:

/// <reference path="bugsnag/bugsnag.d.ts"

Alternately, the definitions can be downloaded from the Bugsnag library source repository.

Reporting unhandled exceptions

After completing installation unhandled exceptions will be automatically reported to your Bugsnag dashboard.

Reporting handled exceptions

Reporting handled exceptions can be accomplished as follows:

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

Since many JavaScript exceptions 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");

For more information see reporting handled errors.

Sending diagnostic data

Automatically captured diagnostics

Bugsnag will automatically capture the following data for every exception:

  • Request information such as the IP and URL
  • Browser name, version, user agent and locale
  • Operating system
  • Release stage (production, beta, staging, etc)

Custom diagnostics

The metaData field is a nested object in which each root value will be rendered as a tab in a Bugsnag error report. This example would create a tab called “company” in each error report:

Bugsnag.metaData = {
  company: {
    name: "Acme Co.",
    country: "uk"
  }
};

Custom diagnostics can also be set in a beforeNotify callback if you need to calculate them at the point when an exception happens:

Bugsnag.beforeNotify = function(payload, metaData) {
  metaData.user_analytics = {
    session_length: 1045,
    new_visitor: false
  };
 };

You can also send custom diagnostics with a handled exception. For more information, see Reporting handled errors.

Leaving breadcrumbs

Breadcrumbs allow you to see a log of actions that led up to an error. Error reports automatically include breadcrumbs for the last 25 events which occurred.

Automatically captured breadcrumbs

By default, Bugsnag captures common events as breadcrumbs including:

  • Clicks
  • Errors
  • Console logs, warnings, and errors
  • Page load, hide, and show
  • DOMContentLoaded
  • Pop state
  • History push state and replace state
  • Hash change

For more information or to disable particular classes of automatic breadcrumb generation, see autoBreadcrumbs) in Configuration options.

Attaching custom breadcrumbs

Bugsnag.leaveBreadcrumb("Increased Volume")

You can also attach additional diagnostic data to breadcrumbs as follows:

Bugsnag.leaveBreadcrumb('Increased Volume', {
  from: 5,
  to: 11
})

Note that for breadcrumbs, the metadata object should only be one level deep and the object’s values are limited to 140 characters each.

Identifying users

In order to correlate errors with customer reports, or to see a list of users who experienced each error, it is helpful to capture and display user information on your Bugsnag dashboard. The user property is used to populate the “User” tab of reported errors on your Bugsnag dashboard, and the id property specifically is used to determine the number of users affected by a particular error. Common other fields to include are name and email.

Bugsnag.user = {
    id: 7,
    name: "Conrad Irwin",
    email: "conrad@bugsnag.com"
};

Tracking deploys

By sending your source revision or application version to us when you deploy a new version of your app, you’ll be able to see in which deploy each error was introduced or seen, as well as connect stacktrace lines with the source code on GitHub.

Integrate a call to our deploy tracking API into your deployment process to get started.

Next steps

  • View bugsnag-js, the library powering this integration, on GitHub
  • Get support for your questions and feature requests