Raygun4js Documentation

The raygun4js library supports several crash reporting patterns to enhance error visibility:

• Basic Crash Reporting: Standard setup to capture unhandled errors.
• Custom Data: Sending additional context/metadata alongside the crash report.
• User Details: Attaching specific user information to a crash report to identify affected users.
• Tags: Sending custom tags to help with filtering and grouping errors in the Raygun dashboard.
• Manual Error Sending: Using the API to manually trigger a crash report for specific errors.
• Error Grouping: Using a custom error grouping key to control how errors are aggregated.
• Environment Filtering: Implementing logic to ignore errors generated on localhost or *.local domains to reduce noise.

To avoid (anonymous function) entries in your stack traces, use named functions. When assigning functions to objects or variables, use a naming convention that avoids collisions with the identifier to ensure compatibility with older browsers like IE.

Recommended Pattern:

• For object properties: Api.foo = function Api_foo() { ... };
• For variables: var bar = function barFn() { ... };

Raygun4JS provides two ways to interact with the provider:

• V1 (Legacy/Synchronous): Functions are called directly on the global Raygun object (e.g., Raygun.init('key').attach()). This version supports being bundled with other vendor scripts.
• V2 (Recommended/Asynchronous): Uses a global rg4js() function that accepts parameters applied once the script is downloaded asynchronously (e.g., rg4js('init', 'key')). This is superior for performance and ensures errors occurring during page load (before the script is ready) are still caught.

For most functions, you can use either Raygun.functionName(value) or rg4js('functionName', value), except for send().

To perform a basic setup of Raygun4js V1, load the script directly from the Raygun CDN and initialize it with your API key. This configuration will automatically send all unhandled errors to your Raygun app.

Step 1: Load the script Use the following script tag to load the library. You can use the unversioned release for the latest stable version or specify a versioned subdirectory (e.g., /raygun4js/1.14.0/raygun.js) for stability.

Step 2: Initialize and attach Call Raygun.init() with your API key and Raygun.attach() to enable automatic error catching.

<!-- Step 1: Load from CDN -->
<script type="text/javascript" src="//cdn.raygun.io/raygun4js/raygun.min.js"></script>

<!-- Step 2: Initialize and attach -->
<script type="text/javascript">
  Raygun.init('yourApiKey', {
    // Setup options here
  });
  Raygun.attach();
</script>

Errors in scripts hosted on different domains often appear as generic 'Script Error' with poor stack traces.

1. Enable Whitelisting: Use Raygun.init('key', { ignore3rdPartyErrors: true }).whitelistCrossOriginDomains(['cdn.example.com']) to allow specific remote domains.
2. CORS Requirements: For full stack traces, the remote domain must have Access-Control-Allow-Origin set to your domain. In Chrome, the <script> tag must also have the crossOrigin="Anonymous" attribute.

Raygun.init('apikey', { ignore3rdPartyErrors: true })
  .whitelistCrossOriginDomains(['code.jquery.com']);

To capture Angular errors automatically, implement the ErrorHandler interface and use the rg4js('send', ...) method within the handleError function. This ensures that any error caught by Angular's error handling lifecycle is reported directly to Raygun.

// Create a new ErrorHandler and report an issue straight to Raygun
export class RaygunErrorHandler implements ErrorHandler {
  handleError(e: any) {
    rg4js('send', {
      error: e,
    });
  }
}

In Vue.js 2.x, you can capture errors by assigning a function to the global Vue.config.errorHandler property. Use the rg4js('send', ...) method, passing the error and any relevant metadata (like info) inside the customData array.

// Vue 2.x example
Vue.config.errorHandler = function(err, vm, info) {
  rg4js('send', {
    error: err,
    customData: [{ info: info }]
  });
};

For projects using module bundlers (like Webpack or Browserify) or specific package managers, you can install Raygun4js synchronously.

Warning: Synchronous installation will not catch errors thrown during the initial page load and can disrupt Real User Monitoring (RUM) timings. Use the asynchronous CDN method for RUM-sensitive applications.

Installation Commands:

• NPM: npm install raygun4js --save
• Bower: bower install raygun4js
• NuGet: Install-Package raygun4js (via Package Manager Console in Visual Studio)

In Vue.js 3.x, the error handler is configured on the application instance rather than the global Vue object. After calling Vue.createApp({}), assign your error handling logic to app.config.errorHandler.

// Vue 3.x example
const app = Vue.createApp({});

app.config.errorHandler = function(err, vm, info) {
  rg4js('send', {
    error: err,
    customData: [{ info: info }]
  });
};

app.mount('#app');

TraceKit can be installed using the Bower package manager. This will place the library at components/tracekit/tracekit.js. After installation, include the script in your HTML page.

bower install tracekit