Hooks/callbacks

Search…
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:
m - Heatmap movements
Data value is a Positions string​
c - Heatmap clicks
Data value is a Positions string​
p - Partial recording data
Data value is a Recording string​
r - Full recording data (sent when pageview has finished)
Data value is a Recording string​
i - clientPageID
Data value is a number
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"
​
​
JavaScript API - Previous
Events
Next - JavaScript API
Other API functions
Last modified 1yr ago
Copy link
Outline
What are userTrack callbacks?
Available callbacks
Usage example
Notes