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

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

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

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

---

Track Form Submission

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

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:

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