Configuration Object

What is the Configuration Object?

The configuration object is a JavaScript object {} that is passed to the LogUI client when it is started/initialised. This object is hugely important. It tells the LogUI client some key information, including:

• what the corresponding LogUI server endpoint URL is;
• what the authorisation token is to enable communication with the server;
• details on what browser wide events should be tracked; and
• details on what element level events should be tracked.

What does it Look Like?

We provide a complete example of a configuration object below for your reference. We'll provide subsections below, providing detailed information on each of the different components of the configuration object.

Providing a badly-formed configuration object — or providing a configuration object with missing required settings — will result in an Error being raised by the LogUI client.

let configurationObject = {
    logUIConfiguration: {
        endpoint: 'ws://path-to-server:8000/ws/endpoint/',
        authorisationToken: 'AUTHTOKEN',  // The authorisation token.
        verbose: true,
        browserEvents: {
            // See the Browser Events Wiki page.
        }
    },
    applicationSpecificData: {
        userID: 123,
    },
    trackingConfiguration: {
        'querybox-focus': {
            selector: '#input-box',
            event: 'focus',
            name: 'QUERYBOX_FOCUS',
        },
        'querybox-losefocus': {
            selector: '#input-box',
            event: 'blur',
            name: 'QUERYBOX_BLUR',
        },
        'left-rail-item-mousemovements': {
            selector: '#left-rail-results li',
            event: 'mouseHover',
            properties: {
                mouseenter: {
                    name: 'LEFT_RAIL_RESULT_HOVER_IN',
                },
                mouseleave: {
                    name: 'LEFT_RAIL_RESULT_HOVER_OUT',
                }
            },
            metadata: [
                {
                    nameForLog: 'resultRank',
                    sourcer: 'elementAttribute',
                    lookFor: 'data-rank',
                }
            ]
        },
    },
}

logUIConfiguration

The logUIConfiguration object provides details and settings global to the instance of the LogUI client that you are initialising. Two settings are required; two are optional. These are listed and detailed below.

• endpoint (Required) The endpoint setting expects a string; this string represents the full URL of the WebSocket endpoint for the LogUI Server you will connect to. 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, the LogUI client will fail to connect, nothing will be logged!

• authorisationToken (Required) The authorisationToken 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.

• verbose (Optional; default false) This setting is a boolean; it denotes whether the LogUI client should output to the browser's console information about what is happening internally within the client at any given time. This is a useful option for debugging. Set this setting to true to see detailed output from the LogUI client (especially when events are captured and logged); set it to false in a production environment. Error messages when verbose is set to false will still be visible in the browser's console.

• browserEvents (Optional; if not supplied, default settings applied) The browserEvents setting expects a nested JavaScript object; the settings provided here vary depending on the browser event handlers present. Refer to the Browser Events Wiki page for more information on what can be provided here.

applicationSpecificData

applicationSpecificData is a setting that allows you to provide additional information about your application that is stored with each captured event by the LogUI client. This information could, for example, include information on the userID that a participant is assigned; it could also provide the experimental condition they have been assigned to. The idea here is that by attaching this information to each logged event, you'll then be able to filter events by, say, the condition to obtain average summary statistics for a given experimental condition.

The information you provide applicationSpecificData is appended to every logged interaction by the LogUI client. You can alter the application specific data while the client is running by using the LogUI client API — refer to functions deleteApplicationSpecificDataKey() and updateApplicationSpecificData() for more information.

Application specific data is provided in a nested JavaScript application, such as shown in the example below.

...
applicationSpecificData: {
    userID: 123,
    condition: 2,
}
...

You can even nest JavaScript objects, too, like so.

...
applicationSpecificData: {
    userID: 123,
    condition: 2,
    loginDetails: {
        loggedInTimestamp: 1616942617,
        completedDemographics: true,
    }
}
...

Whatever information you need to provide here, the LogUI client will support it. The only caveat is that any objects placed here must be serialisable!

