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).
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.
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.
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.
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.
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.
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.
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).
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,
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.
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.
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: