# Custom Events

Cuoral’s churn Intelligence System provides powerful **analytics** and **session replay** to help you understand how users interact with your website and exact point you need to engage them.

In addition to automatically tracking common interactions, you can send **custom events** to monitor important business actions and product usage.

Custom events allow you to capture **meaningful user behavior that automatic tracking cannot detect**.

***

## Automatic Tracking

Cuoral Intelligence automatically tracks the following events:

| Event Type            | Description                                              |
| --------------------- | -------------------------------------------------------- |
| **Page Views**        | Every page visit and navigation                          |
| **Clicks**            | Interactions with buttons, links, and clickable elements |
| **Scroll Depth**      | How far users scroll on each page                        |
| **Form Interactions** | Form submissions, field completion, and form abandonment |
| **API Calls**         | Network requests and responses                           |
| **Console Errors**    | JavaScript errors and unhandled exceptions               |
| **Session Replay**    | Video-like playback of complete user sessions            |

***

## Why Use Custom Events?

Custom events help you track **specific user behaviors that matter to your business**.

Common use cases include:

* Important button actions (e.g., **Add to Cart**, **Start Checkout**)
* Feature usage (e.g., **Opened Filter Menu**, **Applied Coupon Code**)
* User preferences (e.g., **Changed Language**, **Enabled Dark Mode**)
* Onboarding progress (e.g., **Completed Onboarding Step 3**)
* Product milestones (e.g., **Reached Quiz Question 5**)

***

## Prerequisites

Before sending custom events, make sure:

1. **Cuoral Intelligence is enabled** for your organization
2. **The Cuoral widget is installed** on your website
3. You have access to modify your website’s **JavaScript code**

To verify Intelligence is enabled, check:

```
Dashboard → Intelligence & Analytics
```

or contact your Cuoral administrator.

***

## Quick Start

### 1. Verify Cuoral is Loaded

Ensure the Cuoral widget is present on your website.\
You should see the **Cuoral chat icon** on the page.

***

### 2. Track Your First Custom Event

```javascript
window.Cuoral.trackCustomEvent(
  'button_clicked',   // Event name
  'user_action',      // Event category
  { page: 'home' }    // Optional properties
);
```

***

### 3. View the Event

Navigate to:

```
Dashboard → Intelligence & Analytics → Custom Events
```

Your event should appear shortly after it is sent.

***

## API Reference

### `trackCustomEvent`

```js
window.Cuoral.trackCustomEvent(
  name,
  category,
  properties,
  elementSelector,
  elementText
)
```

#### Parameters

| Parameter         | Type   | Required | Description                                             |
| ----------------- | ------ | -------- | ------------------------------------------------------- |
| `name`            | string | Yes      | Name of the event (e.g., `add_to_cart`, `video_played`) |
| `category`        | string | Yes      | Event category (e.g., `ecommerce`, `navigation`)        |
| `properties`      | object | No       | Additional data to attach to the event                  |
| `elementSelector` | string | No       | CSS selector of the triggering element                  |
| `elementText`     | string | No       | Text content of the triggering element                  |

Defaults:

```
properties = {}
elementSelector = null
elementText = null
```

***

## Automatic Event Properties

Every custom event automatically includes the following metadata:

| Property          | Description                       |
| ----------------- | --------------------------------- |
| `session_id`      | Current session identifier        |
| `url`             | Page URL where the event occurred |
| `event_timestamp` | ISO timestamp of the event        |
| `viewport_width`  | Browser viewport width            |
| `viewport_height` | Browser viewport height           |
| `screen_width`    | Device screen width               |
| `screen_height`   | Device screen height              |
| `user_agent`      | Browser user agent                |
| `referrer`        | Page referrer                     |
| `language`        | Browser language                  |

***

## Implementation Examples

### Track a Button Click

```js
document.getElementById('signup-button').addEventListener('click', () => {
  window.Cuoral.trackCustomEvent(
    'signup_clicked',
    'conversion',
    { source: 'homepage_hero' }
  );
});
```

***

### Track Form Submission

```js
document.getElementById('contact-form').addEventListener('submit', function(e) {
  e.preventDefault();

  window.Cuoral.trackCustomEvent(
    'contact_form_submitted',
    'conversion',
    {
      form_type: 'contact',
      has_phone: !!this.phone.value,
      message_length: this.message.value.length
    }
  );
});
```

***

### Track Feature Usage

```javascript
function toggleDarkMode() {
  const isDark = document.body.classList.toggle('dark-mode');

  window.Cuoral.trackCustomEvent(
    'dark_mode_toggled',
    'preferences',
    { enabled: isDark }
  );
}
```

***

## Recommended Event Categories

To keep analytics organized, use standardized categories:

| Category          | Use Case                             |
| ----------------- | ------------------------------------ |
| **ecommerce**     | Shopping, cart actions, checkout     |
| **media**         | Video or audio playback              |
| **navigation**    | Menu clicks, page transitions        |
| **engagement**    | Searches, filters, interactions      |
| **conversion**    | Signups, form submissions, downloads |
| **user\_action**  | Generic user interactions            |
| **error**         | Custom error tracking                |
| **preferences**   | Settings and user preferences        |
| **user\_journey** | Onboarding flows and tutorials       |

***

## Viewing Your Events

After implementation, events can be analyzed in the Cuoral dashboard.

#### 1. Open Analytics

```
Dashboard → Intelligence & Analytics
```

#### 2. Filter Events

Select **Custom Events** from the event type filter.

#### 3. Analyze Behavior

You can:

* Group events by **category**
* Build **conversion funnels**
* View events in **session replay**
* Track feature usage trends

***

## Testing Custom Events

To confirm events are being tracked correctly:

```js
window.Cuoral.trackCustomEvent('test_event', 'testing', {
  test_time: new Date().toISOString()
});

// Optional: force immediate send
window.Cuoral.flush();
```

Then open **Developer Tools → Network** and look for requests to:

```
customer-intelligence/session-recording/batch
```