If you do not require to provide application specific data, simply provide an empty JavaScript object, as shown below.

...
applicationSpecificData: {}
...

trackingConfiguration

The third component of the configuration obejct is the trackingConfiguration. This component houses all of the details required for determing what elements to track, and what events to track on those elements. In addition, you can specify here additional information to be captured when an event takes place on a specified element — we call this metadata.

The trackingConfiguration is an array of JavaScript objects; each object represents the mapping between an element and an event. Note that metadata and properties are optional. We list an example trackingConfiguration mapping object below for reference. This example makes use of all four settings.

'left-rail-item-mousemovements': {  // Mapping name (between element(s) and event)
    selector: '#left-rail-results li',  // Selector
    event: 'mouseover',  // Event
    name: 'LEFT_RAIL_ITEM_MOUSEOVER',  // Log event name
    metadata: [  // Metadata (optional)
        {
            nameForLog: 'resultRank',
            sourcer: 'elementAttribute',
            lookFor: 'data-rank',
        }
    ]
},

• Mapping Name The mapping name is a unique string identifier that you can use to identify what this mapping corresponds to. As an example, you may wish to identify the element(s) and event that you are mapping together, as shown in the example above. The naming convention is however left entirely up to you.

Mapping names must be unique — two or more identical names will result in the last mapping occurrence with that name being used, with the other(s) discarded. In this scenario, the LogUI client will also output a warning to the browser's console.**

• selector (Required) The selector is a string that tells the LogUI client what element(s) should be selected for this mapping. In other words, what element(s) on the page should have the following event listener (specified by event) applied to them? To specify this, you must use a CSS selector. Any standard CSS selector will work — for example:

  • #elementID will select an element on the page with the id attribute elementID;
  • .className will select element(s) on the page that have the class className assigned to them; or something more complex
  • ol.resultsList li will find the ordered list (ol) element(s) with the class resultsList, and select all of their children of the li tag (list item).

  You can refer to the MDN documentation on CSS selectors for more information on how to use them. We will be developing this further over time to make things easier; for now, this is the most straightforward and universally accepted way to identify element(s) to manipulate on a webpage.

• event (Required) The event setting requires a string which specifies what DOM event you want to bind to the element(s) (defined above by selector) selected.

  • As an example, you may use the event mouseover event to identify when the user's mouse cursor hovers over the element(s) in question. Similarly, click would identify when the user clicks on an item.
  • We also provide LogUI event handlers which can map together multiple DOM events into a single LogUI event handler. They also provide functionality for additional checks, if required. As an example, the mouseHover LogUI event handler combines both mouseentry and mouseout events into a single event that you can specify in a configuration object.
  • As such, the logic behind parsing the event is straightforward: if a LogUI event handler is present with the name specified, that is used. Otherwise, this falls back to the standard DOM event listener, which is attached to the element(s) in question. For more information on how this works, and what LogUI event handlers are available, refer to the Event Handlers Wiki page.

  Refer to the MDN documentation on DOM events for more information on what events you can use. This approach will be developed further over time to make things simpler for users of LogUI. We will be developing more LogUI event handlers to make the process of identifying elements and events to be a more streamlined and simple process.

• name (Optional, but highly recommended) The name setting is optional, but highly recommended. This setting attaches a name to the captured event in question, allowing you to then identify in your post-hoc log parsing what the captured event belongs to. In the example above, LEFT_RAIL_ITEM_MOUSEOVER is applied to the mapping example provided. This name would show in the log, so filtering or looking for LEFT_RAIL_ITEM_MOUSEOVER named events in the corresponding log will provide you wil all of the entries tied to this mapping.

• metadata (Optional) Finally, the optional setting metadata allows you to obtain and attach additional data to the log entry for the event mapping in question. Data can be attached from a variety of sources; refer to the Metadata Sourcers Wiki page for further information.