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

# Zdarzenia

> Definiuj niestandardowe zdarzenia śledzenia — kliknięcia, formularze, wyzwalacze przewijania, widoczność — i ustaw cele konwersji

## Przegląd

Zakładka Zdarzenia pozwala definiować zdarzenia śledzenia w celu rejestrowania konkretnych działań odwiedzających na Twojej stronie. Śledź kliknięcia przycisków, wysyłki formularzy, kamienie milowe przewijania, widoczność elementów lub wywoływaj niestandardowe zdarzenia z własnego kodu. Każde zdarzenie może być oznaczone jako **cel konwersji** do mierzenia skuteczności kampanii.

<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="Zakładka Zdarzenia" 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="Zakładka Zdarzenia" width="2873" height="1553" data-path="images/tracker-events-dark.png" />
</Frame>

## Lista zdarzeń

Tabela zdarzeń pokazuje wszystkie zdefiniowane zdarzenia z kluczowymi metrykami:

| Kolumna       | Opis                                                                                    |
| ------------- | --------------------------------------------------------------------------------------- |
| **Nazwa**     | Nazwa zdarzenia                                                                         |
| **Typ**       | Typ zdarzenia (Kliknięcie, Przewijanie, Wysyłka formularza, Widoczność, Niestandardowe) |
| **Wywołania** | Łączna liczba wywołań tego zdarzenia                                                    |
| **Konwersja** | Czy zdarzenie liczy się jako cel konwersji                                              |
| **Status**    | Aktywne lub nieaktywne                                                                  |
| **Akcje**     | Edytuj lub usuń zdarzenie                                                               |

### Filtry

Filtruj listę zdarzeń według:

| Filtr            | Opis                                          |
| ---------------- | --------------------------------------------- |
| **Typ**          | Pokaż tylko zdarzenia określonego typu        |
| **Konwersja**    | Pokaż tylko zdarzenia będące celami konwersji |
| **Status**       | Pokaż aktywne lub nieaktywne zdarzenia        |
| **Wyszukiwanie** | Szukaj zdarzeń po nazwie                      |

***

## Tworzenie zdarzenia

Kliknij **Utwórz zdarzenie**, aby zdefiniować nowe zdarzenie śledzenia. Każde zdarzenie wymaga:

| Pole              | Wymagane | Opis                                                                                       |
| ----------------- | -------- | ------------------------------------------------------------------------------------------ |
| **Nazwa**         | Tak      | Nazwa zdarzenia do identyfikacji (np. "Kliknięcie CTA", "Wysyłka formularza kontaktowego") |
| **Typ**           | Tak      | Sposób wywoływania zdarzenia (zobacz Typy zdarzeń poniżej)                                 |
| **Selektor CSS**  | Zależy   | Selektor CSS wskazujący element (wymagany dla Kliknięcia, Wysyłki formularza, Widoczności) |
| **URL strony**    | Nie      | Ogranicz zdarzenie do wywoływania tylko na konkretnej stronie                              |
| **Cel konwersji** | Nie      | Przełącznik, aby liczyć zdarzenie jako konwersję w analityce                               |

***

## Typy zdarzeń

Każdy typ zdarzenia śledzi inny rodzaj interakcji odwiedzającego. Skrypt trackera obsługuje wszystkie automatyczne typy — kodowanie nie jest wymagane.

### Kliknięcie

Wywołuje się, gdy odwiedzający **kliknie** element pasujący do selektora CSS.

| Ustawienie       | Opis                                                                               |
| ---------------- | ---------------------------------------------------------------------------------- |
| **Selektor CSS** | Selektor elementu docelowego (np. `#cta-button`, `.buy-now`, `a[href="/contact"]`) |
| **URL strony**   | Opcjonalne — ogranicz śledzenie do konkretnej strony                               |

**Co jest rejestrowane:**

* Treść tekstowa elementu (pierwsze 100 znaków)
* Nazwa tagu elementu (`button`, `a`, `div` itp.)
* Selektor CSS, który pasował
* Aktualny URL strony

<Tip>
  Użyj DevTools przeglądarki, aby znaleźć odpowiedni selektor CSS. Kliknij prawym przyciskiem myszy element → **Zbadaj** → kliknij prawym przyciskiem myszy tag HTML → **Kopiuj** → **Kopiuj selektor**.
