@ux-capture/ux-capture

v4.6.0

Published

2 years ago

Browser instrumentation helper that makes it easier to capture UX speed metrics

Downloads

0High
0Medium
0Low

sergeychernyshev

webperf perfmatters web performance ux speed user-timing

UX Capture JavaScript Library

Browser instrumentation JavaScript library that makes it easier to capture UX performance metrics using UX Capture approach

The intent of this library is to help developers instrument technical events (marks) on their pages and group them into "zones" that represent "phases" of page load, with each phase representing distinct stages of user experience.

React bindings for this library exists as a separate module @ux-capture/react-ux-capture

Usage

NOTE: this version of the library relies on UserTiming API to be available in the browser, but should not break if it doesn't. You can use a polyfill if you want to support older browsers.

Step 1: Inline the library in the `<head>` tag

Load the library by inlining the contents of ux-capture.min.js in a <script> tag in the HTML document <head>. Here's an example using server-side React:

const uxCaptureFilename = require.resolve('ux-capture/lib/ux-capture.min.js');
const uxCaptureJS = fs.readFileSync(uxCaptureFilename, 'utf8');
...
render() {
    <head>
        <title>My Page</title>
        <script dangerouslySetInnerHTML={{ __html: uxCaptureJS }} />
        ...
    </head>
    ...
}

NOTE: The script must be inlined. Do not use a script tag with a src attribute. Waiting for network requests might artifically skew event timings on the page and lead to race conditions.

NOTE: It is important to have this code available very early on the page since we need to instrument events that happen as early as HTML parsing, so ideally in the <head>.

Step 2: Initialize the library

Initialize UXCapture using UXCapture.create(), optionally with mark and measure event handlers, e.g.

<script>
UXCapture.create({
    onMark: name => console.log('marked', name),
    onMeasure: name => console.log('measured', name),
});
</script>

Custom event handlers are useful in cases where the monitoring solution you use (e.g., NewRelic) does not support the W3C UserTiming API natively. You can then provide a custom method of recording the results.

onMark - provides a custom handler to be called every time a mark is recorded with the name of the mark as the only argument
onMeasure - provides a custom handler to be called every time a measure is recorded with the name of the measure as the only argument

Step 3: Configure expected zones for the view

At the top of the view markup, define the expected zones and corresponding marks with UXCapture.startView(), e.g.

<script>
UXCapture.startView([
    {
        name: 'ux-destination-verified',
        elements: [
            {
                selector: "#logo",
                marks: ['ux-1', 'ux-2']
            },
        ]
    }, {
        name: 'ux-primary-content-available',
        elements: [
            {
                selector: "#intro",
                marks: ['ux-3']
            },
            {
                selector: "a.moreinfo",
                marks: ['ux-4']
            },
        ]
    }
    ...
]);
</script>

NOTE: UXCapture.startView() will throw an error if called while previous view is active, so be careful to only call it once.

Each individual zone configuration object contains of zone's name that will be used as a name of corresponding W3C UserTiming API measure and a list of elements comprising the zone with CSS or JS function selector that returns the node and marks array of individual event name strings, each individual mark name will be used when recording corresponding events as W3C UserTiming API mark.

Step 4: (optionally) Update zone configuration as page loads

You can optionally update a view that has already been started and add more zones by calling UXCapture.updateView().

Step 5: Mark individual events on the page

Call UXCapture.mark in the HTML markup for each ‘mark’ name passed into UXCapture.startView()/updateView().

<script>UXCapture.mark('ux-1')</script>
<img onload="UXCapture.mark('ux-2')" … />
...

Step 6: SPA views / transitions (if applicable)

For "interactive" view changes (usually associated with a route change), the client app must imperatively indicate when the current view is no longer valid using UXCapture.startTransition() call.

history.push(‘/foo’)
UXCapture.startTransition();

or, a little less controlled, using History API:

window.onpopstate = UXCapture.startTransition;

