Metadata Sourcers

Extracting Metadata from Components

In the LogUI client, a metadata sourcer is a component that is able to extract additional data from some source (listed in Available Metadata Sourcers below), and attaches it to a given event that is about to be logged.

This provides a high degree of flexibility when using LogUI, as you can attach additional data relating to the element in question (such as from an element attribute), and store that data as part of the logged interaction. Essentially, given a metadata sourcer configuration, LogUI will resolve this down to a single value which is stored as part of the captured event in question.

Example Usage

You can apply multiple metadata sourcers to an individual trackingConfiguration mapping, part of the configuration object. Consider the following example below.

...
trackingConfiguration: {
    selector: '#results li',
    event: 'click',
    metadata: [
        {
            nameForLog: 'resultRank',
            sourcer: 'elementAttribute',
            lookFor: 'data-rank',
        },
        {
            nameForLog: 'documentTitle',
            sourcer: 'elementProperty',
            lookFor: 'textContent',
        },
    ],
},
...

This example provides two metadata sourcers for the #results li CSS selector (on a li child of the #results element), when a click occurs.

Each metadata sourcer configuration contains three settings, each of which are listed below. All three of these settings are required; if one or more are missing or lead to no data, then the metadata sourcer configuration in question is ignored.

• nameForLog The nameForLog property specifies the name that should be used when logging this particular metadata sourcer configuration. In essence, this is the key that represents the resolved value from the sourcer.

• sourcer The sourcer is the type of metadata sourcer that you wish to extract data from. Available types are listed below; in the example above, we use the elementAttribute and elementProperty sourcers. These extract an individual attribute from the element in question (elementAttribute), and an individual property from the element in question (elementProperty).

• lookFor Finally, lookFor specifies a string which represents the field/attribute/property that is required. LogUI looks for this field/attribute/property in the element provided, and if it finds it, it returns the value.

Together, these three settings resolve to an object (i.e., string, boolean, number, object) which is recorded as part of the logged interaction in question.

Available Metadata Sourcers

We provide six metadata sourcers for you to use to capture additional data for your logged interaction events. More will be added in the future, with flexibility improved.

elementAttribute

This metadata sourcer extracts values from HTML attributes for the element in question. For example, the following metadata sourcer configuration:

{
    nameForLog: 'searchLanguage',
    sourcer: 'elementAttribute',
    lookFor: 'data-language',
},

and the following selected HTML element:

<input type="text" id="searchBox" data-language="english" />

will result in the following key and value being appended to the interaction on the above element.

{
    searchLanguage: 'english',
}

If the requested attribute is not found on the element in question, no data is appended, nor do any Errors occur. This fails silently.

elementProperty

Like the attributeProperty metadata sourcer, the elementProperty sourcer obtains data from the element in question, but instead of looking for specific HTML attributes associated with it, it looks at properties associated with the element. For example, on an input field, the value property will yield a string that represents the contents of the field.

To demonstrate this, consider the following metadata sourcer configuration.

{
    nameForLog: 'fieldValue',
    sourcer: 'elementProperty',
    lookFor: 'value',
},

Applied on an HTML input field, like so:

<input type="text" id="searchBox" />  <!-- Where the user has typed in "hello" -->

this will result in the following being appended to the event being logged.

{
    fieldValue: 'hello',
}

You can also instruct the elementProperty metadata sourcer to pull properties from a different element if required. An example where this may be useful is when a small form is being submitted — you could use this feature to pull the value of an <input> field when a button is clicked by the user, and log that. To use this functionality, use the additional onElement property.

{
    nameForLog: 'value_of_field',
    sourcer: 'elementProperty',
    lookFor: 'value',
    onElement: '#inputField',
},

This configuration dictates that when the corresponding event is triggered, metadata should be extracted (and logged under the name value_of_field) from the value property of the element returned from selector #inputField. In other words, the call document.querySelector('#inputField').value will return the same value as what LogUI will log in this instance.

As can be seen from above, onElement should be passed a valid CSS selector string to identify the element you wish to extract a property's value from.

The CSS selector you use should return a single element. If you were to use a CSS selector that returns more than one element (i.e., a class selector), the element that is chosen to extract the desired property from is undefined. Use a selector that returns a single element to ensure reproducibile behaviour.

If the onElement property is not specified, LogUI will assume that the desired property to be stored exists within the element that the user has interacted with.

If onElement specifies an element that does not exist in the DOM, or the lookFor property does not exist as part of the element in question, the metadata sourcer will not record anything.

localStorage

The localStorage metadata sourcer pulls out a value from the browser's LocalStorage object. In this instance, if we set a value in LocalStorage with the following command:

window.LocalStorage.setItem('someValue', 12345);

and then added a metadata sourcer to a given eventTracking configuration mapping:

{
    nameForLog: 'someNumber',
    sourcer: 'localStorage',
    lookFor: 'someValue',
},

the resulting output appended to the logged interaction would be:

{
    someNumber: 12345,
}

sessionStorage

With the sessionStorage metadata sourcer, the same occurs as the localStorage metadata sourcer, only this time extracting data from the SessionStorage browser object.

reactComponentProp

The LogUI client also provides the ability to extract data from React components, the building blocks of any React application. As each component has props and a state, we can, given an HTML element, determine if it belongs to a React component, and extract data from it.

The reactComponentProp therefore examins the props of a given HTML element's React component, and draws out a value from it, appending it to the captured event.

reactComponentState

The same is true for the reactComponentState metadata sourcer. However, this time, this metadata sourcer examines the state object of a component, rather than the props.