Skip to main content

Tracking script

The tracking script tracks user actions on your website.

Loading the script​

By default the script can be fetched from https://cdn.ndrstnd.io/ndrstnd-v1.js, or, if you configured a tracking subdomain, from https://{your subdomain}/scripts/ndrstnd-v1.js.

The script can be added directly to a website, but we recommend using the following snippet so the commands issued through the global ndrstnd function are stored in a queue until the script has finished loading:

<script>
    (function (w, d, s, u, n, e, a) {
        w["NDRSTND_ALIAS"] = n; w[n] = w[n] || function (cb) { (w[n].q = w[n].q || []).push(cb); };
        e = d.createElement(s); e.src = u; e.async = 1;
        a = d.getElementsByTagName(s)[0]; a.parentNode.insertBefore(e, a);
    })(window, document, "script", "https://cdn.ndrstnd.io/ndrstnd-v1.js", "ndrstnd");
</script>

In this example, the last two parameters passed to the function configure, respectively:

  • the URL the script is fetched from
  • the name of the global function defined on the window object used to talk to the API (ndrstnd from here on)

Usage​

The ndrstnd function runs commands as callbacks whose first parameter is the client used to talk to the API (this pattern makes it possible to defer running the commands until the script is loaded).

ndrstnd(function(client) {
    // code to run
});

Creating a tracker​

A tracker is an object created by the client that sends data to the API for a specific project. To create a tracker, call the client's createTracker method.

ndrstnd(function(client) {
    const tracker = client.createTracker("projectId");
    // ...
});

The createTracker method takes the Webmarketer project identifier as its first parameter. It also accepts, as a second parameter, an object that configures the tracker.

ndrstnd(function(client) {
    const tracker = client.createTracker(
        "projectId",
        // default option values:
        {
            cookieName: "ndrstnd",          // name of the JavaScript cookie set by the script
            cookieDomain: "auto",           // domain the JavaScript cookie must be set on
            name: "default",                // tracker name (useful when several trackers are created with the same client)
            ndrstndDomain: `ndrstnd.io`,    // tracking domain
            spaCompatibilityEnabled: true,  // enables compatibility with SPA applications
        },
    );
    // ...
});

cookieName​

When the script loads, a JavaScript cookie is set on the website; by default that cookie is named ndrstnd. To avoid a possible conflict, the cookie name can be changed by setting the cookieName value.

cookieDomain​

By default the script sets the JavaScript cookie on the highest possible level domain, which lets a set of subdomains of your website share the same cookie. That behavior can be changed by setting the cookieDomain value.

Invalid domain

If the configured domain is neither the current domain nor a parent of it, a warning appears in the console and the cookie is set on the highest possible level domain (the default behavior).

name​

The tracker name, useful to tell apart the trackers created by the client when there are several of them.

ndrstndDomain​

By default the script talks to the API on the ndrstnd.io domain. When a project is configured to use a tracking subdomain, the configured subdomain must be provided in the ndrstndDomain option.

spaCompatibilityEnabled​

This option enables automatic compatibility with SPA (single-page application) applications.

How it works

show more

A page's referrer is the URL of the website the visitor came from. Webmarketer uses that information to analyze which search engine, social network or other website brought you traffic.

To count sessions correctly, Webmarketer needs the referrer to be set properly, otherwise users' browsing sessions cannot be built correctly.

In SPA applications, the page referrer is not updated while navigating, which distorts how sessions are built. To work around that, the tracking script uses the previous page view as the referrer of each page view sent (for the first page view, the referrer is set to document.referrer).

I want to implement a different behavior

show more

If you want to implement a different behavior, disable this option and implement your own logic to provide the referrer to the tracker.

Here is an example of setting the referrer manually:

ndrstnd(function(client) {
    const tracker = client.createTracker("projectId", { ndrstndDomain: "subdomain.my-website.com" });
    tracker.send("pageview", {r: "https://my-website.com/page-1"});
});

Retrieving a tracker​

An already created tracker can be retrieved through the client's getTracker method.

ndrstnd(function(client) {
    const tracker = client.getTracker("trackerName");
    // ...
});

If no name is passed to the method, it returns the tracker named default.

Listing trackers​

The names of the trackers created with the client can be listed through the getTrackers method.

ndrstnd(function(client) {
    const trackers = client.getTrackers();
    console.log(trackers);
    // ["tracker1", "tracker2", ...]
});

Sending data to the API​

A tracker's send method sends data to the API.

tracker.send("pageview");

The send method takes:

  • the message type to send (here pageview) as its first parameter
  • an optional object as its second parameter, to add information to the message as key/value pairs
Page views

For user sessions to be consistent in Webmarketer, it is important to send a pageview message every time the user navigates to a new page of the website.

Examples​

<script>
    (function (w, d, s, u, n, e, a) {
        w["NDRSTND_ALIAS"] = n; w[n] = w[n] || function (cb) { (w[n].q = w[n].q || []).push(cb); };
        e = d.createElement(s); e.src = u; e.async = 1;
        a = d.getElementsByTagName(s)[0]; a.parentNode.insertBefore(e, a);
    })(window, document, "script", "https://cdn.ndrstnd.io/ndrstnd-v1.js", "ndrstnd");

    // create a tracker for project "projectId" and send a pageview
    ndrstnd(function(client) {
        const tracker = client.createTracker("projectId");
        tracker.send("pageview");
    });
</script>