const pushState = window.history.pushState;
window.history.pushState = (...args) => {
	UXCapture.startTransition();
	return pushState.apply(window.history, args);
};

const replaceState = window.history.replaceState;
window.history.replaceState = (...args) => {
	UXCapture.startTransition();
	return replaceState.apply(window.history, args);
};

UXCapture.startTransition() call creates additional transitionStart UserTiming API mark to indicate the moment user interaction happened.

All measures in this interactive view will be recorded from this moment, rather than "natural" zero of page view's navigationStart provided by Navigation Timing API.

The call to UXCapture.startTransition does not need to be in the markup (and generally shouldn’t be).

Step 6A: Indicate which elements will persist or get removed

There are two methods of defining pre-existing elements on the page, by configuring selectors for elements in the zone or by explicitly clearing marks that correspond to these elements before next UXCapture.startView() is called.

If Zone is fully satisfied by pre-existing elements, it will be measured from and to transitionStart mark making it effectively a 0ms long.

Method 1: Use Selectors

When you configure Zones and corresponding elements in UXCapture.startView() call (see Step 3 above), you include selector property for each element which is either a CSS Selector string or a JS function that returns DOM nodes corresponding to the element.

Alternatively, you can select a selector attribute set to a JS function on the zone object as a whole and it will be called for each element in the zone passing element configuration as input.

These selectors would be used to determine if element is still present on the page and UX Capture will satisfy them immediately without expecting the marks fired for them.

Method 2: Clear Marks for Removed Elements

Clear any marks for elements that will not be resent on the subsequent view using UXCapture.clearMarks(name). To clear all marks, omit the name argument. Do not clear marks that are associated with elements that do not change between views.

Note: This method is used by react-ux-capture because it fits well with React's lifecycle methods, but might be hard to maintain in other applications.

Repeat

Repeat from the start for regular page views and from step 3 for SPA applications.

Sample page

This repository contains a sample page that implements basic instrumentation for your reference: https://www.ux-capture.org/examples/

Instrumentation

This documentation shows snippets of code using UX Capture JavaScript library, for more information on methods of individual element instrumentation, see project page.

Image elements

Image tracking requires two measurements, one within the onload callback of the image itself and another within inline <script> tag directly after the image.

<img src="hero.jpg" onload="UXCapture.mark('ux-image-onload-logo')">
<script>UXCapture.mark('ux-image-inline-logo')</script>

Text without custom font

Text that does not use a custom font can be instrumented by supplying one inline <script> tag directly after the text:

<h1>Headline</h1>
<script>UXCapture.mark("ux-text-headline");</script>

Text with custom font

Many pages use custom fonts to display text and often experience Flash of Invisible Text or FOIT. It is important to take into account time to load custom fonts. You can do it using font loaders provided by using event tracking in Web Font Loader used by Typekit and Google.

You can inline the library in HTML and then use the following code to fire a mark when font loaded.

<script>
WebFont.load({
    custom: {
        families: ["Montserrat:n4"]
    },
    active: function() {
        UXCapture.mark("ux-font-montserrat-normal");
    }
});
</script>

NOTE: See Font Variation Description format used by Web Font Loader for specifying particular font variation to track.

Similarly to tracking text without custom font, inject a mark inline after text that uses custom font in question.

<h2>Title with font</h2>
<script>UXCapture.mark("ux-text-title-using-montserrat-normal");</script>

Event handler attachment

Some user activity requires custom JavaScript handler code to be attached to an event on the page, e.g. click of the button (e.g. it's only "available" when visible AND clickable). Instrumenting handler attachment is straightforward, just include the call right after handler attachment in JavaScript code.

var button_element = document.getElementById('mybutton');
button_element.addEventListener('click', myActionHandler);
UXCapture.mark('ux-handler-myaction');

UX Capture API Specification and sequence diagram

For API specification and requirements, including sequence diagram, see UX Capture Core Library API Spec document.