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


---

# 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.cuoral.com/integration/custom-events.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.