Hooks/callbacks

What are userTrack callbacks?

The userTrack callbacks or hooks are a way to tap into the client-side userTrack tracking functionality and listen to specific events. This is useful, for example, if you want to read or forward some userTrack tracking data to another service.

Available callbacks

  • UST.onLoaded

    • Called as soon as the ust.min.js finishes loading.

  • UST.onTrackingStarted

    • Called when all tracking checks passed, meaning that a new session will be created.

  • UST.onSessionCreated(clientID: number)

    • Called when the userTrack server create a new session for this client

    • clientID: The integer number ID of the session.

    • This is called only once per visit for each visitor.

  • UST.onPageViewCreated(clientID: number, clientPageID: number)

    • Called when a new page has loaded and the server responded with the pageview ID.

    • clientID: The integer ID of the session.

    • clientPageID: The integer ID of the pageview.

    • This callback is also called once immediately after onSessionCreated (first pageview).

  • UST.onDataSent(data: string[])

    • Called whenever tracking data (session recording/heatmap data) is sent to the server.

    • data: An array of data strings sent to the server. Each data string is in the format c=XXX where c is the data type and XXX is the data value. The data type can be:

  • UST.onTagAdded(tag: string)

    • Called when UST.addTag() was called and the server responded.

    • tag: The string that has just been added as a tag to the current user.

  • UST.onEventAdded(eventData: Event)

    • Added in version 3.5.0

    • Called when UST.addEvent() was called and the server responded.

    • eventData: The original eventData passed, also containing clientID and clientPageID

  • UST.onGDPRAccepted

    • Called when the user accepted the tracking consent pop-up.

  • UST.onGDPRDeclined

    • Called when the user declined the tracking consent pop-up.

Usage example

Make sure write the callbacks declarations after the tracking file is included.

// <head>
// After ust.min.js include snippet
// ...
// <script>
// Example: User will be recorded
UST.onTrackingStarted = function() {
console.log('Creating session...!');
}
// Example: New session has been created with an unique clientID
UST.onSessionCreated = function(clientID) {
console.log('New session created for client', clientID);
}
// Example: whenever a tag is added, add the same tag + current pageID
UST.onTagAdded = function(tag) {
if (tag === 'AddToCart' || tag === 'Converted') {
UST.addTag(tag + ';' + sessionStorage.clientPageID);
}
}
// <script>
// </head>

After the session has been created (onSessionCreated), you can always read the current userTrack clientID and clientPageID from sessionStorage:

sessionStorage.getItem('clientPageID')

sessionStorage.getItem('clientID')

sessionStorage.getItem('token') token - Another unique identifier per session (similar to clientID). This is useful as it's not incremental.

Notes

Positions string (compressed format):

"X1^Y1^count1~X2^Y2^count2"
// For example:
"303^490^1~441^570^1~439^642^1"

Recording string (compressed format)

// This is more complex, looking at the data send or in the ust_records
// Should give you some idea of the format
// Some event names and their shorthand character:
enum PlaybackEventType {
CLICK = 'c',
SCROLL = 's',
MOVEMENT = 'm',
INACTIVITY = 'i',
BLUR_INPUT = 'b',
TEXT_SELECTION = 'a',
WINDOW_RESIZE = 'r',
}
// For example
"a`body(2)(1)(5)(1)(2)(4)(2)(4)%201%23T%23^body(2)(1)(5)(1)(2)(4)(2)(4)%201%23T%23^8^9~i`80"
"m`966^1016~i`8~s`0^806~s`0^998~m`954^1415~s`0^1000~m`962^1416"