UXWizz
WebsitePricingDemoTwitter (X)
  • Introduction
  • 🛠️ Installation
    • Requirements
      • Limitations
      • Server specs (CPU, RAM)
    • Installation guide
      • Uploading the script
      • Creating a MySQL database
      • Running the installer
    • Install on a new server
      • Ubuntu 20.04 (or higher)
      • DigitalOcean
    • Docker
      • Via Docker Compose
      • Standalone Docker image
    • Adding the tracking code
      • Automatic SPA pageview tracking
      • Add tracker to Next.js App
      • Add tracker to React Router App
    • Optimization tips
      • MySQL/MariaDB
      • Auto-delete old data (cron jobs)
      • Apache
    • Frequently Asked Questions
  • 🔧JavaScript API
    • Tags
    • Events
    • Hooks/callbacks
    • Other API functions
    • Session Recording
      • Ignore specific elements
  • 📖Guides and features
    • Goals (NEW!)
    • Ask AI (NEW!)
    • Basic usage
    • A/B testing
    • Usage tips
    • Dashboard user access level
    • Resetting the admin password
    • Database querying
    • Technical details
      • IP Geolocation
    • Troubleshooting
      • Agency
        • MultiDB
      • Dashboard
        • Refreshing dashboard sub-page leads to 404 error
        • Website iframe not loading (x-frame-options)
        • License says "invalid"
        • Updating Fails
      • Tracking
        • No data is being recorded
        • Can't include tracker via Google Tag Manager
        • The A/B test JS file is missing
      • WordPress
        • Cloudways 403 Forbidden screen on WordPress
        • NGINX 403 Forbidden screen on WordPress
    • Extending the dashboard
    • Support
    • Migrating to a new server
  • 🎓Useful Examples
    • Feedback form (polls)
    • Tracking 404 Pages
    • Tracking UTM parameters
    • Tracking Google Ads GCLID
    • Storing user device types
    • Track video playback
  • 📜About
    • Changelog
    • Personal Data Information
    • Privacy Policy (uxwizz.com)
    • Licenses and pricing
    • [Deprecated] License Subscriptions
Powered by GitBook
On this page
  • What are UXWizz callbacks?
  • Available callbacks
  • Usage example
  • Notes

Was this helpful?

  1. JavaScript API

Hooks/callbacks

PreviousEventsNextOther API functions

Last updated 8 months ago

Was this helpful?

What are UXWizz callbacks?

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

Available callbacks

  • UST.onLoaded()

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

  • UST.onTrackingStarted() : false | undefined

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

    • This is called before the session was created.

    • If you want to stop creating this session, return false from this function.

  • UST.onSessionCreated(clientID: number)

    • Called when the UXWizz 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

      • c - Heatmap clicks

        • Data value is a

      • p - Partial recording data

        • Data value is a

      • r - Full recording data (sent when pageview has finished)

        • Data value is a

      • x - Recording type

        • Data is an integer

      • w - We have a complete recording

        • Data is 1 (or not set)

      • s - Skip updating lastActivity

        • Useful for when we want to update data for a user, without automatically refreshing/increasing the user's session duration.

        • Data is 1 (or not set)

      • 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 UXWizz tracking consent pop-up.

  • UST.onGDPRDeclined()

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

Usage example

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

Example: Multiple UXWizz callbacks

// <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>

Example: Dynamically disable tracking the current visitor

// Example: Permanently disable tracking a visitor once they reached checkout
UST.onTrackingStarted = function() {
    if (window.location.path === '/checkout-complete') {
        // Starting with the next page-load disable tracking this user (permanently)
        UST.disableRecord();
        
        // Return `false` to stop tracking this first pageview too
        return false;
    }
}

Example: Track the current user but disable session recording

UST.onTrackingStarted = function() {
     // Disable session recording for specific IPs
     // Note: `ust_myIP` is globally populated ONLY if you have set 
     // some excluded IPs in the tracking settings
     if (['123.456.12.13', '127.0.0.1'].indexOf(ust_myIP) !== -1) {
         UST.settings.enableSessionRecordings =  false; // Disable sending rec data
         UST.fullRec = false; // Disable attaching the full recorder
         UST.nativeSessionRecording = false; // Disable attaching the native recorder
     }
     
     console.log('Creating pageview...!');
} 

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"

🔧
Positions string
Positions string
Recording string
Recording string