</Tip>

**Przykłady selektorów CSS:**

```css theme={null}
/* Przycisk po ID */
#buy-now-btn

/* Wszystkie przyciski z konkretną klasą */
.add-to-cart

/* Link do konkretnej strony */
a[href="/pricing"]

/* Przycisk wewnątrz konkretnej sekcji */
.hero-section .cta-button

/* Dowolny element z atrybutem data */
[data-action="subscribe"]
```

### Przewijanie (Widoczność)

Wywołuje się, gdy odwiedzający **przewinie** obok konkretnego elementu na stronie. Używa IntersectionObserver do wykrywania, kiedy element pojawia się w oknie widoku.

| Ustawienie           | Opis                                                                     |
| -------------------- | ------------------------------------------------------------------------ |
| **Selektor CSS**     | Element docelowy do obserwacji (np. `#pricing-section`, `.testimonials`) |
| **Próg przewijania** | Procent elementu, który musi być widoczny (domyślnie: 50%)               |

**Przypadki użycia:**

* Śledź, ilu odwiedzających widzi Twoją sekcję cenową
* Mierz zaangażowanie w konkretne bloki treści
* Wykrywaj, czy odwiedzający docierają do końca długiej strony

<Note>
  Każde zdarzenie przewijania wywołuje się **tylko raz** na sesję na element — nawet jeśli odwiedzający przewinie obok niego wielokrotnie. Zapobiega to zawyżeniu liczników.
</Note>

### Wysyłka formularza

Wywołuje się, gdy odwiedzający **wyśle formularz** pasujący do selektora CSS.

| Ustawienie          | Opis                                                                                |
| ------------------- | ----------------------------------------------------------------------------------- |
| **Selektor CSS**    | Element docelowy formularza (np. `#contact-form`, `.signup-form`)                   |
| **Pola formularza** | Opcjonalne — lista dozwolonych nazw pól do rejestrowania (np. `email, phone, name`) |

**Co jest rejestrowane:**

* Wartości z pól `<input>`, `<select>` i `<textarea>`
* Nazwy pól i ich wartości (do 500 znaków na pole)
* Pola hasła i ukryte są **automatycznie wykluczane**

<Warning>
  Domyślnie rejestrowane są wszystkie widoczne pola formularza. Użyj listy dozwolonych **Pól formularza**, aby ograniczyć zbieranie danych do konkretnych pól i uniknąć rejestrowania wrażliwych informacji.
</Warning>

### Widoczność elementu

Wywołuje się, gdy konkretny element **staje się widoczny** w oknie widoku przeglądarki. Podobne do Przewijania, ale skoncentrowane na śledzeniu, czy dany element interfejsu został zobaczony.

| Ustawienie       | Opis                                                     |
| ---------------- | -------------------------------------------------------- |
| **Selektor CSS** | Element docelowy (np. `.promo-banner`, `#special-offer`) |

**Przypadki użycia:**

* Śledź wyświetlenia banerów promocyjnych
* Mierz widoczność ważnych CTA
* Wykrywaj, czy dynamicznie ładowana treść jest widziana (działa z SPA)

<Note>
  Tracker używa MutationObserver do obserwacji dynamicznie dodawanych elementów. Jeśli element docelowy jest renderowany przez JavaScript po załadowaniu strony (React, Vue itp.), nadal zostanie wykryty.
</Note>

### Niestandardowe (ręczne)

Wywołuje się, gdy wywołasz **JavaScript API** z własnego kodu. To najbardziej elastyczny typ zdarzenia — sam kontrolujesz, kiedy i z jakimi danymi zdarzenie się wywołuje.

| Ustawienie | Opis                                                            |
| ---------- | --------------------------------------------------------------- |
| **Nazwa**  | Nazwa zdarzenia zgodna z nazwą używaną w `RevolTracker.track()` |

