> ## 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 дозволяє визначати події для відстеження конкретних дій відвідувачів на вашому сайті. Відстежуйте кліки на кнопки, відправлення форм, прокрутку до ключових елементів, видимість елементів або відправляйте кастомні події зі свого коду. Будь-яку подію можна позначити як **конверсійну ціль** для вимірювання ефективності кампаній.

<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="Вкладка подій" 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="Вкладка подій" width="2873" height="1553" data-path="images/tracker-events-dark.png" />
</Frame>

## Список подій

Таблиця подій показує всі визначені події з ключовими метриками:

| Колонка        | Опис                                                       |
| -------------- | ---------------------------------------------------------- |
| **Name**       | Назва події                                                |
| **Type**       | Тип події (Click, Scroll, Form Submit, Visibility, Custom) |
| **Fires**      | Загальна кількість спрацювань                              |
| **Conversion** | Чи є подія конверсійною ціллю                              |
| **Status**     | Активна або неактивна                                      |
| **Actions**    | Редагувати або видалити подію                              |

### Фільтри

Фільтруйте список подій за:

| Фільтр         | Опис                                 |
| -------------- | ------------------------------------ |
| **Type**       | Показати лише події певного типу     |
| **Conversion** | Показати лише конверсійні події      |
| **Status**     | Показати активні або неактивні події |
| **Search**     | Пошук подій за назвою                |

***

## Створення події

Натисніть **Create Event**, щоб визначити нову подію. Кожна подія потребує:

