API

The LogUI Client API

How do you interact with the LogUI client library programmatically? How do you integrate the LogUI client into your application's codebase? In order to answer these questions, we've created this short page to provide you with information on the functionality offered by the public-facing LogUI client library API.

When loaded correctly, the LogUI client will always be available at the LogUI object — or, to be more precise, window.LogUI. Using your browser's console, you can interact and play with the API to get an understanding of what each of the exposed functions does, and complement that with reading the descriptions offered below.

Note that the config object is included for debugging purposes. It will be removed in a later release. Do not assume that this object will be available to you in the future!

Exposed Properties and Functions

Find the header for the property/function you are interested in below.

buildDate

This property yields a string of the date and time when the LogUI library you are using was compiled.

buildEnvironment

This property yields a string, production when you are using a production-ready version of the LogUI client. The other option is test, which is compiled with a special test harness and should not be used in webpages.

buildVersion

This property yields a string that reports the version of the LogUI client being used. If you find yourself having issues connecting to the LogUI server, you can check this property to ensure that you are using the correct version of the LogUI client for the version of the LogUI server that you are running.

clearSessionID()

This function removes any session ID that is currently stored by the LogUI client to help in identifying itself to the server. A session is created the first time a user's browser connects to the LogUI server from an unknown browser; this session will persist across all subsequent page loads from that server until the user browser closes the browser window.

You can force the LogUI client to surrender this unique session ID and request a new session begin by calling this function. This could be useful, for example, if you run an experiment on a single page (through some JavaScript application), and a natural break point is reached. If you want to split the interactions up between sessions, you can call this function.

You cannot call clearSessionID() while the LogUI client is running; if you do, it will throw an Error and will continue to run.

deleteApplicationSpecificDataKey(key)

This function manipulates the application specific data object that is appended to each event captured and logged by the LogUI client. You may find that during the course of an experiment or the lifespan of a page, you will want to alter the application specific data. This function allows you to delete a key in the object.

If your configuration object when initialising the LogUI client consists of the following applicationSpecificData object:

applicationSpecificData: {
    userID: 123,
    condition: 4,
    rotation: 2,
    consentProvided: false,
    deleteMe: true,
}

and you decide you want to remove the deleteMe key, issue the following command.

LogUI.deleteApplicationSpecificDataKey('deleteMe');

This will result in the applicationSpecificData object being updated to reflect the deletion, and will look like this.

applicationSpecificData: {
    userID: 123,
    condition: 4,
    rotation: 2,
    consentProvided: false,
}

All subsequent interaction events captured and logged with the LogUI client will then append the updated applicationSpecificData object to the event when sending back to the server for storage.

If you provide a key that does not exist, the deleteApplicationSpecificDataKey() deleteApplicationSpecificDataKeyfunction call will return gracefully without raising an Error.

init(configObject)

The init() function starts the LogUI client. You must pass a configuration object to the init() function as the one and only parameter. If this configuraiton object is badly formed, or some other component fails on startup, an Error will be raised.

You cannot call init() after the LogUI client has already started. In this instance, an Error will be raised.

isActive()

The isActive() function returns a boolean value indicating whether the LogUI client at that point in time was running or not (i.e, actively tracking elements and events on the DOM). true denotes that the LogUI is running, false denotes otherwise.

logCustomMessage(objectToLog)

LogUI works primarily by intervening when a native brower Event is fired (on a specific element, or through a browser event, such as a browser viewport resize). What if you want to log an interaction that takes place when an event is not fired?

You can use the logCustomMessage() function. Call this with a JavaScript object as the sole parameter to record a customEvent. For example, consider the following code.

function openModalDialog() {
    if (window.LogUI && window.LogUI.isActive()) {
        window.LogUI.logCustomMessage({
            name: 'MODAL_DIALOG_SHOW',
        });
    }

    showDialog();
}

In the example above, a custom LogUI event is saved when the openModelDialog() function is called by your application. The code above checks that LogUI is present and active, and then called the logCustomMessage() function.

The parameter you pass to the logCustomMessage() function contains all of the information you wish to save with the event. The example above will produce a LogUI customEvent, as shown below.

