Tracker Script Configuration

When you load the tracker script, one the first things it does is look for a global variable called _trackJs. It uses this variable to configure itself with things like your customer token, or the specific application it’s monitoring. If it doesn’t find that variable it will issue a warning to the console and shut itself down. To that end, it’s important that the global configuration variable is set before the script initializes.

It might look a little odd to declare a global variable before loading our script. We do things this way because we want to make sure TrackJS begins monitoring immediately upon initialization. TrackJS implicitly initializes itself - that is, it starts monitoring without any explicit code action by you. In order for that to work, the configuration needs to be present before TrackJS is loaded.

Simplest Configuration Possible

All the tracker script really needs is your customer token. You can find out where to get it in the installation instructions.

The important thing to note here is that the configuration variable is defined before we load the script.

<script>
  window._trackJs = {
    token: "YOUR_TOKEN_HERE"
  }
</script>
<script type="text/javascript" src="https://cdn.trackjs.com/releases/current/tracker.js"></script>

If you’re interested in bundling TrackJS with your current workflow, we support many modern JavaScript workflows, including Gulp, Webpack, Browserify, RequireJS etc.

What’s with the global _trackJs variable used for configuration?

It might look a little odd to declare a global variable before loading our script. We do things this way because we want to make sure TrackJS begins monitoring immediately upon initialization. TrackJS implicitly initializes itself - that is, it starts monitoring without any explicit code action by you. In order for that to work, the configuration needs to be present before TrackJS is loaded.

Advanced Configuration

The following is an annotated example of all the possible configuration options. Some of the more advanced ones are broken out and discussed in more depth in the tips and tricks documentation

window._trackJs = {

  // Specify your customer token.
  // The only mandatory configuration option we require.
  token: "",

  // Whether to activate the tracker script on the page.
  // Useful for disabling TrackJS in certain environments or situations
  enabled: true,

  // Callback that is fired before every error is tracked and sent over the network to our servers.
  // Returning false will prevent the error from sending.
  // You may also modify the error payload before it gets sent in this function.
  // Scroll down for more information.
  onError: function (payload) { return true; },

  // By default, we attempt to serialize objects into something you'd expect.
  // You can customize how we serialize objects by overriding this.
  serialize: function (what) {
    if (what && typeof what === "string") return what;
    else if (typeof what === "number" && isNaN(what)) return "NaN";
    else if (what === "") return "Empty String";

    var result;
    try { result = JSON.stringify(what); }
    catch (e) { result = "Unserializable Object"; }
    if (result) { return result; }

    if (what === undefined) return "undefined";
    else if (what && what.toString) return what.toString();
    else return "unknown";
  },

  // TrackJS allows you to track errors for multiple applications from the same account.
  // See the UI documentation for how to setup applications.
  application: "",

  // If you have some identifiable string that represents a user or customer, please include it.
  // In the TrackJS UI we allow you to group and filter by this value.
  userId: "",

  // Similar to userId, if you have a session guid or something you can set it here.
  // We allow you to search on this value in the UI.
  sessionId: "",

  // Whether the tracker should prevent duplicate error messages from being tracked
  // subsequently within a page view.
  dedupe: true,

  // This value will be included on all error details pages so you can see which version of your application caused the error.
  version: "",
  callback: {

    // TrackJS wraps addEventListener() and setTimeout() by default.
    // If you want to prevent this wrapping, set this to false.
    enabled: true,

    // Similar to "async" stack traces in Chrome developer tools, bindStack will attempt to produce stack traces that span async operations.
    // There is a slight performance impact to this option, though for most applications it's not noticeable.
    bindStack: false

  },

  console: {
    // By default TrackJS will watch all console activity and include that information in the Telemetry Timeline
    enabled: true,

    // Since TrackJS wraps the console, we can also prevent the messages from being output to the browser.
    // This is useful if you don't want your users seeing anything if they have the dev tools open.
    display: true,

    // By default any calls to console.error() will automatically trigger an error.
    // Set this to false if you don't want console.error() to trigger errors.
    error: true,

    // Whether to trigger an error on calls to `console.warn()`
    warn: false,

    // If you only want TrackJS to watch certain console functions, you may specify them here.
    watch: ["log","debug","info","warn","error"]

  },

  network: {

    // TrackJS will monitor network calls and add some metadata about them to your Telemetry Timeline.
    // If you don't want your network events monitored set this to false.
    enabled: true,

    // By default any network response with a status code of 400 or greater will trigger an error.
    // Set this to false if you do not wish to automatically track 400 or greater network errors.
    error: true

  },
  visitor: {

    // We add information to the Telemetry Timeline as the user is clicking or typing on your site.
    // Set this to false if you wish to disable it.
    enabled: true

  },

  window: {

    // TrackJS sets up a window.onerror function automatically.
    // Set this to false if you wish to use your own, or to manually track errors.
    enabled: true,

    // Whether to listen for global unhandled promise rejections.
    promise: true

  }
};