| Поле                | Обов'язкове | Опис                                                                                 |
| ------------------- | ----------- | ------------------------------------------------------------------------------------ |
| **Name**            | Так         | Назва події для ідентифікації (наприклад, «CTA Button Click», «Contact Form Submit») |
| **Type**            | Так         | Як спрацьовує подія (див. Типи подій нижче)                                          |
| **CSS Selector**    | Залежить    | CSS-селектор цільового елемента (обов'язковий для Click, Form Submit, Visibility)    |
| **Page URL**        | Ні          | Обмежити спрацювання лише на конкретній сторінці                                     |
| **Conversion Goal** | Ні          | Увімкнути для підрахунку як конверсія в аналітиці                                    |

***

## Типи подій

Кожен тип події відстежує інший вид взаємодії відвідувача. Скрипт трекера обробляє всі автоматичні типи — кодування не потрібне.

### Click

Спрацьовує коли відвідувач **натискає** на елемент, що відповідає CSS-селектору.

| Налаштування     | Опис                                                                                     |
| ---------------- | ---------------------------------------------------------------------------------------- |
| **CSS Selector** | Селектор цільового елемента (наприклад, `#cta-button`, `.buy-now`, `a[href="/contact"]`) |
| **Page URL**     | Необов'язково — обмежити трекінг конкретною сторінкою                                    |

**Що фіксується:**

* Текстовий вміст елемента (перші 100 символів)
* Тег елемента (`button`, `a`, `div` тощо)
* CSS-селектор, який спрацював
* Поточний URL сторінки

<Tip>
  Використовуйте DevTools браузера, щоб знайти правильний CSS-селектор. Клацніть правою кнопкою на елемент → **Інспектувати** → клацніть правою кнопкою на HTML-тег → **Copy** → **Copy selector**.
</Tip>

**Приклади CSS-селекторів:**

```css theme={null}
/* Кнопка за ID */
#buy-now-btn

/* Всі кнопки з певним класом */
.add-to-cart

/* Посилання на конкретну сторінку */
a[href="/pricing"]

/* Кнопка всередині певної секції */
.hero-section .cta-button

/* Будь-який елемент з data-атрибутом */
[data-action="subscribe"]
```

### Scroll (Visibility)

Спрацьовує коли відвідувач **прокручує** до певного елемента на сторінці. Використовує IntersectionObserver для виявлення входу елемента у viewport.

| Налаштування         | Опис                                                                                |
| -------------------- | ----------------------------------------------------------------------------------- |
| **CSS Selector**     | Цільовий елемент для спостереження (наприклад, `#pricing-section`, `.testimonials`) |
| **Scroll Threshold** | Відсоток елемента, який повинен бути видимим (за замовчуванням: 50%)                |

**Сценарії використання:**

* Відстеження скільки відвідувачів бачать секцію з цінами
* Вимірювання залучення до конкретних блоків контенту
* Виявлення чи відвідувачі досягають низу довгої сторінки

<Note>
  Кожна подія прокрутки спрацьовує **лише один раз** за сесію на елемент — навіть якщо відвідувач прокручує повз нього кілька разів. Це запобігає завищеним підрахункам.
</Note>

### Form Submit

Спрацьовує коли відвідувач **відправляє форму**, що відповідає CSS-селектору.

| Налаштування     | Опис                                                                                |
| ---------------- | ----------------------------------------------------------------------------------- |
| **CSS Selector** | Цільовий елемент форми (наприклад, `#contact-form`, `.signup-form`)                 |
| **Form Fields**  | Необов'язково — список дозволених полів для збору (наприклад, `email, phone, name`) |

**Що фіксується:**

* Значення з `<input>`, `<select>` та `<textarea>` полів
* Назви полів та їх значення (до 500 символів на поле)
* Поля паролів та приховані поля **автоматично виключаються**

<Warning>
  За замовчуванням збираються всі видимі поля форми. Використовуйте список **Form Fields**, щоб обмежити збір даних конкретними полями та уникнути збору конфіденційної інформації.
</Warning>

### Element Visibility

Спрацьовує коли певний елемент **стає видимим** у viewport браузера. Подібно до Scroll, але фокусується на відстеженні чи був побачений конкретний UI-елемент.

| Налаштування     | Опис                                                            |
| ---------------- | --------------------------------------------------------------- |
| **CSS Selector** | Цільовий елемент (наприклад, `.promo-banner`, `#special-offer`) |

**Сценарії використання:**

* Відстеження показів рекламних банерів
* Вимірювання видимості важливих CTA
* Виявлення чи динамічно завантажений контент був побачений (працює з SPA)

<Note>
  Трекер використовує MutationObserver для спостереження за динамічно доданими елементами. Якщо цільовий елемент рендериться JavaScript після завантаження сторінки (React, Vue тощо), він все одно буде виявлений.
</Note>

### Custom (Manual)

Спрацьовує коли ви викликаєте **JavaScript API** з власного коду. Це найгнучкіший тип подій — ви контролюєте коли саме та з якими даними подія спрацьовує.

| Налаштування | Опис                                                                 |
| ------------ | -------------------------------------------------------------------- |
| **Name**     | Назва події, що збігається з назвою у виклику `RevolTracker.track()` |

Кастомні події детально описані у розділі [Custom Events API](#custom-events-api) нижче.

***

## Конверсійна ціль (Conversion Goal)

Будь-яку подію можна позначити як **Conversion Goal** увімкненням перемикача. Коли увімкнено:

* Подія враховується у KPI **Conversions** на Dashboard
* Використовується для розрахунку **Conversion Rate** у таблиці ефективності кампаній
* Сесії з цією подією виділяються у детальному перегляді
* Подія з'являється у конверсійних воронках та звітах

### Що робити конверсійною ціллю?

<AccordionGroup>
  <Accordion title="Лідогенерація">
    Позначте **відправлення форм** як конверсії — контактні форми, запити на розрахунок, підписки на розсилку. Це чіткі індикатори того, що відвідувач став лідом.
  </Accordion>

  <Accordion title="E-commerce">
    Позначте кастомні події **додавання в кошик** або **завершення покупки** як конверсії. Відстежуйте повну воронку від перегляду до покупки.
  </Accordion>

  <Accordion title="Залучення">
    Позначте події **прокрутка до цін** або **запуск відео** як мікро-конверсії. Вони вказують на сильний інтерес навіть без відправлення форми.
  </Accordion>

  <Accordion title="Дзвінки та чати">
    Позначте події **клік на номер телефону** або **відкриття чат-віджета** як конверсії. Вони показують намір прямої взаємодії.
  </Accordion>
</AccordionGroup>

<Tip>
  Можна мати кілька активних конверсійних цілей одночасно. KPI Conversions на Dashboard рахує унікальні сесії з **хоча б однією** конверсійною подією — тому сесія, що спрацювала 3 конверсійні події, все одно рахується як 1 конверсія.
</Tip>

***

## Custom Events API

Кастомні події дають вам повний контроль над трекінгом з вашого власного JavaScript-коду. Використовуйте їх коли автоматичний трекінг (кліки, форми, видимість) недостатній — для динамічних взаємодій, багатокрокових процесів або бізнес-специфічних дій.

### Базове використання

```javascript theme={null}
// Проста подія — без додаткових даних
RevolTracker.track('button_clicked');

// Подія з кастомними даними
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)
```

| Параметр    | Тип      | Обов'язковий | Опис                                                                                             |
| ----------- | -------- | ------------ | ------------------------------------------------------------------------------------------------ |
| `eventName` | `string` | Так          | Назва події — повинна збігатися з назвою у вкладці Events, якщо потрібна прив'язка до визначення |
| `data`      | `object` | Ні           | Кастомний payload — будь-які JSON-серіалізовані дані (об'єкти, масиви, рядки, числа)             |

**Автоматично фіксується** (не потрібно передавати):

* Поточний URL сторінки
* ID сесії
* Часова мітка
* ID компанії

### Приклади E-Commerce

Відстеження повної воронки покупок:

```javascript theme={null}
// Перегляд товару
RevolTracker.track('product_viewed', {
    product_id: 'SKU-12345',
    product_name: 'Running Shoes Pro',
    category: 'Footwear',
    price: 89.99
});

// Додавання в кошик
RevolTracker.track('add_to_cart', {
    product_id: 'SKU-12345',
    quantity: 1,
    price: 89.99
});

// Початок оформлення замовлення
RevolTracker.track('checkout_started', {
    cart_total: 89.99,
    items_count: 1
});

// Покупка завершена
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 }
    ]
});
```

### Інтеграція «Додати в кошик»

Повний приклад інтеграції кастомних подій з кнопкою «Додати в кошик»:

```html theme={null}
<button class="add-to-cart-btn"
        data-product-id="SKU-12345"
        data-product-name="Running Shoes Pro"
        data-price="89.99">
    Додати в кошик
</button>

<script>
document.querySelectorAll('.add-to-cart-btn').forEach(function(btn) {
    btn.addEventListener('click', function() {
        // Ваша існуюча логіка кошика
        addItemToCart(this.dataset.productId);

        // Відстеження події в Revol
        RevolTracker.track('add_to_cart', {
            product_id: this.dataset.productId,
            product_name: this.dataset.productName,
            price: parseFloat(this.dataset.price)
        });
    });
});
</script>
```

### Приклад форми лідогенерації

Відстеження відправлення форм з даними полів:

```html theme={null}
<form id="contact-form">
    <input name="name" type="text" placeholder="Ваше ім'я">
    <input name="email" type="email" placeholder="Email">
    <input name="phone" type="tel" placeholder="Телефон">
    <textarea name="message" placeholder="Повідомлення"></textarea>
    <button type="submit">Надіслати</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

Для single-page додатків — відправлення подій при зміні маршрутів або взаємодії з компонентами:

```javascript theme={null}
// React — відстеження перегляду сторінки при зміні маршруту
useEffect(() => {
    RevolTracker.track('page_view', {
        page: location.pathname,
        title: document.title
    });
}, [location.pathname]);

// React — відстеження кліку на кнопку
function handlePricingClick(plan) {
    RevolTracker.track('pricing_plan_selected', {
        plan: plan,
        page: '/pricing'
    });
}
```

### Як відправляються події

Події **буферизуються та відправляються пакетами** для продуктивності:

1. Кожен виклик `RevolTracker.track()` додає подію у внутрішній буфер
2. Кожні **5 секунд** всі буферизовані події відправляються на сервер одним запитом
3. При **закритті сторінки** залишкові події відправляються через `sendBeacon()` для надійності
4. Максимум **50 подій** на пакет — зайві події відкидаються

<Note>
  Не обов'язково створювати визначення події у дашборді, щоб кастомні події записувалися. Невизначені кастомні події все одно зберігаються з даними — але не матимуть лічильника спрацювань у списку Events. Для повного трекінгу створіть відповідне визначення з тією самою назвою.
</Note>

***

## Аналіз сайту за допомогою Claude Code

Якщо ви не впевнені які елементи відстежувати, ви можете використати **Claude Code** для аналізу вашого сайту та рекомендації оптимального набору подій.

<Accordion title="Промпт для аналізу сайту">
  ```text theme={null}
  # Інструкція: Генерація класів для відстеження подій на сайті

  ## Контекст

  Я використовую систему трекінгу Revol, яка відстежує дії
  користувачів на сайті через CSS-селектори. Трекер підключається
  одним скриптом і автоматично слухає події на елементах, які
  відповідають заданим CSS-селекторам. Ніякого додаткового JS-коду
  на сайті не потрібно (за винятком AJAX-форм, про це нижче).

  ## Як працює трекінг подій

  Система підтримує 5 типів подій:

  - click — клік на елемент. Працює через
    document.addEventListener('click') + e.target.closest(css_selector),
    делегування на document у capture phase.
  - form_submit — відправка форми. Працює через
    document.addEventListener('submit') + перевірка css_selector
    на тезі <form>.
  - scroll — прокрутка до елемента. IntersectionObserver з threshold
    (0-100%), спрацьовує один раз за сесію.
  - visibility — елемент з'явився у viewport. IntersectionObserver,
    одноразово.
  - custom — ручний виклик з JS: RevolTracker.track('Назва', {data})

  ## Твоє завдання

  ### Крок 1: Проаналізуй всі сторінки сайту

  Пройди по всіх HTML/шаблонних файлах і знайди:

  1. Кнопки (buttons/links) — CTA, навігація, дії
  2. Телефонні номери — <a href="tel:...">, текстові блоки з номерами
  3. Email-посилання — <a href="mailto:...">
  4. Месенджери — Telegram, Viber, WhatsApp посилання
  5. Форми — контактні, заявки, підписки, замовлення
  6. Клікабельні блоки — картки, банери, секції з посиланнями
  7. Елементи конверсії — кошик, замовлення, реєстрація

  ### Крок 2: Додай CSS-класи для трекінгу

  Для кожного знайденого елемента додай CSS-клас з префіксом rv-:

  Конвенція іменування: rv-{тип}-{секція}-{дія}
  Типи: btn, link, form, block, scroll

  Приклади:
  - rv-btn-hero-cta — кнопка CTA в hero-секції
  - rv-btn-header-phone — клік на телефон у хедері
  - rv-btn-footer-phone — клік на телефон у футері
  - rv-btn-pricing-order — кнопка замовлення
  - rv-btn-header-telegram — клік на Telegram у хедері
  - rv-form-contact — контактна форма
  - rv-form-callback — форма зворотного дзвінка
  - rv-block-services-card — клік на картку послуги
  - rv-link-nav-about — навігаційне посилання "Про нас"
  - rv-scroll-testimonials — прокрутка до відгуків

  Правила:
  - Клас rv-* додається ДОДАТКОВО до існуючих класів
  - Один елемент = один rv- клас
  - Клас має бути унікальним на сторінці (або спільним
    для однотипних елементів, наприклад всі картки послуг)

  ### Крок 3: Правила для форм

  Клас rv-form-* ставиться на тег <form>, НЕ на кнопку submit:

    Правильно:
    <form class="contact-form rv-form-contact" action="/submit">
      <input name="phone" type="tel">
      <button type="submit">Надіслати</button>
    </form>

    Неправильно:
    <form class="contact-form">
      <button class="rv-form-contact" type="submit">Надіслати</button>
    </form>

  AJAX-форми (без нативного submit):

  Якщо форма відправляється через JS (fetch, axios, $.ajax) без
  нативної події submit, трекер НЕ зловить її автоматично. Ознаки:
  - e.preventDefault() + fetch/axios/$.ajax в обробнику
  - Форма без action або з action="javascript:void(0)"
  - Кнопка має type="button" замість type="submit"

  Для таких форм додай ручний виклик поряд з AJAX-відправкою:
    RevolTracker.track('Контактна форма', { form: 'contact' });

  В таблиці подій такі форми позначай типом custom замість
  form_submit і вказуй що потрібен ручний виклик.

  ### Крок 4: Сформуй таблицю подій

  Назви подій — українською мовою. Формат таблиці:

  № | Назва події | CSS-селектор | Тип | Конверсія? | Сторінка | Опис

  Приклад:
  1 | Клік CTA Hero | .rv-btn-hero-cta | click | Так | Головна | Основна кнопка в hero-банері
  2 | Клік телефон хедер | .rv-btn-header-phone | click | Так | Всі | Клік на телефон у шапці
  3 | Клік телефон футер | .rv-btn-footer-phone | click | Так | Всі | Клік на телефон у підвалі
  4 | Клік Telegram | .rv-btn-header-telegram | click | Так | Всі | Клік на Telegram
  5 | Контактна форма | .rv-form-contact | form_submit | Так | Контакти | Відправка контактної форми
  6 | Форма зворотного дзвінка | .rv-form-callback | form_submit | Так | Головна | Форма "Передзвоніть мені"
  7 | Клік картка послуги | .rv-block-services-card | click | Ні | Послуги | Клік на картку послуги
  8 | Навігація Про нас | .rv-link-nav-about | click | Ні | Всі | Перехід на сторінку "Про нас"
  9 | Скрол до відгуків | .rv-scroll-testimonials | scroll (80%) | Ні | Головна | Доскролив до відгуків
  10 | Форма заявки (AJAX) | — | custom | Так | Послуги | AJAX-форма, потрібен RevolTracker.track()

  ### Що вважати конверсією

  Так — конверсія:
  - Клік на телефон (<a href="tel:...">)
  - Клік на email (<a href="mailto:...">)
  - Клік на месенджери (Telegram, Viber, WhatsApp)
  - Відправка будь-якої форми (заявка, замовлення, зв'язок)
  - Клік на CTA-кнопки ("Замовити", "Купити", "Записатись")

  Ні — не конверсія:
  - Навігаційні посилання
  - Кліки на інформаційні блоки/картки (якщо це не CTA)
  - Scroll/visibility події
  - Кліки на соцмережі (якщо це не CTA)

  ## Формат відповіді

  1. Список змін у файлах — які класи rv-* додати, з diff
  2. Таблиця подій — повний перелік подій з усіма колонками
  3. AJAX-форми — окремо перелічи форми що потребують ручного
     виклику RevolTracker.track(), з готовим кодом вставки

  Мій сайт: [ВСТАВТЕ URL]
  Тип бізнесу: [напр. e-commerce, SaaS, послуги, агенція]
  Основна конверсійна дія: [напр. заповнення форми, покупка, запис]
  ```
</Accordion>