Zdarzenia niestandardowe są szczegółowo opisane w sekcji [API zdarzeń niestandardowych](#custom-events-api) poniżej.

***

## Cel konwersji

Każde zdarzenie może być oznaczone jako **Cel konwersji** poprzez włączenie przełącznika. Po włączeniu:

* Zdarzenie jest liczone na karcie KPI **Konwersje** w Panelu analitycznym
* Jest używane do obliczania **Współczynnika konwersji** w tabeli Wydajność kampanii
* Sesje zawierające to zdarzenie są wyróżnione w widoku szczegółów sesji
* Zdarzenie pojawia się w lejkach konwersji i raportach

### Co stanowi dobry cel konwersji?

<AccordionGroup>
  <Accordion title="Generowanie leadów">
    Oznacz **wysyłki formularzy** jako konwersje — formularze kontaktowe, prośby o wycenę, zapisy na newsletter. To wyraźne wskaźniki, że odwiedzający stał się leadem.
  </Accordion>

  <Accordion title="E-commerce">
    Oznacz zdarzenia niestandardowe **dodaj do koszyka** lub **zakup zakończony** jako konwersje. Śledź pełny lejek od odsłony strony do zakupu.
  </Accordion>

  <Accordion title="Zaangażowanie">
    Oznacz zdarzenia **przewinięcie za cennik** lub **odtworzenie wideo** jako mikro-konwersje. Wskazują one na silne zainteresowanie nawet bez wysłania formularza.
  </Accordion>

  <Accordion title="Połączenia i czaty">
    Oznacz zdarzenia **kliknięcie numeru telefonu** lub **otwarcie widżetu czatu** jako konwersje. Pokazują one zamiar bezpośredniego kontaktu.
  </Accordion>
</AccordionGroup>

<Tip>
  Możesz mieć jednocześnie wiele aktywnych celów konwersji. KPI Konwersje w Panelu analitycznym liczy unikalne sesje z **co najmniej jednym** zdarzeniem konwersji — więc sesja, która wywołuje 3 zdarzenia konwersji, nadal liczy się jako 1 konwersja.
</Tip>

***

## API zdarzeń niestandardowych

Zdarzenia niestandardowe dają pełną kontrolę nad śledzeniem zdarzeń z własnego kodu JavaScript. Używaj ich, gdy automatyczne śledzenie (kliknięcia, formularze, widoczność) nie wystarczy — dla dynamicznych interakcji, wieloetapowych procesów lub działań specyficznych dla biznesu.

### Podstawowe użycie

```javascript theme={null}
// Proste zdarzenie — bez dodatkowych danych
RevolTracker.track('button_clicked');

// Zdarzenie z niestandardowymi danymi
RevolTracker.track('item_added_to_cart', {
    item_id: 'SKU-12345',
    item_name: 'Running Shoes',
    price: 89.99,
    currency: 'USD'
});
```

### Dokumentacja API

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

| Parametr    | Typ      | Wymagany | Opis                                                                                                                        |
| ----------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------- |
| `eventName` | `string` | Tak      | Nazwa zdarzenia — musi odpowiadać nazwie zdefiniowanej w zakładce Zdarzenia, jeśli chcesz powiązać ją z definicją zdarzenia |
| `data`      | `object` | Nie      | Niestandardowy ładunek — dowolne dane serializowalne do JSON (obiekty, tablice, łańcuchy, liczby)                           |

**Automatycznie rejestrowane** (nie musisz ich przekazywać):

* Aktualny URL strony
* Identyfikator sesji
* Znacznik czasu
* Identyfikator firmy

### Przykłady e-commerce

Śledź pełny lejek zakupowy:

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

// Dodano do koszyka
RevolTracker.track('add_to_cart', {
    product_id: 'SKU-12345',
    quantity: 1,
    price: 89.99
});

// Rozpoczęto realizację zamówienia
RevolTracker.track('checkout_started', {
    cart_total: 89.99,
    items_count: 1
});

// Zakup zakończony
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 }
    ]
});
```

### Integracja Dodaj do koszyka

Kompletny przykład integracji zdarzeń niestandardowych z przyciskiem "Dodaj do koszyka":

```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() {
        // Twoja istniejąca logika koszyka
        addItemToCart(this.dataset.productId);

        // Śledź zdarzenie w Revol
        RevolTracker.track('add_to_cart', {
            product_id: this.dataset.productId,
            product_name: this.dataset.productName,
            price: parseFloat(this.dataset.price)
        });
    });
});
</script>
```

### Przykład formularza kontaktowego

Śledź wysyłki formularzy z danymi pól:

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

### Przykład SPA / React

Dla aplikacji jednostronicowych wywołuj zdarzenia przy zmianach tras lub interakcjach z komponentami:

```javascript theme={null}
// React — śledzenie odsłony strony przy zmianie trasy
useEffect(() => {
    RevolTracker.track('page_view', {
        page: location.pathname,
        title: document.title
    });
}, [location.pathname]);