Configuration After Page Load

While we recommend configuring everything with the _trackJs global configuration variable, sometimes it’s not feasible. For example, you may not know the user ID right away. There are several properties which can be set at any time using trackJs.configure(). Keep in mind that any errors tracked before the configuration is applied will be missing that data.

The following are the properties that can be configured after tracker script initialization

trackJs.configure({

  userId: "John Doe"

  sessionId: "1acecc2b-395f-4aa8-b3a1-391c7336235d",

  version: "1.4.6",

  onError: function (payload){ return true; },

  serialize: function (item){}

});

Custom onError() Callback

When you specify an onError callback to ignore or modify errors (see Tips & Tricks for more information) you’ll be passed the error payload that will go to the server. Returning a falsy value from this callback will prevent the error from being transmitted. Returning true, but modifying the payload, is a way to add additional information at tracking time.

Here is the general shape of the object as well as property data types:

{
  "bindStack": "", // (mixed) Enable deep stack traces for asynchronous and event bound methods. Default "" if set
  "bindTime": "0000-00-00T00:00:00.000Z", // (timestamp) Timestamp for bindstack reference
  "console": // (array) Console events before error
  [
    {
      "timestamp":"0000-00-00T00:00:00.000Z", // (timestamp) Timestamp console event occurred
      "severity":"log", // (string) Severity of console event
      "message":"text" // (string) Message from console event
    }
  ],
  "customer": // (object) Customer information
  {
    "application": "", // (string) Customer Application ID
    "correlationId": "b986c8f2-1371-4df6-8c77-84e313c5b7ab", // (string) Unique generated ID for matching visitor to multiple errors
    "sessionId": "", // (string) Unique generated ID for matching sessions to errors
    "token": "ffa107642aec4670af7fbd64d7d0b960", // (string) Customer Token
    "userId": "", // (string) Customer provided UserID. Used to match error to users.
    "version": "" // (string) Customer provided Version. Used to match errors to versions.
  },
  "entry": "direct", // (string) Type of error. Can be "window","direct","global", "ajax" or "catch"
  "environment": // (object) Environment information
  {
    "age": 28566, // (number) How long user was on page in ms
    "dependencies": // (object) Libraries detected on the page
    {
      "jQuery": "1.11.2", // (string)
      "trackJs": "2.1.12" // (string)
    },
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/43.0.2357.130 Safari/537.36", // (string) User agent detected
    "viewportHeight": 456, // (number) Detected viewport height
    "viewportWidth": 1440 // (number) Detected viewport width
  },
  "file": "scripts.js", // (string) Filename reported if from a global error handler.
  "message": "TypeError: e is undefined, scripts.js, line 1", // (string) Error message
  "metadata": // (array) Custom metadata about the Environment
  [
    {
      "key": "", // (string)
      "value": "" // (string)
    }
  ],
  "network": // (array) Network events detected before error
  [
    {
      "startedOn": "0000-00-00T00:00:00.000Z", // (timestamp) Network event started at
      "method": "POST", // (string) HTTP method detected
      "url": "http://domain.com", // (string) Url detected
      "completedOn": "0000-00-00T00:00:00.000Z", // (timestamp) Network event completed at
      "statusCode": 200, // (number) HTTP status code detected
      "statusText": "OK" // (string) Status Text
    }
  ],
  "url": "http://domain.com/", // (string) Url error was detected on
  "stack": "", // (string) Stack trace of error
  "timestamp": "0000-00-00T00:00:00.000Z", // (timestamp) When the error occurred
  "visitor": // (array) User actions detected before error
  [
    {
      "timestamp": "0000-00-00T00:00:00.000Z", // (timestamp) When action occurred
      "action": "input", // (string) Action type
      "element": // (object) DOM element from action
      {
        "tag": "input", // (string) HTML tag detected
        "attributes": // (object) HTML tag attributes detected
        {
          "type": "text", // (string)
          "name": "s", // (string)
          "class": "form-control", // (string)
          "id": "searchBar", // (string)
          "placeholder": "Search ...." // (string)
        },
        "value": // (object) Input shape detected
        {
          "length": 0, // (number)
          "pattern": "empty" // (string) regex pattern match. Can be "empty", "email", "date", "usphone", "whitespace", "numeric", "alpha", "alphanumeric", "characters"
        }
      }
    }
  ],
  "version": "2.1.12", // TrackJS version detected on page
  "throttled": 0 // Message Throttle count
}