Installation

You install the Browser Agent by including the script on your website. The agent script listens for errors and other events to be reported back to your TrackJS Dashboard. The agent is lightweight and dependency free.

Here is the default installation method for loading from our CDN, bundling as a module, or using the legacy client (earlier than 3.0.0). Loading from the CDN is the easiest way to get started, especially if you don’t already use a module bundler (like Webpack).

<script src="https://cdn.trackjs.com/agent/v3/latest/t.js"></script>
<script>
  window.TrackJS && TrackJS.install({
    token: "YOUR_TOKEN"
  });
</script>

Copy

// ES6 Modular JavaScript.
// npm install trackjs --save

import { TrackJS } from "trackjs";
TrackJS.install({
  token: "YOUR_TOKEN"
});

Copy

<!-- Legacy agent deprecated 2018-10-31 -->
<script>
  window._trackJs = {
    token: "YOUR_TOKEN"
  };
</script>
<script src="https://cdn.trackjs.com/releases/current/tracker.js"></script>

Copy

Install Options

In addition to token, there are lots of options you can pass when installing the agent to better integrate with your application. Options can be used to:

• add custom context to your errors
• disable agent behaviors
• customize reporting behavior

If you need the agent to do something specialized, checkout the onError option that allows you to manipulate errors before they are reported.

Crossorigin

If you are installing the TrackJS agent from our CDN, the script will be loaded from a different origin than your page. This can sometimes cause errors to be obfuscated as "Script Error" due to the browser’s Same-Origin Policy.

For this reason, we recommend including the agent as a module and bundling it with your other scripts, hosted from your own domains. If this is not feasible for you, you can also decorate the script with the crossorigin attribute to attempt to bypass the Same-Origin policy.

<script src="https://cdn.trackjs.com/agent/v3/latest/t.js" crossorigin></script>
<script>
  window.TrackJS && TrackJS.install({
    token: "YOUR_TOKEN"
  });
</script>

Copy

Be aware that not all browsers support the crossorigin attribute, and networks can block the delivery of CORS headers required for it to function. Check out Crossorigin Scripts and Corporate Proxies for more.

Safety Checking

It is not uncommon for scripts to fail to load in production. Slow devices, flaky connections, network middleware, and browser extensions can call interfere with a script loading.

Anytime you are referencing a script that loads separately, you should perform a Safety Check that it has loaded. Otherwise, you might encounter an error like ReferenceError: TrackJS is not defined, and stop execution of your code prematurely.

When you load the agent from our cdn, or as a standalone script, safety check to make sure the agent has loaded before calling a method. This looks like window.TrackJS && TrackJS.someMethod(). This is performing a logical operation to check if window.TrackJS exists before attempting to call the method.

If you are bundling the agent as a module with your code, this safety check is probably unnecessary.

Auto Install

You can configure the agent to automatically install itself as soon as it is loaded by creating a config object on window._trackJs. This is useful if you do not know when the agent may be loaded.

This was the default mechanism of installation before agent version 3.0.0.

Versions

The latest version of the agent is published to our CDN at https://cdn.trackjs.com/agent/v3/latest/t.js. You can also find it on GitHub and npm. All the version information is available in the changelog.

The Agent is periodically updated with new capabilities and fixes for browser variations. We recommend referencing a specific version of the agent so that you control when changes are introduced in your application.

To be notified when a new version of the agent is released, you can subscribe to the GitHub package for releases, or join the agent release mailing list.

Placement

When the agent is installed, it wraps the browser’s native functions to capture context and report errors. Errors and events that occur before the agent is installed will not be recorded. Therefore, we recommend that you reference and install the agent as early as possible in the page.

If you are referencing the agent as a script tag, which is the default, the agent should be the first script in the document. If you are bundling the agent, make sure that TrackJS.install() is called as soon as possible during initialization.

Initialization errors are very common for web applications. Delaying the installation of the TrackJS agent can create dangerous blindspots to these kinds of errors.

Bundling as a Module

The agent is published to npm and supports ES6, CommonJS, and AMD modules. Below are some common use cases, which expect you’ve already included the agent from npm (npm install trackjs --save).

import { TrackJS } from "trackjs";

TrackJS.install({ token: "YOUR_TOKEN" });

Copy

var TrackJS = require("trackjs").TrackJS;

TrackJS.install({ token: "YOUR_TOKEN" });

Copy

require.config({
    paths: {
        "TrackJS": "/node_modules/trackjs/t.js"
    }
});

require(["TrackJS"],
    function(TrackJS) {
        TrackJS.install({ token: "YOUR_TOKEN" });
    }
);

Copy

Async

Although we strongly recommend against it, you may want to load the agent asynchronously to reduce page load time. You can effectively do this by using the async attribute, which will load and execute the script when the browser is ready. For example,

<script>
  window._trackJs = { token: "TOKEN" };
</script>
<script async src="https://cdn.trackjs.com/agent/v3/latest/t.js></script>

Copy

This code utilizes the Automatic Install method of installation, which will install the agent as soon as it is loaded if it detects a window._trackJs config object.

Content-Security

If you are using a Content-Security Policy to secure the scripts on your page, here are the directives you’ll need to ensure TrackJS functions properly.

script-src https://cdn.trackjs.com; connect-src https://capture.trackjs.com; img-src https://usage.trackjs.com; img-src https://fault.trackjs.com

Copy

Developing Locally

The agent can interfere with your development on local environments. You may see that console messages all appear from t.js, or that your debugger is stepping through our minified code.

If you are developing using either Chrome, Blackboxing the agent script will remove these console annoyances and bypass our agent in your debugger.

You may prefer to disable the agent entirely on local environments to cut down on noise in your Dashboard. Assuming your local environment is hosted at localhost, here is how you can do that:

<script src="https://cdn.trackjs.com/agent/v3/latest/t.js"></script>
<script>
  if (location.host.indexOf("localhost") !== 0) {
    window.TrackJS && TrackJS.install({
      token: "YOUR_TOKEN"
    });
  }
</script>

Copy

// ES6 Modular JavaScript.
// npm install trackjs --save

import { TrackJS } from "trackjs";

if (location.host.indexOf("localhost") !== 0) {
  TrackJS.install({
    token: "YOUR_TOKEN"
  });
}

Copy

<!-- Legacy agent deprecated 2018-10-31 -->
<script>
  window._trackJs = {
    token: "YOUR_TOKEN",
    enabled: location.host.indexOf("localhost") !== 0
  };
</script>
<script src="https://cdn.trackjs.com/releases/current/tracker.js"></script>

Copy