// React — śledzenie kliknięcia przycisku
function handlePricingClick(plan) {
    RevolTracker.track('pricing_plan_selected', {
        plan: plan,
        page: '/pricing'
    });
}
```

### Jak zdarzenia są wysyłane

Zdarzenia są **buforowane i wysyłane partiami** dla wydajności:

1. Każde wywołanie `RevolTracker.track()` dodaje zdarzenie do wewnętrznego bufora
2. Co **5 sekund** wszystkie zbuforowane zdarzenia są wysyłane na serwer w jednym żądaniu
3. Przy **opuszczaniu strony** pozostałe zdarzenia są wysyłane przez `sendBeacon()` dla niezawodności
4. Maksymalnie **50 zdarzeń** na partię — nadmiarowe zdarzenia są odrzucane

<Note>
  Nie musisz tworzyć definicji zdarzenia w panelu, aby zdarzenia niestandardowe były rejestrowane. Niezdefiniowane zdarzenia niestandardowe są nadal zapisywane z ich danymi — ale nie będą miały licznika wywołań na liście Zdarzeń. Dla pełnego śledzenia utwórz pasującą definicję zdarzenia o tej samej nazwie.
</Note>

***

## Przeanalizuj swoją stronę za pomocą Claude Code

Jeśli nie jesteś pewien, które elementy śledzić, możesz użyć **Claude Code** do analizy swojej strony i zasugerowania optymalnej konfiguracji śledzenia zdarzeń.

<Accordion title="Prompt do analizy strony">
  ```text theme={null}
  # Instrukcja: Generowanie klas CSS do sledzenia zdarzen na stronie

  ## Kontekst

  Uzywam systemu sledzenia Revol, ktory monitoruje dzialania
  uzytkownikow na stronach za pomoca selektorow CSS. Tracker jest
  osadzany jednym skryptem i automatycznie nasluchuje zdarzen na
  elementach pasujacych do podanych selektorow CSS. Zaden dodatkowy
  kod JS na stronie nie jest potrzebny (z wyjatkiem formularzy AJAX,
  patrz nizej).

  ## Jak dziala sledzenie zdarzen

  System obsluguje 5 typow zdarzen:

  - click — klikniecie elementu. Uzywa
    document.addEventListener('click') + e.target.closest(css_selector),
    delegacja na document w fazie przechwytywania.
  - form_submit — wyslanie formularza. Uzywa
    document.addEventListener('submit') + sprawdza css_selector
    na tagu <form>.
  - scroll — przewiniecie do elementu. IntersectionObserver
    z threshold (0-100%), wyzwala sie raz na sesje.
  - visibility — element pojawil sie w viewport. IntersectionObserver,
    jednorazowo.
  - custom — reczne wywolanie JS: RevolTracker.track('Nazwa', {data})

  ## Twoje Zadanie

  ### Krok 1: Przeanalizuj wszystkie strony

  Przejrzyj wszystkie pliki HTML/szablonow i znajdz:

  1. Przyciski (buttons/links) — CTA, nawigacja, akcje
  2. Numery telefonow — <a href="tel:...">, bloki tekstu z numerami
  3. Linki email — <a href="mailto:...">
  4. Komunikatory — Telegram, Viber, WhatsApp linki
  5. Formularze — kontaktowe, zgloszenia, subskrypcje, zamowienia
  6. Klikalne bloki — karty, bannery, sekcje z linkami
  7. Elementy konwersji — koszyk, zamowienie, rejestracja

  ### Krok 2: Dodaj klasy CSS do sledzenia

  Dla kazdego znalezionego elementu dodaj klase CSS z prefiksem rv-:

  Konwencja nazewnictwa: rv-{typ}-{sekcja}-{akcja}
  Typy: btn, link, form, block, scroll

  Przyklady:
  - rv-btn-hero-cta — przycisk CTA w sekcji hero
  - rv-btn-header-phone — klikniecie telefonu w naglowku
  - rv-btn-footer-phone — klikniecie telefonu w stopce
  - rv-btn-pricing-order — przycisk zamowienia na cennik
  - rv-btn-header-telegram — klikniecie Telegram w naglowku
  - rv-form-contact — formularz kontaktowy
  - rv-form-callback — formularz oddzwonienia
  - rv-block-services-card — klikniecie karty uslugi
  - rv-link-nav-about — link nawigacyjny "O nas"
  - rv-scroll-testimonials — przewiniecie do opinii

  Zasady:
  - Klasa rv-* jest dodawana DODATKOWO do istniejacych klas
  - Jeden element = jedna klasa rv-
  - Klasa powinna byc unikalna na stronie (lub celowo wspolna
    dla podobnych elementow, np. wszystkie karty uslug)

  ### Krok 3: Zasady dla formularzy

  Klasa rv-form-* idzie na tag <form>, NIE na przycisk submit:

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

    Niepoprawnie:
    <form class="contact-form">
      <button class="rv-form-contact" type="submit">Wyslij</button>
    </form>

  Formularze AJAX (bez natywnego submit):

  Jesli formularz jest wysylany przez JS (fetch, axios, $.ajax) bez
  natywnego zdarzenia submit, tracker go NIE przechwyci. Oznaki:
  - e.preventDefault() + fetch/axios/$.ajax w handlerze
  - Formularz bez action lub z action="javascript:void(0)"
  - Przycisk ma type="button" zamiast type="submit"

  Dla takich formularzy dodaj reczne wywolanie obok AJAX:
    RevolTracker.track('Formularz kontaktowy', { form: 'contact' });

  W tabeli zdarzen oznacz takie jako typ custom zamiast form_submit
  i zaznacz, ze potrzebne jest reczne wywolanie.

  ### Krok 4: Utworz tabele zdarzen

  Nazwy zdarzen po polsku. Format tabeli:

  # | Nazwa zdarzenia | Selektor CSS | Typ | Konwersja? | Strona | Opis

  Przyklad:
  1 | Klik CTA Hero | .rv-btn-hero-cta | click | Tak | Glowna | Glowny CTA w hero
  2 | Klik telefon naglowek | .rv-btn-header-phone | click | Tak | Wszystkie | Klik telefonu w naglowku
  3 | Klik telefon stopka | .rv-btn-footer-phone | click | Tak | Wszystkie | Klik telefonu w stopce
  4 | Klik Telegram | .rv-btn-header-telegram | click | Tak | Wszystkie | Klik linku Telegram
  5 | Formularz kontaktowy | .rv-form-contact | form_submit | Tak | Kontakt | Wyslanie formularza
  6 | Formularz oddzwonienia | .rv-form-callback | form_submit | Tak | Glowna | Formularz "Oddzwon"
  7 | Klik karta uslugi | .rv-block-services-card | click | Nie | Uslugi | Klik na karte uslugi
  8 | Nav — O nas | .rv-link-nav-about | click | Nie | Wszystkie | Przejscie do "O nas"
  9 | Scroll do opinii | .rv-scroll-testimonials | scroll (80%) | Nie | Glowna | Przewiniecie do opinii
  10 | Formularz zgloszenia (AJAX) | — | custom | Tak | Uslugi | AJAX, potrzebuje RevolTracker.track()

  ### Co liczy sie jako konwersja

  Tak — konwersja:
  - Klik telefonu (<a href="tel:...">)
  - Klik emaila (<a href="mailto:...">)
  - Klik komunikatorow (Telegram, Viber, WhatsApp)
  - Wyslanie dowolnego formularza (zgloszenie, zamowienie, kontakt)
  - Klik przyciskow CTA ("Zamow", "Kup", "Zarezerwuj")

  Nie — nie konwersja:
  - Linki nawigacyjne
  - Klikniecia na bloki informacyjne (jesli nie CTA)
  - Zdarzenia scroll/visibility
  - Klikniecia social media (jesli nie CTA)

  ## Format odpowiedzi

  1. Zmiany w plikach — jakie klasy rv-* dodac, z diff
  2. Tabela zdarzen — pelna lista ze wszystkimi kolumnami
  3. Formularze AJAX — osobno wymienic formularze wymagajace
     recznego wywolania RevolTracker.track(), z gotowym kodem

  Moja strona: [WKLEJ URL]
  Typ biznesu: [np. e-commerce, SaaS, uslugi, agencja]
  Glowna akcja konwersji: [np. formularz, zakup, rezerwacja]
  ```
</Accordion>