How monitoring.js works

The JavaScript tracking snippet defines a global kuoll function known as the 'command queue'. It's called the command queue because rather than executing the commands it receives immediately, it adds them to a queue that delays execution until the monitoring.js library is fully loaded.

In JavaScript, functions are also objects, which means they can contain properties. The tracking snippet defines a q property on the kuoll function object like an empty array. Before the monitoring.js library being loaded, calling the kuoll() function appends the list of arguments passed to the kuoll() function to the end of the q array.

Once the monitoring.js library is loaded, it inspects the contents of the kuoll.q array and executes each command in order. After that, the kuoll() function is redefined, so all subsequent calls run immediately.

This pattern allows developers to use the kuoll() command queue without having to worry about whether or not the monitoring.js library has finished loading. It provides a simple, synchronous-looking interface that abstracts away most of the complexities of asynchronous code.

Adding commands to the queue

All calls to the kuoll() command queue share a common signature. The first parameter, the 'command', is a string that identifies a particular monitoring.js method. Any additional parameters are the arguments that get passed to that method.

The method a particular command refers to can be a global method, like create, a method on the kuoll object or it can be an instance method on a tracker object, like send. If the kuoll() command queue receives a command it doesn't recognize, it just ignores it, making calls to the kuoll() function very safe, as they will almost never result in an error.

Command parameters

Most monitoring.js commands (and their corresponding methods) accept parameters in some different formats. That is done as a convenience to make it easier to pass commonly used fields to specific methods. All monitoring.js commands accept a final `params` parameter that can be used to specify any fields as well. For example, 'startRecord' call can look like:

kuoll("startRecord", {
    API_KEY: "YOUR_API_KEY"
    userId: 123, 
    userEmail: "example@kuoll.io",
    notes: "Anything"
});