Quick Start Guide

The Basics

Welcome to the LogUI client quick start guide! This page should provide you with all of the basic information that you need to get a bare-bones version of LogUI client up and running with one of your applications.

Bear in mind that at the moment, LogUI is specifically suited to a single page. You can of course expand on telling what LogUI to log (via the configuration object) to cover multiple pages, but support for this is still somewhat limited and will be improved upon over time. By a single page, we mean something like a results page from a search engine, where we wish to track interactions in a fine-grained manner.

Setting everything up depends heavily on your application, and how you have implemented. Since we cannot possibly provide detailed instructions for every application, we are going to a simple, example webpage as the basis for our application to show you what you need to do to integrate the LogUI client into it. The page is called Sample Search, and mimics a simple Search Engine Results Page (SERP), like what you would see after typing a query into Google, for example.

We'll walk you through all of the necessary steps to get Simple Search up and running with LogUI. Once you have an idea of what you can do (and how), you can then take more time reading the more in-depth documentation on how to configure the LogUI client.

For now though, this quick start guide is split up into seven main steps.

1. The first involves downloading the compiled library.
2. We then include the library in your application's static files and template(s).
3. Next, we configure the basic configuration object that tells LogUI what to log.
4. We then setup the LogUI server for your application.
5. We obtain the authentication token and include it in the configuration object.
6. We then write a small amount of JavaScript to start the LogUI client on a page load.
7. Try it out!

1. Download the Compiled Library

First, you need to acquire a copy of the LogUI client. You can do find out how to do this by reading the Acquiring the LogUI client Wiki page.

2. Include it in your Application's Static Files and Template

You then need to take the logui.bundle.js module you have downloaded/compliled, and place it in the static directory for your application.

The static directory is the location from which your application's server serves static files (such as CSS, JavaScript, and images). It may not be a simple directory; you may need to place it on some kind of CDN, if you have a complex setup!

From the screenshot above, we can see that the logui.bundle.js file has been placed into the js directory of our static directory for the sample-search app. While this 'application' is a simple webpage to demonstrate how the LogUI client works, the message is still served: place this file in a location that your web server will be able to host to any clients that request it.

You then need to open the basic HTML template for your application, and append a <script> tag to the bottom of the markup. Again, this will vary wildly depending on your environment, setup, and application — for a Django or other server-side implementation, for example, place this in the template(s) that will hold content you wish to track user interactions on.

Include the following snippet just after the </body> has been closed.

<script src="<PATH-TO-STATIC>/logui.bundle.js"></script>

Replace <PATH-TO-STATIC> with the necessary path to your static directory when it is being hosted by your webserver. This could be as simple as /static/, or may require something more extravagant, like a Django template tag — {% static 'logui.bundle.js' %}.

In the screenshot below, you can see the inclusion of the preceding markup snippet in the Sample Search template on line 73 of the presented file.

3. Create the Configuration Object

Next, you need to create what we call the configuration object. This is a JavaScript object {} that provides all of the necessary details for the LogUI client to start tracking information on your application. You can read the Configuration Object Wiki page for detailed information on what you need to supply.

For now, we're going to include the following simple configuration object in our template.

let configurationObject = {
    logUIConfiguration: {
        endpoint: 'ws://path-to-server:8000/ws/endpoint/',
        authorisationToken: 'TO-BE-FILLED-LATER',
        verbose: true,
    },
    applicationSpecificData: {
        userID: 123,
    },
    trackingConfiguration: {
        'querybox-focus': {
            selector: '#input-box',
            event: 'focus',
            name: 'QUERYBOX_FOCUS',
        },
        'querybox-losefocus': {
            selector: '#input-box',
            event: 'blur',
            name: 'QUERYBOX_BLUR',
        },
    },
}

Let's digest what is being done here. We'll split the explanation up into three main sections: one one logUIConfiguration; one on applicationSpecificData, and one on the trackingConfiguration.

Again, refer to the Configuration Object Wiki page for more detailed information.

The logUIConfiguration Component

This component of the configuration object requires two settings.

• endpoint This setting expects a string, which is the complete URL to access the LogUI server WebSocket. The path is always set to /ws/endpoint/. Join the full hostname (and port, if not running on port 80) to the path. If you are running LogUI server at someserver.tudelft.nl on port 80, you would enter ws://someserver.tudelft.nl/ws/endpoint/ for the endpoint setting. If an incorrect value is supplied, nothing will be logged!

• authorisationToken This setting expects a string; it is the authorisation token that you can obtain from the LogUI server control application for the flight you want to track interactions for. Refer to the LogUI server documentation for more information on how to obtain this token.

The property verbose is optional; this requires a boolean value, the default of which is false. In the example above, we switch it to true. Why? Turning on verbose permits the LogUI client to use the console to print information about what it is doing at any given time; use your browser's development tools to see the browser's console, and see the output. This is useful when checking to see if events are being logged correctly.

There is a fourth optional setting, browserEvents. Refer to the Configuration Object Wiki page for more information on this setting.

The applicationSpecificData Component

applicationSpecificData is a setting that allows you to provide additional information pertaining to your application. Whatever you provide here is sent with each interaction event captured by LogUI, and stored in the database on the LogUI server.

Examples of application specific data could be, for example, the userID for a given participant, or a value for the experimental condition or rotation that the participant is being subjected to. In the example above, we have provided userID with a value of 123 for the application specific data.

