Browser Events

Capturing Browser-wide Events

Browser-wide events are events that do not pertain to a specific element on your application's webpage(s); rather, they are associated with the browser as a whole. Instead of applying a listener to a specific element to determine if a user clicks on it or not with his/her mouse cursor, a browser-wide event could for example be a resize event, where the end user resizes the viewport of the web browser.

Out of the box, LogUI provides you with a series of different browser-wide events that you can track. These can be enabled or disabled within the browserEvents setting in the LogUI client configuration object; some can even be configured to behave differently. Some of these settings also influence how the LogUI client behaves when capturing other events, too.

Below, we provide details on each of the implemented browser-wide events. We also provide details on how you can enable/disable/configure them using the configuration object.

Use of the browserEvents object

In order to enable/disable/configure these browser-wide events, use the browserEvents setting in your LogUI client configuration object. An example is provided below.

let configurationObject = {
    logUIConfiguration: {
        ...
        browserEvents: {
            contextMenu: false,
        },
    },
    ...
};

Note that ... denotes additional settings that you have provided, such as the trackingConfiguration.

In this simple example above, we provide the setting contextMenu, setting it to false. As outlined below, this has the effect of disabling tracking for when a user right clicks on a page, bringing up the context menu. Setting this to true will enable the tracking of this behaviour.

Names of the settings to use for each event are shown with the browserEvents setting tag.

Available Browser Events

Below, we provide a list of all of the browser-wide events that can be currently captured with the LogUI client.

Block Events while Scrolling

• browserEvents setting: eventsWhileScrolling
• Default (unsupplied) setting: true (Enabled)
• Appears in log as: N/A

The eventsWhileScrolling setting provides global functionality to the LogUI client. One of the biggest problems we have encountered with interaction data is the addition of erroneous logged events while a user scrolls up and down the page. There may be extra hover events, for example, which can mess up you analysis scripts. Enabling eventsWhileScrolling temporarily disables event capturing while a scroll event is taking place on the page. This should hopefully alleviate and reduce the potential for capturing erroneous data.

By default, this is enabled. Set eventsWhilScrolling to false to disable this feature, and allow for the capturing of events while scrolling. No log events are recorded with this setting.

URL Changes

• browserEvents setting: URLChanges
• Default (unsupplied) setting: true (Enabled)
• Appears in log as: URLChange

The URL changes setting determines whether any change to the URL as displayed in the browser's address bar should be logged. This is particuarly useful for contemporary JavaScript web applications made in React, for example. These applications often change the URL in the address bar without reloading the webpage from the webserver.

Specifying URLChanges as true will enable this event tracking functionality; false will disable it.

With this event enabled, a corresponding log entry will have two additional fields:

• previousURL, yielding the URL as it appeared in the address bar before the change; and
• newURL, yielding the URL as it now appears in the address bar.

Context Menu

• browserEvents setting: contextMenu
• Default (unsupplied) setting: true (Enabled)
• Appears in log as: contextMenuFired

The context menu setting allows for tracking across the page when the context menu appears. This typically happens when right clicking on an area of the page. When set to true, displaying the context menu will be logged. When set to false, this event is ignored.

Page Focus

• browserEvents setting: pageFocus
• Default (unsupplied) setting: true (Enabled)
• Appears in log as: viewportFocusChange

The viewportFocusChange setting allows for you to capture when the browser that events are being captured in loses focus (i.e., it is no longer the active window). Conversely, it also captures events when the browser gains focus (i.e., it becomes the active window).

By default, this functionality is enabled. Set pageFocus to false to disable it.

When recording this event, the LogUI client will name the event type as viewportFocusChange, and will include an addition property, hasFocus. This is a boolean, and will state true if focus has been gained by the browser, or false if focus has been lost by the browser.

Tracking Cursor Movements

• browserEvents setting: trackCursor
• Default (unsupplied) setting: true (Enabled)
• Appears in log as: cursorTracking (positionUpdate)

Put simply, the trackCursor setting enables (true) or disables (false) cursor tracking within the viewport of the browser. This feature allows the LogUI client to capture the position of the cursor in the viewport at periodic intervals, or whenever the cursor position changes within the viewport.

The interval at which you would wish to track the cursor's location can be varied, and the interval at which you track the event will depend on the use case you have. If cursor tracking is of paramount importance, you may wish to log an event whenever the cursor's position in the viewport changes, rather than wait x milliseconds.

The cursorUpdateFrequency setting lets you specify this interval.

• Setting cursorUpdateFrequency to 0 will ensure that whenever the cursor moves in the active viewport, an event will be logged.
• A value for cursorUpdateFrequency greater than 0 will ensure that the cursor position is logged every x milliseconds, where x is the value specified.
• If cursorUpdateFrequency is not set, the default value for this setting is 200, meaning the cursor will be tracked every 200 milliseconds.

When logging this event, the LogUI client will record a cursorTracking event. There are three kinds of trackingType provided.

• positionUpdate provides an update of when the cursor has moved in the viewport only.
• cursorLeftViewport provides an update when the cursor moves outside of the browser's viewport.
• cursorEnteredViewport provides an update when the cursor moves within the browser's viewport, from the outside.

All three of these trackingTypes come complete with:

• clientX, the X coordinate in the browser's viewport;
• clientY, the Y coordinate in the browser's viewport;
• screenX, the X coordinate in relation to the user's monitor;
• screenY, the Y coordinate in relation to the user's monitor;
• pageX, the X coordinate in relation to the entire page (not considering the viewport);
• pageY, the Y coordinate in relation to the entire page (not considering the viewport);
• pageHadFocus, a boolean that states whether the page with event tracking was the active window at the time (true if yes, false if no).

Note that all X and Y coordinates relate to the origin at the top left of the browser's viewport/page/screen.

Resizing the Viewport

• browserEvents setting: pageResize
• Default (unsupplied) setting: true (Enabled)
• Appears in log as: viewportResize

The pageResize setting enables or disables the LogUI client's ability to capture viewport resize events. This means resizing the browser window. The event can capture and record the new dimensions of the viewport.

By default, this setting is set to true; set it to false to disable this functionality.

When recording this event, the LogUI client will report a viewportResize event. In addition, three additional values will be recorded:

• the new width of the viewport (in pixels), viewportWidth;
• the new height of the viewport (in pixels), viewportHeight; and
• a string representing both the width and height in the form {width}x{height}.

Note that LogUI attempts to reduce the amount of noise recorded through this event; rather than capture every pixel change (as many browsers do), the LogUI client attempts to record only the final set of dimensions that the user settles on. This is achieved by pausing the listening for page resize events every 200 milliseconds after one has been fired.