> ## Documentation Index
> Fetch the complete documentation index at: https://revolai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Events

> Define custom tracking events — clicks, forms, scroll triggers, visibility — and set conversion goals

## Overview

The Events tab lets you define tracking events to capture specific visitor actions on your website. Track button clicks, form submissions, scroll milestones, element visibility, or fire custom events from your own code. Any event can be marked as a **conversion goal** to measure campaign effectiveness.

<Frame>
  <img className="block dark:hidden" src="https://mintcdn.com/revolai/iNw1SuV7xncLWRFk/images/tracker-events-light.png?fit=max&auto=format&n=iNw1SuV7xncLWRFk&q=85&s=a2ff0a5cbcd29ff22b3471bcca775edd" alt="Events tab" width="2874" height="1558" data-path="images/tracker-events-light.png" />

  <img className="hidden dark:block" src="https://mintcdn.com/revolai/iNw1SuV7xncLWRFk/images/tracker-events-dark.png?fit=max&auto=format&n=iNw1SuV7xncLWRFk&q=85&s=fdf74d88094e9f6afd40cb31abdf720a" alt="Events tab" width="2873" height="1553" data-path="images/tracker-events-dark.png" />
</Frame>

## Events List

The events table shows all defined events with key metrics:

| Column         | Description                                                 |
| -------------- | ----------------------------------------------------------- |
| **Name**       | Event name                                                  |
| **Type**       | Event type (Click, Scroll, Form Submit, Visibility, Custom) |
| **Fires**      | Total number of times this event has been triggered         |
| **Conversion** | Whether this event counts as a conversion goal              |
| **Status**     | Active or inactive                                          |
| **Actions**    | Edit or delete the event                                    |

### Filters

Filter the events list by:

| Filter         | Description                         |
| -------------- | ----------------------------------- |
| **Type**       | Show only events of a specific type |
| **Conversion** | Show only conversion goal events    |
| **Status**     | Show active or inactive events      |
| **Search**     | Search events by name               |

***

## Creating an Event

Click **Create Event** to define a new tracking event. Each event requires:

| Field               | Required | Description                                                                      |
| ------------------- | -------- | -------------------------------------------------------------------------------- |
| **Name**            | Yes      | Event name for identification (e.g., "CTA Button Click", "Contact Form Submit")  |
| **Type**            | Yes      | How the event is triggered (see Event Types below)                               |
| **CSS Selector**    | Depends  | CSS selector targeting the element (required for Click, Form Submit, Visibility) |
| **Page URL**        | No       | Restrict the event to fire only on a specific page                               |
| **Conversion Goal** | No       | Toggle to count this event as a conversion in analytics                          |

***

## Event Types

Each event type tracks a different kind of visitor interaction. The tracker script handles all automatic types — no coding required.

### Click

Fires when a visitor **clicks** on an element matching the CSS selector.

| Setting          | Description                                                                     |
| ---------------- | ------------------------------------------------------------------------------- |
| **CSS Selector** | Target element selector (e.g., `#cta-button`, `.buy-now`, `a[href="/contact"]`) |
| **Page URL**     | Optional — limit tracking to a specific page                                    |

**What is captured:**

* Element text content (first 100 characters)
* Element tag name (`button`, `a`, `div`, etc.)
* CSS selector that matched
* Current page URL

<Tip>
  Use browser DevTools to find the right CSS selector. Right-click the element → **Inspect** → right-click the HTML tag → **Copy** → **Copy selector**.
</Tip>

**Examples of CSS selectors:**

```css theme={null}
/* Button by ID */
#buy-now-btn

/* All buttons with a specific class */
.add-to-cart

/* Link to a specific page */
a[href="/pricing"]

/* Button inside a specific section */
.hero-section .cta-button

/* Any element with a data attribute */
[data-action="subscribe"]
```

### Scroll (Visibility)

Fires when the visitor **scrolls** past a specific element on the page. Uses an IntersectionObserver to detect when the element enters the viewport.

| Setting              | Description                                                           |
| -------------------- | --------------------------------------------------------------------- |
| **CSS Selector**     | Target element to observe (e.g., `#pricing-section`, `.testimonials`) |
| **Scroll Threshold** | Percentage of the element that must be visible (default: 50%)         |

**Use cases:**

* Track how many visitors see your pricing section
* Measure engagement with specific content blocks
* Detect if visitors reach the bottom of a long page