You can provide zero or more items, and even nest objects if required. You can specify strings, booleans, floats, or, as stated, other objects.

If you do not wish to provide application specific data, simply specify an empty object, like so:

applicationSpecificData: {}

The trackingConfiguration Component

The trackingConfiguration component is hugely important — this is where you tell LogUI what interactions track on your application's webpage(s). It is comprised of an array of so-called configuration groupings, where you link together one or more elements on your webpage(s) with an event, and provide additional information to be bundled with the event, when captured by LogUI.

Let's take a simple example from the example above.

'querybox-focus': {
    selector: '#input-box',
    event: 'focus',
    name: 'QUERYBOX_FOCUS',
}

First, let us examine the key of the key/value pairing, querybox-focus. This is a unique name that you provide to give yourself some understanding of what this configuration grouping representings. For example, querybox-focus denotes it considers the query box, and when the user activates — or focuses on — the query box. If you duplicate names in your configuration object, the LogUI client will take the last occurring grouping by that name and use it. You will also receive a warning in your browser's console if there is a naming conflict.

The value of the mapping is a further JavaScript object. You must provide the following two settings.

• selector The selector identifies what elements on the webpage being tracked by LogUI should be captured by this grouping. This selector is defined using CSS selectors. For example, #input-box will select the element on the page with the id of input-box — a further example .results li would select all list items (li) within all parents with the class results on your page.

• event What event do you want to track on the given element(s) selected above? This is where you specify the event. This can be any one of the standard DOM events, or a specific LogUI event that provides additional functionality. Refer to the Event Handlers Wiki for more information. In the example above, we use the standard focus event on an input element.

The third name setting is optional, but highly recommended. By entering a name to this grouping, you tell the LogUI client to bundle this name up when the event is captured. This allows you to then discern between events in your post-hoc analysis. For example, we'll be able to parse for QUERYBOX_FOCUS named events when we want to know when the user interacted with the query box.

There's more to it, but these are the absolute basics. Have a look at the Configuration Object Wiki page for more detailed information on what you can provide for configuration groupings, such as the inclusion of metadata.

CSS selectors are an incredibly powerful tool; they are by far the most straightforward way to identify what elements you want to track! Have a look at the MDN documentation on CSS selectors for more information.

4. Setup your LogUI Server Instance

Next, you'll need to tell the LogUI server that you'll want to track interactions for your application. Follow the information provided on the LogUI server Wiki for information on how to do this.

You'll need to get a copy of the authorisation token you create for the application flight you are using. Following the documentation above, you'll be able to acquire this token from the LogUI server control application. A sample screenshot is shown below demonstrating the interface.

5. Include the Authentication Token

Copy this token to your clipboard using the Copy Authorisation Token to Clipboard button. You should then paste this into your configuration object, as the value to the authorisationToken setting. Don't forget the two quote marks around the token to denote that it is a string! An example is shown below.

authorisationToken: 'eyJ0eXBlIjoibG9nVUktYXV0aG9yaXNhdGlvbi1vYmplY3QiLCJhcHBsaWNhdGlvbklEIjoiMmFkZmQ4YTItZGU5ZS00NGI1LTllODYtMDM1Mjg4ZjZlNzFmIiwiZmxpZ2h0SUQiOiJlZmYxZDA0MS02ZTNlLTQ2YWYtOTUxMC05ZGU1ZTA1NzgwYTEifQ:1lPtjD:ANoj9RYddsiIEH6Qa5iJa_uwZR84wiPW6ITUYndjs2I',

6. Drive the LogUI Client

Finally, you'll need tell LogUI when to start. The most basic code to do this is when the page you are tracking interactions on has loaded. You can include the following JavaScript code in your template to instruct LogUI to start when the page loads.

<!-- This <script> tag comes from step 2. -->
<script src="<PATH-TO-STATIC>/logui.bundle.js"></script>

<!-- Place this short script *after* including the LogUI client bundle. -->
<script>
    let configurationObject = {
        // ...
        // Configuration object contents placed here.
        // ...
    };

    document.addEventListener('DOMContentLoaded', function() {
        LogUI.init(configurationObject);
    });
</script>

This script appends an event listener to your page when the DOMContentLoaded event is fired. This denotes when the DOM (the elements on the initial page render) have been loaded. When this happens, we tell the LogUI client (at object LogUI) to init(). The init() call takes a single parameter — your configuration object.

This script can be expanded to consider other aspects of your page; you can even programmatically generate your configuration object if you so desire. Of course, this script can also be farmed out to a separate JavaScript file, which would reduce your separation of concerns.

LogUI can also be started and stopped at different points throughout the lifecycle of a page. In this simple example, we start LogUI when the page loads, but there is nothing to stop you from starting LogUI at different points in the page's life. We also provide a stop() call on the LogUI object, which stops all interaction logging. For more information on how to integrate the LogUI client with your application, refer to our shorthand guide on the API that is provided.

7. Try it out!

The final step is to try it out! It is imperative that you test things carefully to ensure that all the events you wish to capture are being logged. While we will be providing infrastructure to assist you with that in the future, one idea would be to enable verbose logging in the browser (with verbose: true), and use an experimental flight for testing.

This way, you'll be able to witness the events being logged in the console of the browser as they happen, and the interaction logs stored on the server will not be interfering with the flight dedicated to your experiment proper.

In the example screenshot below, note the Google Chrome developer tools showing the console. The events that are captured are output to the console. These can be expanded to show you the details being sent to the LogUI server.