Nilavra Bhattacharya

Sign in

Record User Interactions on your Webpages: A tutorial

three person pointing the silver laptop computer
Photo by John Schnobrich on Unsplash

Logging user interactions on a webpage is an integral part of user research. This is a barebones tutorial to log events such as mouse clicks, mouse hovers, and visibility changes on a webpage being tested.

For the purposes of this tutorial, we will record user interactions only on pre-defined HTML elements on our webpage, e.g., some specific images, buttons, paragraphs, etc. We call these HTML elements as AOIs, or Areas of Interest. The final log produced will contain two items: aoi_dtl, and interaction_events.

aoi_dtl is an object of objects, containing the details of each AOIs, and aggregated interaction events (total click count and total hover duration in milliseconds). An example is below

interaction_events is an array of objects, containing a chronological list of all the interaction events that took place on the webpage, from page load, to when the user navigated away from the page. An example with the four types of interaction events (M_HOVER, M_CLICK, VISBILITY_HIDDEN, and VISIBILITY_VISIBLE ) is shown below.

The VISIBILITY_interaction events determine whether the current tab is visible, a proxy for whether the current tab is active.

Details about each of the recorded data values are shared in text, and/or code comments below.

Step 0: Pre-requisites

We depend on the following JavaScript libraries:

Step 1: Mark up your HTML

For each HTML element we are interested to track, we add a data-aoi attribute to that element. The value of the data-aoi attribute is the name of the AOI. This name serves as the key, and the value for the aoi_name attribute, in the aoi_dtl JSON object. These names show up in the final log data we collect. The following example shows two AOIs: a header-image, and an “Evaluate Results” button.

Step 2: JavaScript, at the beginning of user-journey

When the user browses to the page, we initialize our logging setup. This is usually inside the$(document).ready() function in jQuery.


First, we initialize the variables that will store the logged data.

Then we define two utility functions. The first function, get_ts_h converts Javascript Timestamps (milliseconds from Unix epoch) into human-readable format: “2021–07–21 15:43:48.119”.

The second function, get_bb_details, gets the bounding-box details of any HTML element, relative to the screen (monitor) and the webpage. These values can be used for correlating with, e.g., eye-tracking data.

Now we are ready to log user interactions.

Logging Mouse Clicks

Mouse click logging is adapted from this StackOverflow answer. Sometimes, the click event produces duplicate events on radio buttons, so we use mouseup event instead.

Logging Mouse Hovers

Mouse hover logging is adapted from this StackOverflow answer. First we define a threshold value HOVER_THRESH of 100ms (say). Then we log hover events that are at least 100ms or more.

Logging Whether the Current Tab is Visible

This logging is useful if the user clicks a link that opens a webpage in a new tab. Eventually, the user will return to “this” tab. In such cases, the following code adds a VISIBILITY_HIDDEN log-entry, when the user moves to the new tab; and a VISIBILITY_VISIBLE log-entry, when the returns to this tab.

Logging Other Interaction Events

We can add other types of logging events as well, by attaching event-listeners to the appropriate event, and pushing an object with required metadata in the interaction_events array. Examples of such events can include scrolling, right-clicks, text-entry, and others.

Step 3: JavaScript, at the end of user-journey

When the user has completed all the tasks on our webpage, and is ready to leave our page, we run the following code to collate all the log data together.

Populate aoi_dtl

The following code gets the details of all the AOIs in their final form, and populates the aoi_dtl object initialized at start.

At this point, the interaction_events array is fully populated, and can be used as-is. Now, you are free to take the appropriate action as required by your data pipeline. For example, you can append it to an existing form on the webpage, make an AJAX request to an API, or save the data in localstorage.

Thank you for reading. Please share suggestions, improvements, and/or comments below.

If you wish to cite this tutorial in your research, you can use the following:

author={Bhattacharya, Nilavra},
title={Record User Interactions on your Webpages: A tutorial},
note = "[Online]"

Human-computer Interaction (HCI) researcher. PhD Student at The University of Texas at Austin.