Troubleshooting

Supported browsers and platforms

Modern browsers are supported out-of-the-box. Auto-updating versions of Chrome, Firefox, IE10+, Safari and Opera. IE 8 and 9 are also supported (the former requires the allowInsecureSubmissions option). Real User Monitoring requires IE >= 9 for Navigation Timing API support.

Raygun4JS also has dedicated support for WinJS, and works on various Android browsers and smart TVs. Support for React Native and other bundled mobile frameworks is available.

It is also known to run on old versions of Firefox (pre 4.0) and Opera. Legacy browsers such as Netscape, IE <= 7 are supported on a best-effort basis. Naturally, browsers that do not have JavaScript enabled are incompatible.

Sending errors manually

Raygun.init("apikey");

try {
  throw new Error("Description of the error");
} catch (e) {
  Raygun.send(e)
}

In order to get stack traces, you need to wrap your code in a try/catch block like above. Otherwise the error hits window.onerror handler and may only contain the error message, line number, and column number.

You also need to throw errors with throw new Error('foo') instead of throw 'foo'.

To automatically catch and send unhandled errors, you can attach the automatic window.onerror handler callback:

rg4js('enableCrashReporting', true);

If you need to detach it from window.onerror (which will disable automatic unhandled error sending):

rg4js('detach');

Internet Explorer 8 support

If you are serving your site over HTTP and want IE8 to be able to submit JavaScript errors then you will need to set the following setting which will allow IE8 to submit the error over HTTP. Otherwise the provider will only submit over HTTPS which IE8 will not allow while being served over HTTP.

rg4js('options', {
  allowInsecureSubmissions: true
});

Browser behaviour

Depending on what browser your users are running, the above properties may or may not have an effect. This sums up the situation as of writing:

  • Chrome 30+
  • Firefox 13+
  • Opera 12.50+
  • Safari (at least 6+)

In these browsers, if the script attribute is present, the HTTP header will need to be also present, otherwise the script will be blocked.

Firefox has additional behavior for RuntimeErrors. These will be provided to window.onerror regardless of the two properties, as these aren’t considered a security risk. SyntaxErrors, however, will be blocked in both Gecko and WebKit browsers, if crossorigin is present but the associated cross-origin domain lacks the header.

  • Internet Explorer <= 10

Errors will be reported with all available data in IE 10 and below.

  • Internet Explorer 11+

Third-party errors will not contain any data, and the attributes are not respected at current time.

Limitations of stack trace data

Due to browser API and security limitations, in cases where the message is ‘Script error’, only one stack trace frame may be present. In this scenario, the line number may not reflect the actual position where the original error was thrown.

For more information, check out this blog post on CORS requirements for Script Errors here.

Custom error grouping

You can control custom grouping for error instances by passing in a callback. This will override the automatic grouping and be used to group error instances together. Errors with the same key will be placed within the same error group. The callback’s signature should take in the error payload, stackTrace and options and return a string, ideally 64 characters or less. If the callback returns null or or a non-string the error will be grouped using Raygun’s server side grouping logic (this can be useful if you only wish to use custom grouping for a subset of your errors).

var groupingKeyCallback = function (payload, stackTrace, options) {
  // Inspect the above parameters and return a hash derived from the properties you want

  return payload.Details.Error.Message; // Naive message-based grouping only
};

rg4js('groupingKey', groupingKeyCallback);

Synchronous methods

Raygun4JS is designed to run asynchronously. Not doing so will block the page load while it is being downloaded/parsed/executed and stop errors being caught whilst the page is loading.

This will also disrupt Real User Monitoring timings, making them erroneous. For Real User Monitoring, it is especially important that the async snippet method is used.

NoConflict mode

If you already have an variable called Raygun attached to window, you can prevent the provider from overwriting this by enabling NoConflict mode:

rg4js('noConflict', true);

To then get an instance of the Raygun object when using V2, call this once the page is loaded:

var raygun = rg4js('getRaygunInstance');

Callback events

onBeforeSend

rg4js('onBeforeSend', function (payload) {
  return payload;
});

Call this function and pass in a function which takes one parameter (see the example below). This callback function will be called immediately before the payload is sent. The one parameter it gets will be the payload that is about to be sent. Thus from your function you can inspect the payload and decide whether or not to send it.

