Tracking User Activity with JavaScript

CommonWeb is no longer recommended for tracking user activity. Instead, we suggest using the Keen Tracking.js library. You can find it here.

CommonWeb is an open-source JavaScript library that captures and analyzes various user activities on your website. By listening for pageviews, clicks, form submissions, and more, CommonWeb generates a stream of event data in JSON format, complete with useful properties.

This data can be leveraged to compute traditional web metrics such as visits, time on site, bounce rate, and content ranking. Moreover, CommonWeb seamlessly integrates with services like Keen IO, providing robust tools for analyzing and reporting streams of event data.

The Philosophy Behind CommonWeb

Unlike an analysis tool, CommonWeb primarily functions as a collection tool. It simplifies the process of data collection, automating the gathering of 80% of common web events and properties that are universal for most websites. This feature enables basic reporting without much effort.

However, the analysis of the collected data varies depending on the specific needs of your users and your website. For instance, your definition of a “cohort” may differ significantly from that of another company.

CommonWeb empowers you to:

  • Automatically collect the 80% of interesting web events and properties.
  • Customize or add new events and properties that are specific to your website.
  • Send data to configurable back-ends or trigger JavaScript callbacks.

By consistently capturing web analytics data in a configurable manner, CommonWeb ensures that reporting tools built with this library in mind can benefit anyone.

Boost Your Web Analytics Game with Keen IO

If you’re already a Keen IO user, CommonWeb can help you level up your web analytics game. It streamlines your tracking process, potentially eliminating the need for old tracking code while providing new insights into user behavior. Please note that CommonWeb is not a replacement for keen-js; rather, it builds on top of it, offering a higher level of abstraction and a well-defined data model.

See also  JavaScript Proficiency Test

Installation

To get started, download common-web.min.js from the provided repository and include it in your project. If necessary, adjust the file path (/javascripts/common-web.min.js) to match your project’s structure.

Please ensure that you have the following dependencies installed before including common-web.min.js:

  • jQuery (required)
  • Keen IO JS SDK v3 (required if using Keen as a backend for captured JSON data)

Remember to include the dependencies before including common-web.min.js itself. Here’s an example of how to include both jQuery and Keen IO:

<script src="jquery.js"></script>
<script src="keenio.js"></script>
<script src="/javascripts/common-web.min.js"></script>

If you’re using the Keen IO backend, you need to inform CommonWeb about the Keen.Client instance you want it to use for recording events. You can do this by using the CommonWeb.Keen callback:

CommonWeb.Keen(client);

Usage

Once all the required JavaScript files have been included, you can start making calls to the CommonWeb object. The CommonWeb API provides several trackXXX methods for initializing tracking on pageviews or events associated with specific HTML elements. Here are examples of each:

CommonWeb.trackPageviews();
CommonWeb.trackClicks();
CommonWeb.trackFormSubmissions();

Blocking vs. Non-Blocking

Most links (<a> tags) and traditional non-AJAX form submissions unload pages when clicked, taking the user to a new page. If the page unloads before an event recording is completed, the event may go unrecorded, leading to inaccurate data. This is a common issue in web analytics that often goes unnoticed.

To mitigate this problem, CommonWeb allows you to explicitly specify when to work around this scenario. By informing CommonWeb about the links/forms that will unload the page, CommonWeb can prevent the default browser action, record the event with the backend, and then proceed with the action.

See also  Learning JavaScript from Java

Here are the methods that alter default behavior:

  • trackClicks
  • trackFormSubmissions

On the other hand, these methods have a more passive approach and do not interrupt the normal event flow:

  • trackClicksPassive
  • trackInputChanges
  • trackFormSubmissionsPassive (coming soon)

Specifying HTML Elements (Recommended)

If you only want specific elements to be tracked, you can pass them as the first argument to the track methods. This approach allows for more granular control over tracking. For example:

CommonWeb.trackClicks('.button');
CommonWeb.trackFormSubmissions('form');

The same arguments can be used for tracking non-link clicks and forms.

Words of Caution

While CommonWeb aims to make tracking automatic, it acknowledges that tracking certain elements may not be desired or may cause unexpected behavior. Therefore, it’s preferable to explicitly pass the elements you care about instead of capturing everything. Additionally, be cautious not to wire up the same element multiple times to avoid redundancy.

Specify Additional Properties

The default data model for CommonWeb represents events and includes certain properties. However, there may be instances where you need to include additional properties. For example, you might want to include user properties to facilitate further segmentation analysis.

You can add global properties that will be merged into every captured event on the page:

CommonWeb.addGlobalProperties({
  'user_type': 'paid',
  'subscription_level': 'gold'
});

Alternatively, if you wish to add properties to a specific element’s click event:

CommonWeb.trackClicks('.button', {
  'button_type': 'primary',
  'cta_text': 'Sign Up'
});

You can even pass a function to compute properties lazily at the time of the event:

function computeProperties() {
  return {
    'timestamp': Date.now(),
    'location': window.location.href
  };
}

CommonWeb.trackClicks('.button', computeProperties);

Custom Backend

While CommonWeb currently supports only one backend, you can specify your own backend by defining it as a function.

function customBackend(data) {
  // custom backend implementation
}

CommonWeb.setBackend(customBackend);

Data Model – Event Types

CommonWeb categorizes events into several types based on user interactions, including pageviews, clicks, and form submissions. The event type is added to the JSON payload representing each event, allowing for easy analysis.

Data Model – Event Properties

The CommonWeb library captures certain properties with every event by default. These properties include:

  • page_url: The URL of the current page (window.location.href).
  • referrer_url: The URL of the page that directed the user to the current page (document.referrer).
See also  Introducing ProgramMatek: Your Ultimate JavaScript Code Generator

Additionally, JavaScript event and HTML element objects are converted into JSON structures and placed at the event and element top-level keys, respectively.

Session Tracking

CommonWeb offers session tracking, allowing you to generate a user-specific GUID that accompanies all CommonWeb events. This GUID is stored in the user’s cookies for up to one year, enabling you to associate future events with the same user.

To activate session tracking, use the following code:

CommonWeb.trackSession();

The trackSession method also accepts two arguments: the name of the cookie to use and the GUID to use if there isn’t already one stored. You can pass them in like this:

CommonWeb.trackSession('my_cookie', 'my_guid');

Keen Backend

(Documentation needed here)

Here’s an example of a click event captured by CommonWeb with Keen IO as the backend:

{
  "type": "click",
  "element": {
    ...
  },
  "properties": {
    "page_url": "https://www.example.com",
    "referrer_url": "https://www.google.com",
    ...
  }
}

Further Documentation and Examples

For more information and detailed examples, please refer to the example page with Keen IO as the backend. After cloning the project and opening index.html, you can access the console to fill out your Keen IO project information. The example page showcases various elements, allowing you to click on each and observe the generated events in the JavaScript console.

Contribution

Setup

To contribute to CommonWeb, follow these steps:

  1. Install Node.js if you haven’t already.
  2. Use npm to set up the project dependencies:
npm install
  1. If Gulp is not installed globally, install it using the following command:
npm install -g gulp

Building

You can build the project by running the gulp task:

gulp build

If you want automatic rebuilds whenever a file changes, you can start a watch using either Gulp or the npm hook.

Wishlist

Here are some features that we’d love to have in CommonWeb:

  • Tests
  • Timeout and continue if a backend takes too long
  • Session ID and session age properties
  • Capturing additional common interactions (e.g., time on page)
  • Creating dashboards and visualizations based on the captured data
  • AJAX form handling

License

FOSSA Status
The project is licensed under the MIT License.