Tags

Tags are strings that can be associated with a specific visit/session. Unlike events, tags are unique per session (i.e. can not have duplicate tags), are simple strings of a length of maximum 128 characters. Tags can be used to quickly filter/segment data.

Example

// Call this when the scrollbar reaches the end
UST.addTag('scrolled_to_footer')

// Call this when user adds an item to the basket
UST.addTag('add_to_basket_timestamp: ' + Date.now())

Instructions

• Sometimes you might want to save additional data for each tracked user (such as username or whether they clicked a button or not).

• To add a tag the function UST.addTag() is provided. It has only one parameter which is the tag value. For example after calling this: UST.addTag("username_John")

  The tag will be saved for the current recording and you will be able to find it more easily.

• You can also enable auto-tagging when certain elements are clicked. Add the HTML5 attribute data-UST_click_tag to set what tag will be added if the current element is clicked.

  Example: <input type="text" data-UST_click_tag="clicked_input" />. When this input is clicked the tag clicked_input will be added for this session.

  You will then be able to, for example, see only the recordings of users who clicked that specific input.

Notes

1. Once written the value of tags can not be changed.

2. Each tag is unique and can appear only once. If you call UST.addTag() again with the same tag value, nothing will happen.

3. If you want more tags with similar name you can either add a random value or an unique id to each tag name.

Examples: Using tags

1. Video playback events (play, pause, end)

From version 3.5.0 it would be better to implement this kind of tag as an event.

HTML:

<video id="demo" width=720 height=300 controls>
    <source src="video.mp4" type="video/mp4">
    Video not supported by your browser.
</video>

JavaScript:

var v = document.querySelector('#hero-video');

// PAUSE
v.addEventListener('pause', function() {
    UST.addTag('video_paused');
    // You can also add another tag with the exact time at which the video was paused
    // NOTE: For more flexibility, tracking values should be done using Events
    UST.addTag('video_paused_at_' + Math.round(v.currentTime));
});

// PLAY
v.addEventListener('play', function() {
    UST.addTag('video_play');
});

// ENDED
v.addEventListener('ended', function() {
    UST.addTag('video_end');
});

Result:

Recorded users will then have tags similar to those:

2. Track if user scrolled on homepage

JavaScript:

// Add a tag for users who scroll at least once on the homepage
window.addEventListener('scroll', function didScroll() {
    UST.addTag('scrolled_on_home');
    window.removeEventListener('scroll', didScroll); // Sending it once is enough, remove listener
});

Result:

Recorded users will then have tags similar to this:

3. Record all clicked elements

By default, in order to reduce storage size, userTrack only stores click positions for both heatmaps and recordings. If you want to also store the clicked elements selectors you could add something like this after the tracker file:

<script>
UST.onLoaded = function () {
   addDynamicEventListener(document.body, 'click', '*', function (e) {
        if (!e.delegatedTarget) return;
        var tag = UST.DOM.getUniquePath(e.delegatedTarget);
        UST.addTag('click_' + tag);
    });
}
</script>

This will add a tag like click_element-path for every element clicked, for example click_#pricing-button(1).

The element-path is a CSS selector that has the nth-child: part remove to save space, you can get the original selector by using this function:

function uncompressSelector(selector) {
    return selector.replace(/\((\d+)\)/g, ' > *:nth-child($1)');
}

// Example
var cssSelector = uncompressSelector('#pricing-button(1)');
console.log(cssSelector );
// Outputs: #pricing-button > *:nth-child(1)