# 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"
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.uxwizz.com/api/hooks-callbacks.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