<Note>
  Each scroll event fires **only once** per session per element — even if the visitor scrolls past it multiple times. This prevents inflated counts.
</Note>

### Form Submit

Fires when a visitor **submits a form** matching the CSS selector.

| Setting          | Description                                                                 |
| ---------------- | --------------------------------------------------------------------------- |
| **CSS Selector** | Target form element (e.g., `#contact-form`, `.signup-form`)                 |
| **Form Fields**  | Optional — allowlist of field names to capture (e.g., `email, phone, name`) |

**What is captured:**

* Values from `<input>`, `<select>`, and `<textarea>` fields
* Field names and their values (up to 500 characters per field)
* Password and hidden fields are **automatically excluded**

<Warning>
  By default, all visible form fields are captured. Use the **Form Fields** allowlist to limit data collection to specific fields and avoid capturing sensitive information.
</Warning>

### Element Visibility

Fires when a specific element **becomes visible** in the browser viewport. Similar to Scroll, but focused on tracking whether a particular UI element was seen.

| Setting          | Description                                              |
| ---------------- | -------------------------------------------------------- |
| **CSS Selector** | Target element (e.g., `.promo-banner`, `#special-offer`) |

**Use cases:**

* Track impressions of promotional banners
* Measure visibility of important CTAs
* Detect if dynamically loaded content is seen (works with SPAs)

<Note>
  The tracker uses a MutationObserver to watch for dynamically added elements. If the target element is rendered by JavaScript after page load (React, Vue, etc.), it will still be detected.
</Note>

### Custom (Manual)

Fires when you call the **JavaScript API** from your own code. This is the most flexible event type — you control exactly when and with what data the event fires.

| Setting  | Description                                                     |
| -------- | --------------------------------------------------------------- |
| **Name** | Event name that matches the name used in `RevolTracker.track()` |