From the supplied function, you should return either the payload, or return false.

If your function returns a truthy object, Raygun4js will attempt to send it as supplied. Thus, you can mutate it as per your needs - preferably only the values if you wish to filter out data that is not taken care of by filterSensitiveData(). You can also of course return it as supplied.

If, after inspecting the payload, you wish to discard it and abort the send to Raygun, simply return false.

By example:

var myBeforeSend = function (payload) {
  console.log(payload); // Modify the payload here if necessary
  return payload; // Return false here to abort the send
}

rg4js('onBeforeSend', myBeforeSend);

onAfterSend

rg4js('onAfterSend', function (xhrResponse) {
  // Inspect the XHR response here
});

Call this function and pass in a function which takes one parameter (see the example below). This callback function will be immediately called after the XHR request for a Crash Reporting or Pulse event responds successfully, or errors out (its onerror was called). You can inspect the one parameter, which is the XHR object containing the HTTP response data.

onBeforeSendRUM

rg4js('onBeforeSendRUM', function (payload) {
  return payload;
});

Call this function and pass in a function which takes one parameter (see the example below). This callback function will be called immediately before any Real User Monitoring events are sent. The one parameter it gets will be the payload that is about to be sent. Thus from your function you can inspect the payload and decide whether or not to send it.

From the supplied function, you should return either the payload (intact or mutated as per your needs), or false.

If your function returns a truthy object, Raygun4JS will attempt to send it as supplied. Thus, you can mutate it as per your needs. You can also of course return it as supplied.

If, after inspecting the payload, you wish to discard it and abort the send to Raygun, simply return false.

By example:

var myBeforeSend = function (payload) { console.log(payload); // Modify the payload here if necessary return payload; // Return false here to abort the send }

rg4js('onBeforeSendRUM', myBeforeSend);

onBeforeXHR

rg4js('onBeforeXHR', function (xhr) {
  // Mutate the xhr parameter as per your needs
});

Call this function when you want control over the XmlHttpRequest object that is used to send error payloads to the API. Pass in a callback that receives one parameter (which is the XHR object). Your callback will be called after the XHR object is opened, immediately before it is sent.

For instance, you can use this to add custom HTTP headers.

Adding tags with a callback function

As above for custom data, withTags() can now also accept a callback function. This will be called when the provider is about to send, to construct the tags. The function you pass to withTags() should return an array (ideally of strings/Numbers/Dates).

Bower Installation

Using the Bower package manager, you can install it by running this command in a shell:

bower install raygun4js

NPM Installation

npm install raygun4js --save

This lets you require the library with tools such as Webpack or Browserify.

NuGet Installation

Visual Studio users can get it by opening the Package Manager Console and typing:

Install-Package raygun4js

React Native/Webpack/UMD module Installation

React Native and other bundled app frameworks that uses packaging/module loading libraries can use Raygun4js as a UMD module:

// Install the library

npm install raygun4js --save

// In a central module (as early as possible), reference and install the library with either this syntax:
import rg4js from 'raygun4js';
// Or this syntax:
var rg4js = require('raygun4js');

// Then set your config options (in one module only)
rg4js('enableCrashReporting', true);
rg4js('apiKey', 'paste_your_api_key_here');

All unhandled JavaScript errors will then be sent to Raygun. You can then import rg4js from 'raygun4js' in any other modules and use the rest of the V2 API below - including rg4js('send', anErrorObject) for manual error sending.

Note that the UMD module has a major limitation for web applications as errors that occur during page load in the bundle before the Raygun dependency is executed, such as syntax errors or runtime errors, can’t be caught and sent. Also, Pulse timings may be severly disrupted. Thus, the HTML snippet at the end of is greatly preferred to ensure you don’t miss any errors and for data correctness. The tradeoff with this method is that it is slightly less idiomatic to call rg4js as a global variable without importing/requiring it. As such, we only recommend this approach for React Native and other bundled mobile app (non-web) frameworks.

Manual download

Download the production version or the development version.

You can also download a version without the jQuery hooks if you are not using jQuery or you wish to provide your own hooks. Get this as a production version or development version.