{
    "eventType": "customEvent",
    "eventDetails": {
        "name": "MODAL_DIALOG_SHOW"
    },
    "sessionID": "e72deba6-bf54-4311-884a-305273c734d1",
    "timestamps": {
        "eventTimestamp": "2021-04-24T20:19:18.915Z",
        "sinceSessionStartMillis": 3401,
        "sinceLogUILoadMillis": 3401
    },
    "applicationSpecificData": {
        "userId": "123"
    },
    "applicationID": "e386d221-1b45-481d-bd3a-ef9d2679e60b",
    "flightID": "4246f547-e229-4f58-a5b1-d8ad7c3e0e42"
}

Note that the contents of the parameter you pass to the logCustomMessage() event are saved to the resultant object's eventDetails. Note also that all other data, such as applicationSpecificData, are recorded as standard. Beware that the eventType is of customEvent!

Calling logCustomMessage() when the LogUI client is not running will raise an Error. Check the status of isActive() before calling this function.

We highly recommend providing a name to events logged using this approach. Doing so will provide you with a means for post processing of the captured interaction logs.

stop()

The stop() function stops the LogUI client library. This unbinds all listeners from elements that the LogUI client attached during its init() routine, and returns the DOM back to the state it was at when it found it. It closes the WebSocket connection to the server, if a connection is present. All logged interactions that were not sent to the server at the point of stop() being called will be flushed and sent down the WebSocket connection (if it is still available) before the stop() function completes.

If you call stop() when the LogUI client is not running, an Error will be raised.

updateApplicationSpecificData(updatedObject)

This function manipulates the application specific data object that is appended to each event captured and logged by the LogUI client. You may find that during the course of an experiment or the lifespan of a page, you will want to alter the application specific data. Working in conjunction with the deleteApplicationSpecificDataKey() function, this function alters application specific data by adding or updating a key.

By providing an updated application specific data object (updatedObject) as the parameter for this function, you can update existing values, or add new ones.

Consider the following example. Assume you have initialised the LogUI client with the following application specific data.

applicationSpecificData: {
    userID: 123,
    condition: 4,
    rotation: 2,
    consentProvided: false,
}

You then run the updateApplicationSpecificData() function with the following object passed as updatedObject.

LogUI.updateApplicationSpecificData({
    consentProvided: true,
    hasUpdated: true,
});

After this call has been completed, the applicatin specific data object will then consist of the following key/values.

{
    userID: 123,
    condition: 4,
    rotation: 2,
    consentProvided: true,
    hasUpdated: true,
}

Note that the value for consentProvided has switched from false to true; hasUpdated has been added, with a value of true.

If a key provided in updatedObject already exists in the application specific data, the value in updatedObject will replace the existing value. If a key provided in updatedObject does not exist in the application specific data, it is simply added to the object.

Once updated, all interactions captured and logged by the LogUI client will then be saved with the updated application specific data object that is generated as a result of this function being called.

Considerations when Integrating the LogUI Client

Integrating the LogUI client may take a little effort to get right; we've tried to simplify things as much as possible, although we do admit that this is a very complex problem to solve. Future iterations of the LogUI client will hopefully reduce the complexity of integrating the client with your application further.

As a rough guide, you should do the following when attempting to start the LogUI client.

1. Create the configuration object.
2. Check the LogUI client is loaded.
3. Start/initialise the LogUI client.

// Step 1
let configurationObject = {
    // ...
    // Settings go here.
    // ...
}

document.addEventListener('DOMContentLoaded', function() {
    // Step 2
    if (window.LogUI) {
        // Step 3
        LogUI.init(configurationObject);
    }
    else {
        // LogUI is not available!
    }
});

While the LogUI client is started/initialised in the example above when the page loads (i.e., when the DOMContentLoaded event is fired), you can in theory start the client whenever you like. For example, when your JavaScript application has loaded a specific component/view, you can then call the LogUI.init() function to start LogUI at that point. You should ensure however that LogUI.init() is only called when the DOM has been loaded!

If you do not provide a path for the LogUI client to be LogUI.stop()-ed during the lifecycle of your page, the client will continue to track interactions when the page is unloaded, or, in other words, when the user navigates away from it. This could be through clicking a link, or simply closing the browser. The LogUI.stop() function should automatically be called at this point, ensuring that the LogUI client is able to send off an event to the server indicating when the page was unloaded.

You can of course also programmatically stop the LogUI client by calling the LogUI.stop() function at any time during the lifecycle of your page. So too can you call the other API functions during the lifecycle of the page. Refer to the documentation above for more information on what you can call, and when.