Raygun4js
JavaScript provider for Raygun
Install / Use
/learn @MindscapeHQ/Raygun4jsREADME
Raygun4js
Raygun.com provider for client-side JavaScript
Getting Started
Asynchronous method - Highly recommended
Step 1
No installation via a package manager is required. Just add the following snippet to the beginning of the <head> tag within your markup. Please include this snippet before any other <script> tag references are made to ensure that Raygun has the best chance to capture all error events on the page.
<script type="text/javascript">
!function(a,b,c,d,e,f,g,h){a.RaygunObject=e,a[e]=a[e]||function(){
(a[e].o=a[e].o||[]).push(arguments)},f=b.createElement(c),g=b.getElementsByTagName(c)[0],
f.async=1,f.src=d,g.parentNode.insertBefore(f,g),h=a.onerror,a.onerror=function(b,c,d,f,g){
h&&h(b,c,d,f,g),g||(g=new Error(b)),a[e].q=a[e].q||[],a[e].q.push({
e:g})}}(window,document,"script","//cdn.raygun.io/raygun4js/raygun.min.js","rg4js");
</script>
The above snippet will fetch the Raygun4JS script from our CDN asynchronously, so it doesn't block other scripts from being loaded. It will also catch errors that are thrown while the page is loading, and send them when the script is ready.
Note: If you encounter a situation where no events are appearing within Raygun, you may need to hard code the URL protocol so that the CDN matches your hosting environment. This could look like one of the following -
https://cdn.raygun.io/raygun4js/raygun.min.jshttp://cdn.raygun.io/raygun4js/raygun.min.js
This will be in replacement of //cdn.raygun.io/raygun4js/raygun.min.js.
Via package manager installation
For installations and usage via a package manager, refer to the Synchronous methods section of this document.
Step 2
Add the following lines to your JS site code and paste in your API key (from your Raygun Application Settings), to set up the provider to automatically send errors to your Raygun app:
<script type="text/javascript">
rg4js('apiKey', 'paste_your_api_key_here');
rg4js('enableCrashReporting', true);
</script>
This will configure the provider to send to your Raygun app, and to automatically send all unhandled errors.
That's it for the basic setup! See Usage below for more info on how to send errors.
Snippet without page load error handler
If you do not want errors to be caught while the page is loading, use this snippet here.
Synchronous methods
Note that using these methods will not catch errors thrown while the page is loading. The script needs to be referenced before your other site/app scripts and will block the page load while it is being downloaded/parsed/executed.
This will also disrupt RUM timings, making them erroneous. For RUM, it is especially important that the async snippet method above is used, instead of one of the following.
With Bower
Run bower install raygun4js
With NPM
npm install raygun4js --save
This lets you require the library with tools such as Webpack or Browserify.
From NuGet
Visual Studio users can get it by opening the Package Manager Console and typing Install-Package raygun4js
React Native/as a UMD module
React Native and other bundled app frameworks that use packaging/module loading libraries can use Raygun4JS as a UMD module:
// Install the library
npm install raygun4js --save
// In a central module, reference and install the library
import rg4js from 'raygun4js'; // Import the library with this syntax
var rg4js = require('raygun4js'); // Or this syntax
rg4js('enableCrashReporting', true);
rg4js('apiKey', 'paste_your_api_key_here');
// Any other config options you want such as rg4js('setUser', ...) [see below]
rg4js('boot'); // For React Native only: add this after all other config options have been called
All unhandled errors will then be sent to Raygun. You can also require('raygun4js') in any other modules and use the rest of the V2 API below - including rg4js('send', error) for manual error sending.
If you use this approach, we appreciate your feedback as this is a new feature for the library.
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.
Usage
If you are using the CDN, be sure to call these usage methods after the installation.
To send errors manually:
try {
throw new Error('oops');
}
catch(e) {
rg4js('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 (this will disable automatic unhandled error sending):
rg4js('detach');
Documentation
Initialization Options
To configure the provider, call this and pass in an options object:
rg4js('options', {
// Add some or all of the options below
});
The second parameter should contain one or more of these keys and a value to customize the behavior:
ignoreAjaxAbort - User-aborted Ajax calls result in errors - if this option is true, these will not be sent.
ignoreAjaxError - Ajax requests that return error codes will not be sent as errors to Raygun if this options is true.
debugMode - Raygun4JS will log to the console when sending errors.
wrapAsynchronousCallbacks - if set to false, async callback functions triggered by setTimeout/setInterval will not be wrapped when attach() is called. Defaults to true
ignore3rdPartyErrors - ignores any errors that have no stack trace information. This will discard any errors that occur completely
within 3rd party scripts - if code loaded from the current domain called the 3rd party function, it will have at least one stack line
and will still be sent. Errors that occur in browser extensions or that have been triggered by bots/crawlers that appear to come from
your website will also be ignored. Note: IE 9 and below have no stacktrace information and errors will be discarded with this enabled.
excludedHostnames - Prevents errors from being sent from certain hostnames (domains) by providing an array of strings or RegExp
objects (for partial matches). Each should match the hostname or TLD that you want to exclude. Note that protocols are not tested.
excludedUserAgents - Prevents errors from being sent from certain user agents by providing an array of strings. This is very helpful to exclude errors reported by certain browsers or test automation with CasperJS, PhantomJS or any other testing utility that sends a custom user agent. If a part of the client's navigator.userAgent matches one of the given strings in the array, then the client will be excluded from error reporting.
disableErrorTracking - Stops all errors from being sent to Raygun. This includes errors automatically picked up by global error handlers as well as errors manually sent.
disablePulse - Stops real user monitoring events from being sent.
apiEndpoint - A string URI containing the protocol, domain and port (optional) where all payloads will be sent to. This can be used to proxy payloads to the Raygun API through your own server. When not set this defaults internally to the Raygun API, and for most usages you won't need to set this.
clientIp - A string containing the client's IP address. RUM requests will be associated to this IP address when set. Particularly useful when proxying payloads to the Raygun API using the apiEndpoint option and maintaining RUM's geographic lookup feature.
Note: navigator.sendBeacon is used to send RUM payloads when a page is unloading. As such the clientIp feature will not associate this last payload.
pulseMaxVirtualPageDuration - The maximum time a virtual page can be considered viewed, in milliseconds (defaults to 30 minutes).
pulseIgnoreUrlCasing - Ignore URL casing when sending data to RUM.
captureUnhandledRejections - Automatically catch send errors relating to unhandled promise rejections. See MDN for browser support.
setCookieAsSecure - If the cookies are being used (only used on browsers which don't support localStorage or sessionStorage) then they will be created using the ; secure flag and thus cookies only work on HTTPS.
captureMissingRequests - RUM uses the window.performance API to track XHR timing information and (depending on the browser) not all non-2XX XHR timings are recorded by this API. This option enables the tracking of these missing XHR's calls by tracking the difference between send & success XHR handlers. This is not enabled by default due these timings being as accurate as the performance API.
automaticPerformanceCustomTimings - When enabled Raygun4JS will track each window.performance.measure call as a custom timing entry. This enables developers to use a more native API for tracking performance timings. More information about performance.measure can be found on [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Performance/