Custom events are covered in detail in the [Custom Events API](#custom-events-api) section below.

***

## Conversion Goal

Any event can be marked as a **Conversion Goal** by enabling the toggle. When enabled:

* The event is counted in the **Conversions** KPI card on the Dashboard
* It's used to calculate **Conversion Rate** in the Campaign Performance table
* Sessions containing this event are highlighted in the session detail view
* The event appears in conversion funnels and reports

### What Makes a Good Conversion Goal?

<AccordionGroup>
  <Accordion title="Lead generation">
    Mark **form submissions** as conversions — contact forms, quote requests, newsletter signups. These are clear indicators that a visitor became a lead.
  </Accordion>

  <Accordion title="E-commerce">
    Mark **add to cart** or **purchase completed** custom events as conversions. Track the full funnel from page view to purchase.
  </Accordion>

  <Accordion title="Engagement">
    Mark **scroll past pricing** or **video play** events as micro-conversions. These indicate strong interest even without a form submission.
  </Accordion>

  <Accordion title="Calls and chats">
    Mark **phone number click** or **chat widget opened** events as conversions. These show intent to engage directly.
  </Accordion>
</AccordionGroup>

<Tip>
  You can have multiple conversion goals active at the same time. The Dashboard Conversions KPI counts unique sessions with **at least one** conversion event — so a session that triggers 3 conversion events still counts as 1 conversion.
</Tip>

***

## Custom Events API

Custom events give you full control over event tracking from your own JavaScript code. Use them when automatic tracking (clicks, forms, visibility) isn't enough — for dynamic interactions, multi-step processes, or business-specific actions.

### Basic Usage

```javascript theme={null}
// Simple event — no additional data
RevolTracker.track('button_clicked');

// Event with custom data
RevolTracker.track('item_added_to_cart', {
    item_id: 'SKU-12345',
    item_name: 'Running Shoes',
    price: 89.99,
    currency: 'USD'
});
```

### API Reference

```javascript theme={null}
RevolTracker.track(eventName, data)
```

| Parameter   | Type     | Required | Description                                                                                             |
| ----------- | -------- | -------- | ------------------------------------------------------------------------------------------------------- |
| `eventName` | `string` | Yes      | Event name — must match the name defined in the Events tab if you want it linked to an event definition |
| `data`      | `object` | No       | Custom payload — any JSON-serializable data (objects, arrays, strings, numbers)                         |

**Automatically captured** (you don't need to pass these):

* Current page URL
* Session ID
* Timestamp
* Company ID

### E-Commerce Examples

Track the full shopping funnel:

```javascript theme={null}
// Product viewed
RevolTracker.track('product_viewed', {
    product_id: 'SKU-12345',
    product_name: 'Running Shoes Pro',
    category: 'Footwear',
    price: 89.99
});

// Added to cart
RevolTracker.track('add_to_cart', {
    product_id: 'SKU-12345',
    quantity: 1,
    price: 89.99
});

// Checkout started
RevolTracker.track('checkout_started', {
    cart_total: 89.99,
    items_count: 1
});

// Purchase completed
RevolTracker.track('purchase_completed', {
    order_id: 'ORD-9876',
    total: 89.99,
    currency: 'USD',
    items: [
        { id: 'SKU-12345', name: 'Running Shoes Pro', qty: 1, price: 89.99 }
    ]
});
```

### Add to Cart Integration

A complete example of integrating custom events with an "Add to Cart" button:

```html theme={null}
<button class="add-to-cart-btn"
        data-product-id="SKU-12345"
        data-product-name="Running Shoes Pro"
        data-price="89.99">
    Add to Cart
</button>

<script>
document.querySelectorAll('.add-to-cart-btn').forEach(function(btn) {
    btn.addEventListener('click', function() {
        // Your existing cart logic
        addItemToCart(this.dataset.productId);

        // Track the event in Revol
        RevolTracker.track('add_to_cart', {
            product_id: this.dataset.productId,
            product_name: this.dataset.productName,
            price: parseFloat(this.dataset.price)
        });
    });
});
</script>
```

### Lead Form Example

Track form submissions with field data:

```html theme={null}
<form id="contact-form">
    <input name="name" type="text" placeholder="Your name">
    <input name="email" type="email" placeholder="Email">
    <input name="phone" type="tel" placeholder="Phone">
    <textarea name="message" placeholder="Message"></textarea>
    <button type="submit">Send</button>
</form>

<script>
document.getElementById('contact-form').addEventListener('submit', function(e) {
    var formData = new FormData(this);

    RevolTracker.track('contact_form_submitted', {
        name: formData.get('name'),
        email: formData.get('email'),
        has_phone: !!formData.get('phone'),
        message_length: (formData.get('message') || '').length
    });
});
</script>
```

### SPA / React Example

For single-page applications, fire events on route changes or component interactions:

```javascript theme={null}
// React — track page view on route change
useEffect(() => {
    RevolTracker.track('page_view', {
        page: location.pathname,
        title: document.title
    });
}, [location.pathname]);

// React — track button click
function handlePricingClick(plan) {
    RevolTracker.track('pricing_plan_selected', {
        plan: plan,
        page: '/pricing'
    });
}
```

### How Events Are Sent

Events are **buffered and batched** for performance:

1. Each `RevolTracker.track()` call adds the event to an internal buffer
2. Every **5 seconds**, all buffered events are sent to the server in a single request
3. On **page unload**, any remaining events are sent via `sendBeacon()` for reliability
4. Maximum **50 events** per batch — excess events are dropped

<Note>
  You don't need to create an event definition in the dashboard for custom events to be recorded. Undefined custom events are still stored with their data — but they won't have a fire count in the Events list. For full tracking, create a matching event definition with the same name.
</Note>

***

## Analyze Your Website with Claude Code

If you're not sure which elements to track, you can use **Claude Code** to analyze your website and suggest an optimal event tracking setup.

<Accordion title="Prompt for website analysis">
  ```text theme={null}
  # Instruction: Generate CSS Classes for Website Event Tracking

  ## Context

  I use the Revol tracking system, which tracks user actions on
  websites via CSS selectors. The tracker is embedded with a single
  script and automatically listens for events on elements matching
  the specified CSS selectors. No additional JS code is needed on
  the website (except for AJAX forms, see below).

  ## How Event Tracking Works

  The system supports 5 event types:

  - click — element click. Uses
    document.addEventListener('click') + e.target.closest(css_selector),
    delegated on document in capture phase.
  - form_submit — form submission. Uses
    document.addEventListener('submit') + checks css_selector
    on the <form> tag.
  - scroll — scroll to element. IntersectionObserver with threshold
    (0-100%), fires once per session.
  - visibility — element appeared in viewport. IntersectionObserver,
    one-time.
  - custom — manual JS call: RevolTracker.track('Name', {data})

  ## Your Task

  ### Step 1: Analyze All Website Pages

  Go through all HTML/template files and find:

  1. Buttons (buttons/links) — CTAs, navigation, actions
  2. Phone numbers — <a href="tel:...">, text blocks with numbers
  3. Email links — <a href="mailto:...">
  4. Messengers — Telegram, Viber, WhatsApp links
  5. Forms — contact, applications, subscriptions, orders
  6. Clickable blocks — cards, banners, sections with links
  7. Conversion elements — cart, checkout, registration

  ### Step 2: Add CSS Classes for Tracking

  For each found element, add a CSS class with the rv- prefix:

  Naming convention: rv-{type}-{section}-{action}
  Types: btn, link, form, block, scroll

  Examples:
  - rv-btn-hero-cta — CTA button in hero section
  - rv-btn-header-phone — phone click in header
  - rv-btn-footer-phone — phone click in footer
  - rv-btn-pricing-order — order button on pricing page
  - rv-btn-header-telegram — Telegram click in header
  - rv-form-contact — contact form
  - rv-form-callback — callback request form
  - rv-block-services-card — service card click
  - rv-link-nav-about — "About" navigation link
  - rv-scroll-testimonials — scroll to testimonials

  Rules:
  - rv-* class is added IN ADDITION to existing classes
  - One element = one rv- class
  - Class should be unique per page (or intentionally shared
    for similar elements, e.g. all service cards)

  ### Step 3: Form Rules

  The rv-form-* class goes on the <form> tag, NOT on the submit button:

    Correct:
    <form class="contact-form rv-form-contact" action="/submit">
      <input name="phone" type="tel">
      <button type="submit">Submit</button>
    </form>

    Incorrect:
    <form class="contact-form">
      <button class="rv-form-contact" type="submit">Submit</button>
    </form>

  AJAX forms (without native submit):

  If a form is submitted via JS (fetch, axios, $.ajax) without
  a native submit event, the tracker will NOT catch it. Signs:
  - e.preventDefault() + fetch/axios/$.ajax in handler
  - Form without action or with action="javascript:void(0)"
  - Button has type="button" instead of type="submit"

  For such forms, add a manual call alongside the AJAX submission:
    RevolTracker.track('Contact Form', { form: 'contact' });

  In the events table, mark such forms as type custom instead
  of form_submit and note that a manual call is needed.

  ### Step 4: Create the Events Table

  Event names should be in English. Table format:

  # | Event Name | CSS Selector | Type | Conversion? | Page | Description

  Example:
  1 | Hero CTA Click | .rv-btn-hero-cta | click | Yes | Home | Main CTA button in hero banner
  2 | Header Phone Click | .rv-btn-header-phone | click | Yes | All | Phone number click in header
  3 | Footer Phone Click | .rv-btn-footer-phone | click | Yes | All | Phone number click in footer
  4 | Telegram Click | .rv-btn-header-telegram | click | Yes | All | Telegram link click
  5 | Contact Form | .rv-form-contact | form_submit | Yes | Contact | Contact form submission
  6 | Callback Form | .rv-form-callback | form_submit | Yes | Home | "Call me back" form
  7 | Service Card Click | .rv-block-services-card | click | No | Services | Service card click
  8 | Nav — About | .rv-link-nav-about | click | No | All | Navigate to About page
  9 | Scroll to Testimonials | .rv-scroll-testimonials | scroll (80%) | No | Home | Scrolled to testimonials
  10 | Application Form (AJAX) | — | custom | Yes | Services | AJAX form, needs RevolTracker.track()

  ### What Counts as a Conversion

  Yes — conversion:
  - Phone click (<a href="tel:...">)
  - Email click (<a href="mailto:...">)
  - Messenger clicks (Telegram, Viber, WhatsApp)
  - Any form submission (application, order, contact)
  - CTA button clicks ("Order", "Buy", "Book", "Get a Quote")

  No — not a conversion:
  - Navigation links
  - Info block/card clicks (unless CTA)
  - Scroll/visibility events
  - Social media clicks (unless CTA)

  ## Response Format

  1. File changes — which rv-* classes to add, with diff
  2. Events table — full list of events with all columns
  3. AJAX forms — separately list forms requiring a manual
     RevolTracker.track() call, with ready-to-use code

  My website is: [PASTE URL]
  Business type: [e.g., e-commerce, SaaS, services, agency]
  Main conversion action: [e.g., form submission, purchase, booking]
  ```
</Accordion>