# Hooks/callbacks

## 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 [Positions string](#positions-string-compressed-format)
    * **c** - Heatmap clicks
      * Data value is a [Positions string](#positions-string-compressed-format)
    * **p** - Partial recording data
      * Data value is a [Recording string](#recording-string-compressed-format)
    * **r** - Full recording data (sent when pageview has finished)
      * Data value is a [Recording string](#recording-string-compressed-format)
    * 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**

{% hint style="warning" %}
Make sure write the callbacks declarations **after the tracking file** is included.
{% endhint %}

#### Example: Multiple UXWizz callbacks

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

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

```javascript
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...!');
} 
```

{% hint style="info" %}
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.
{% endhint %}

### Notes

#### Positions string (compressed format):

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

#### Recording string (compressed format)

```javascript
// 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"
```
