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

# Wyzwalacze

> Twórz automatyczne wyskakujące okna, nakładki i paski powiadomień na podstawie reguł zachowania odwiedzających

## Przegląd

Zakładka Wyzwalacze pozwala tworzyć automatyczne akcje wywoływane na podstawie zachowania odwiedzających. Gdy odwiedzający spełnia określone warunki — czas na stronie, głębokość przewijania, źródło UTM, typ urządzenia i inne — wyzwalacz wyświetla modalne okno, powiadomienie toast lub przekierowuje na URL. Wyzwalacze to potężny sposób angażowania odwiedzających w odpowiednim momencie bez kodowania.

<Frame>
  <img className="block dark:hidden" src="https://mintcdn.com/revolai/f9LQJGx083qnby8Z/images/tracker-triggers-light.png?fit=max&auto=format&n=f9LQJGx083qnby8Z&q=85&s=fec85aca2ff7a7e885b2135a613e6bf2" alt="Zakładka Wyzwalacze" width="2873" height="1553" data-path="images/tracker-triggers-light.png" />

  <img className="hidden dark:block" src="https://mintcdn.com/revolai/f9LQJGx083qnby8Z/images/tracker-triggers-dark.png?fit=max&auto=format&n=f9LQJGx083qnby8Z&q=85&s=f0477710da21258fa6da56cd2c8e6e61" alt="Zakładka Wyzwalacze" width="2860" height="1550" data-path="images/tracker-triggers-dark.png" />
</Frame>

## Lista wyzwalaczy

Tabela wyzwalaczy pokazuje wszystkie zdefiniowane wyzwalacze z kluczowymi metrykami:

| Kolumna       | Opis                                                                                                  |
| ------------- | ----------------------------------------------------------------------------------------------------- |
| **Nazwa**     | Nazwa wyzwalacza                                                                                      |
| **Typ**       | Typ akcji — Modal (wyśrodkowane okno), Toast (powiadomienie w rogu) lub Redirect (przekierowanie URL) |
| **Warunki**   | Podsumowanie warunków wywoływania                                                                     |
| **Wywołania** | Łączna liczba aktywacji                                                                               |
| **Status**    | Aktywny lub nieaktywny                                                                                |
| **Akcje**     | Edytuj lub usuń wyzwalacz                                                                             |

***

## Tworzenie wyzwalacza

Kliknij **Utwórz wyzwalacz**, aby otworzyć edytor wyzwalaczy. Edytor ma dwie zakładki: **Treść** dla zawartości wizualnej i **Ustawienia** dla reguł zachowania.

<Frame>
  <img className="block dark:hidden" src="https://mintcdn.com/revolai/f9LQJGx083qnby8Z/images/create-trigger-light.png?fit=max&auto=format&n=f9LQJGx083qnby8Z&q=85&s=6ba8d47a8d3e0fe412e40aedce804b8f" alt="Edytor tworzenia wyzwalacza" width="2869" height="1549" data-path="images/create-trigger-light.png" />

  <img className="hidden dark:block" src="https://mintcdn.com/revolai/f9LQJGx083qnby8Z/images/create-trigger-dark.png?fit=max&auto=format&n=f9LQJGx083qnby8Z&q=85&s=6e16455d986a9e73e653df928889e3c9" alt="Edytor tworzenia wyzwalacza" width="2867" height="1556" data-path="images/create-trigger-dark.png" />
</Frame>

***

## Zakładka Treść

Zakładka Treść to wizualny edytor blokowy, w którym budujesz zawartość wyzwalacza. Każdy wyzwalacz składa się z **bloków treści**, które dodajesz, układasz i stylujesz.

### Dodawanie bloków

Kliknij przycisk **+ Dodaj blok**, aby otworzyć wybór bloków. Dostępne typy bloków:

| Blok                  | Opis                                                                                                                                                                                                                          |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Obraz**             | Dodaj obraz — załaduj plik lub wklej URL. Idealny do zdjęć produktów, banerów lub ikon.                                                                                                                                       |
| **Nagłówek**          | Duży tekst dla tytułów i nagłówków. Obsługuje wyrównanie tekstu (do lewej lub do środka).                                                                                                                                     |
| **Tekst**             | Tekst treści z bogatym formatowaniem. Użyj do opisów, ofert lub instrukcji.                                                                                                                                                   |
| **Lista funkcji**     | Lista punktowana z ikonami ✓ — idealna do wymieniania korzyści, funkcji lub elementów w zestawie.                                                                                                                             |
| **Pole wprowadzania** | Jednowierszowe pole tekstowe do zbierania danych (imię, e-mail, telefon).                                                                                                                                                     |
| **Pole tekstowe**     | Wielowierszowe pole tekstowe do dłuższych odpowiedzi (wiadomości, opinie).                                                                                                                                                    |
| **Przycisk**          | Klikalny przycisk z konfigurowalnym tekstem, kolorem i akcją (link, zamknij lub wyślij dane formularza).                                                                                                                      |
| **Kod promocyjny**    | Stylizowany blok z kodem promocyjnym z przyciskiem kopiowania. Odwiedzający klikają, aby skopiować kod do schowka.                                                                                                            |
| **Kod QR**            | Osadza kod QR kampanii bezpośrednio w wyzwalaczu. Odwiedzający skanują go telefonem, aby kontynuować na urządzeniu mobilnym — z pełną atrybucją kampanii. Zobacz [Kampanie — Kod QR](/widget/campaigns#qr-code) po szczegóły. |
| **Separator**         | Linia pozioma do wizualnego oddzielenia sekcji.                                                                                                                                                                               |

### Ustawienia bloków

Każdy typ bloku ma własne edytowalne właściwości. Kliknij blok, aby go wybrać i skonfigurować:

**Obraz:**

| Ustawienie             | Opis                                          |
| ---------------------- | --------------------------------------------- |
| **URL**                | URL źródła obrazu                             |
| **Tekst alternatywny** | Tekst alternatywny dla dostępności            |
| **Zaokrąglenie rogów** | Zaokrąglenie rogów w pikselach (domyślnie: 0) |

**Nagłówek:**

| Ustawienie     | Opis                               |
| -------------- | ---------------------------------- |
| **Tekst**      | Treść nagłówka                     |
| **Wyrównanie** | Do lewej (domyślnie) lub Do środka |

**Tekst:**

| Ustawienie     | Opis                                                                         |
| -------------- | ---------------------------------------------------------------------------- |
| **Treść HTML** | Tekst z formatowaniem — obsługuje `<b>`, `<i>`, `<u>`, `<a>`, listy i `<br>` |

**Lista funkcji:**

| Ustawienie   | Opis                                                                                                                      |
| ------------ | ------------------------------------------------------------------------------------------------------------------------- |
| **Elementy** | Dynamiczna lista funkcji. Każdy element ma ikonę (emoji), tytuł i tekst opisu. Kliknij "Dodaj element", aby dodać więcej. |

**Pole wprowadzania:**

| Ustawienie      | Opis                                         |
| --------------- | -------------------------------------------- |
| **Klucz**       | Nazwa pola formularza (np. `email`, `phone`) |
| **Typ**         | Tekst, E-mail, Telefon lub Numer             |
| **Etykieta**    | Etykieta pola wyświetlana nad polem          |
| **Placeholder** | Tekst podpowiedzi wewnątrz pola              |
| **Wymagane**    | Czy pole musi być wypełnione przed wysłaniem |

**Pole tekstowe:**

| Ustawienie      | Opis                                                  |
| --------------- | ----------------------------------------------------- |
| **Klucz**       | Nazwa pola formularza                                 |
| **Wiersze**     | Liczba widocznych wierszy tekstu (1–10, domyślnie: 3) |
| **Etykieta**    | Etykieta pola                                         |
| **Placeholder** | Tekst podpowiedzi                                     |
| **Wymagane**    | Czy pole musi być wypełnione                          |

**Przycisk:**

| Ustawienie   | Opis                                                                                                                                              |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Etykieta** | Tekst przycisku                                                                                                                                   |
| **Wariant**  | Główny (jednolity kolor akcentu), Drugorzędny (jasny odcień) lub Kontur (przezroczysty z obramowaniem)                                            |
| **Akcja**    | Zamknij (odrzuć wyzwalacz), Otwórz link (przejdź do URL), Wyślij formularz (wyślij dane formularza) lub Kopiuj wartość (skopiuj tekst do schowka) |
| **Wartość**  | URL dla linków lub tekst do skopiowania                                                                                                           |

**Kod promocyjny:**

| Ustawienie   | Opis                                     |
| ------------ | ---------------------------------------- |
| **Kod**      | Tekst kodu promocyjnego (np. `SPRING20`) |
| **Etykieta** | Opcjonalna etykieta nad kodem            |

**Kod QR:**

| Ustawienie  | Opis                                                                       |
| ----------- | -------------------------------------------------------------------------- |
| **Dane QR** | URL lub tekst do zakodowania. Użyj przycisku "Utwórz QR", aby wygenerować. |
| **Rozmiar** | Rozmiar kodu QR w pikselach (domyślnie: 160)                               |

**Separator:**
Brak ustawień — renderuje poziomą linię separatora.

### Styl wyzwalacza

Kontener wyzwalacza ma globalne ustawienia stylu, które dotyczą całego okna/toastu:

| Ustawienie             | Opis                                                                                                                |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------- |
| **Kolor tła**          | Tło kontenera (domyślnie: `#ffffff`)                                                                                |
| **Kolor tekstu**       | Domyślny kolor tekstu dla wszystkich bloków (domyślnie: `#1a1a1a`)                                                  |
| **Kolor akcentu**      | Kolor przycisków, ikon funkcji i przycisku kopiowania kodu promocyjnego (domyślnie: `#4680ff`)                      |
| **Zaokrąglenie rogów** | Zaokrąglenie rogów całego wyzwalacza w pikselach (domyślnie: 16)                                                    |
| **Pozycja**            | Dla wyzwalaczy toast: prawy-górny, lewy-górny, prawy-dolny lub lewy-dolny. Dla modali: wyśrodkowany z ciemnym tłem. |

### Przykłady treści

<AccordionGroup>
  <Accordion title="Wyskakujące okno ze zniżką powitalną">
    * **Nagłówek**: "Odbierz 10% zniżki na pierwsze zamówienie"
    * **Tekst**: "Zapisz się na nasz newsletter i otrzymaj ekskluzywny kod rabatowy."
    * **Pole wprowadzania**: E-mail
    * **Przycisk**: "Odbierz zniżkę" (akcja wysyłki)
    * **Kod promocyjny**: Wyświetlany po wysłaniu formularza
  </Accordion>

  <Accordion title="Oferta przy zamiarze wyjścia">
    * **Obraz**: Zdjęcie produktu
    * **Nagłówek**: "Poczekaj! Nie przegap tego."
    * **Tekst**: "Darmowa dostawa przy zamówieniach powyżej 200 zł — tylko dziś."
    * **Przycisk**: "Kup teraz" (link do sklepu)
    * **Przycisk**: "Nie, dziękuję" (akcja zamknięcia)
  </Accordion>

  <Accordion title="Kod QR do kontynuacji na telefonie">
    * **Nagłówek**: "Kontynuuj na telefonie"
    * **Tekst**: "Zeskanuj kod QR, aby porozmawiać z naszym agentem AI na urządzeniu mobilnym."
    * **Kod QR**: Kod QR kampanii ze śledzeniem UTM
    * **Tekst**: "Lub kliknij przycisk czatu poniżej."
  </Accordion>

  <Accordion title="Ogłoszenie nowej funkcji">
    * **Obraz**: Zrzut ekranu funkcji
    * **Nagłówek**: "Nowość: Rekomendacje oparte na AI"
    * **Lista funkcji**: 3-4 kluczowe korzyści
    * **Przycisk**: "Dowiedz się więcej" (link do strony funkcji)
    * **Separator**
    * **Tekst**: Drobny druk z zastrzeżeniem
  </Accordion>
</AccordionGroup>

***

## Zakładka Ustawienia

Zakładka Ustawienia kontroluje **kiedy**, **jak często** i **komu** wyzwalacz jest wyświetlany.

### Warunki

Warunki definiują reguły, które muszą być spełnione, aby wyzwalacz się uruchomił. Możesz dodać wiele warunków i wybrać tryb logiki: **AND** (wszystkie warunki muszą być prawdziwe) lub **OR** (wystarczy dowolny warunek), aby wyzwalacz się aktywował.

| Warunek                       | Operator                                  | Opis                                                                                                                                       |
| ----------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| **Czas na stronie (sekundy)** | `>=`, `<=`, `=`                           | Uruchom po spędzeniu X sekund na bieżącej stronie. Przykład: pokaż wyskakujące okno po 30 sekundach czytania.                              |
| **Odwiedzone strony**         | `>=`, `<=`, `=`                           | Uruchom po obejrzeniu X stron w sesji. Przykład: pokaż ofertę po przeglądnięciu 3+ stron.                                                  |
| **Głębokość przewijania (%)** | `>=`, `<=`, `=`                           | Uruchom, gdy odwiedzający przewinie obok procentu strony. Przykład: pokaż CTA po 70% przewinięcia.                                         |
| **Źródło UTM**                | `=`, `contains`                           | Uruchom tylko dla odwiedzających z konkretnego źródła ruchu. Przykład: pokaż specjalną ofertę tylko dla odwiedzających z `google`.         |
| **Medium UTM**                | `=`, `contains`                           | Uruchom tylko dla konkretnego medium marketingowego. Przykład: wyzwalaj tylko dla ruchu `cpc` (płatnego).                                  |
| **Kampania UTM**              | `=`, `contains`                           | Uruchom tylko dla odwiedzających z konkretnej kampanii. Przykład: pokaż sezonowy baner tylko dla kampanii `summer-sale`.                   |
| **ID polecenia**              | `=`, `!=`                                 | Uruchom na podstawie parametru `rvl_ref`. Przykład: pokaż powitalną wiadomość od partnera dla konkretnego polecenia.                       |
| **Referrer zawiera**          | `contains`                                | Uruchom na podstawie URL strony odsyłającej. Przykład: pokaż porównanie z konkurencją dla odwiedzających ze strony konkurenta.             |
| **URL strony**                | `=`, `contains`, `starts_with`, `matches` | Uruchom tylko na konkretnych stronach. Użyj `matches` dla wzorców regex. Przykład: pokaż wyskakujące okno z cennikiem tylko na `/pricing`. |
| **Typ urządzenia**            | `=`                                       | Uruchom tylko na Komputerze, Telefonie lub Tablecie. Przykład: pokaż baner do pobrania aplikacji mobilnej tylko na telefonie.              |
| **Zdarzenie wywołane**        | `=`                                       | Uruchom po wystąpieniu konkretnego zdarzenia śledzenia. Przykład: pokaż wyskakujące okno cross-sell po zdarzeniu `add_to_cart`.            |
| **Dzień tygodnia (0=Niedz.)** | `=`, `in`                                 | Uruchom tylko w konkretne dni. Przykład: pokaż weekendowe promocje w sobotę (6) i niedzielę (0).                                           |
| **Zakres godzin \[od, do]**   | `between`                                 | Uruchom tylko w konkretnych godzinach. Przykład: pokaż "Zadzwoń do nas" tylko w godzinach pracy 9-18.                                      |

### Przykłady warunków

<Tabs>
  <Tab title="Zaangażowany czytelnik">
    Pokaż wyskakujące okno z newsletterem odwiedzającym, którzy aktywnie czytają:

    | Warunek               | Operator | Wartość   |
    | --------------------- | -------- | --------- |
    | Czas na stronie       | `>=`     | `30`      |
    | Głębokość przewijania | `>=`     | `50`      |
    | Typ urządzenia        | `=`      | `desktop` |
  </Tab>

  <Tab title="Oferta dla ruchu płatnego">
    Pokaż specjalną zniżkę dla odwiedzających z Google Ads na stronie cennika:

    | Warunek    | Operator   | Wartość    |
    | ---------- | ---------- | ---------- |
    | Źródło UTM | `=`        | `google`   |
    | Medium UTM | `=`        | `cpc`      |
    | URL strony | `contains` | `/pricing` |
  </Tab>

  <Tab title="Porzucenie koszyka">
    Pokaż przypomnienie po zdarzeniu dodania do koszyka z opóźnieniem:

    | Warunek            | Operator | Wartość       |
    | ------------------ | -------- | ------------- |
    | Zdarzenie wywołane | `=`      | `add_to_cart` |
    | Czas na stronie    | `>=`     | `60`          |
    | Odwiedzone strony  | `>=`     | `2`           |
  </Tab>

  <Tab title="Tylko godziny pracy">
    Pokaż pasek "Zadzwoń do nas" tylko w godzinach pracy w dni robocze:

    | Warunek        | Operator  | Wartość           |
    | -------------- | --------- | ----------------- |
    | Zakres godzin  | `between` | `[9, 18]`         |
    | Dzień tygodnia | `in`      | `[1, 2, 3, 4, 5]` |
    | Typ urządzenia | `=`       | `desktop`         |
  </Tab>
</Tabs>

### Częstotliwość

Kontroluje, jak często wyzwalacz jest wyświetlany temu samemu odwiedzającemu:

| Opcja                                 | Opis                                                                                                                                                                         |
| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Raz na sesję**                      | Pokaż raz podczas bieżącej sesji w karcie przeglądarki. Wyzwalacz nie pokaże się ponownie nawet po przeładowaniu strony — tylko zamknięcie karty go resetuje.                |
| **Raz dziennie**                      | Pokaż raz na dzień kalendarzowy. Odwiedzający nie zobaczy go ponownie do jutra, niezależnie od liczby sesji.                                                                 |
| **Raz na odwiedzającego (na zawsze)** | Pokaż tylko raz — na zawsze. Gdy odwiedzający zobaczył ten wyzwalacz, nigdy się nie pokaże ponownie (śledzone przez token przeglądarki). Idealne dla jednorazowych ogłoszeń. |
| **Przy każdej wizycie**               | Pokaż przy każdej sesji. Wyzwalacz uruchamia się za każdym razem, gdy warunki są spełnione, niezależnie od tego, ile razy odwiedzający go widział. Używaj oszczędnie.        |

<Tip>
  W większości przypadków **Raz na sesję** lub **Raz na odwiedzającego** to właściwy wybór. "Przy każdej wizycie" może być irytujące — używaj go tylko do kluczowych, pilnych informacji, takich jak powiadomienia o konserwacji lub pilne promocje.
</Tip>

### Harmonogram

Opcjonalnie ogranicz wyzwalacz do konkretnego zakresu dat i godzin:

| Pole            | Opis                                                                                                                  |
| --------------- | --------------------------------------------------------------------------------------------------------------------- |
| **Rozpoczęcie** | Data i godzina aktywacji wyzwalacza. Przed tym momentem wyzwalacz nie uruchomi się, nawet jeśli warunki są spełnione. |
| **Zakończenie** | Data i godzina zatrzymania wyzwalacza. Po tym momencie wyzwalacz jest automatycznie dezaktywowany.                    |

Oba pola są opcjonalne:

* **Tylko rozpoczęcie** — wyzwalacz aktywuje się w dacie rozpoczęcia i działa bezterminowo
* **Tylko zakończenie** — wyzwalacz uruchamia się natychmiast i zatrzymuje w dacie zakończenia
* **Oba** — wyzwalacz działa tylko w określonym oknie czasowym
* **Żadne** — wyzwalacz działa tak długo, jak jest włączony

**Przypadki użycia harmonogramu:**

| Scenariusz                    | Rozpoczęcie   | Zakończenie   |
| ----------------------------- | ------------- | ------------- |
| Wyskakujące okno Black Friday | 29 lis, 00:00 | 2 gru, 23:59  |
| Baner promocyjny noworoczny   | 25 gru, 00:00 | 5 sty, 23:59  |
| Ogłoszenie premiery produktu  | 15 mar, 10:00 | 22 mar, 23:59 |
| Powiadomienie o konserwacji   | —             | 1 kwi, 06:00  |

***

## Jak działają wyzwalacze

Gdy skrypt trackera ładuje się na Twojej stronie, pobiera aktywne definicje wyzwalaczy i ewaluuje je w tle:

<Steps>
  <Step title="Aktywne wyzwalacze są ładowane">
    Tracker pobiera aktywne definicje wyzwalaczy z serwera. Serwer filtruje według harmonogramu (daty rozpoczęcia/zakończenia) i statusu aktywności przed wysłaniem ich do klienta.
  </Step>

  <Step title="Częstotliwość jest sprawdzana">
    Co 2 sekundy tracker sprawdza ustawienie częstotliwości każdego wyzwalacza. Jeśli odwiedzający już widział wyzwalacz (na podstawie localStorage lub sessionStorage), wyzwalacz jest pomijany.
  </Step>

  <Step title="Warunki są ewaluowane">
    Dla wyzwalaczy, które przeszły sprawdzenie częstotliwości, tracker ewaluuje wszystkie warunki — czas na stronie, głębokość przewijania, parametry UTM, typ urządzenia, wywołane zdarzenia i inne. Warunki używają logiki AND lub OR w zależności od konfiguracji.
  </Step>

  <Step title="Wyzwalacz jest wyświetlany">
    Treść wyzwalacza (modal lub toast) jest renderowana na stronie wewnątrz Shadow DOM z skonfigurowanymi stylami i animacją. Aktywacja jest rejestrowana jako zdarzenie `trigger_shown`. Dla wyzwalaczy redirect odwiedzający jest przekierowywany na docelowy URL.
  </Step>

  <Step title="Odwiedzający wchodzi w interakcję">
    Odwiedzający może wchodzić w interakcję z wyzwalaczem — klikać przyciski, wypełniać pola, kopiować kody promocyjne, skanować kody QR lub go zamknąć. Każda interakcja jest śledzona jako osobne zdarzenie (`trigger_clicked`, `trigger_dismissed`, `trigger_promo_copied`).
  </Step>
</Steps>

<Note>
  Wyzwalacze są renderowane wewnątrz własnego kontenera **Shadow DOM**, więc ich style są w pełni izolowane od Twojej strony. Brak konfliktów CSS.
</Note>

***

## Integracja wyzwalaczy i zdarzeń

Wyzwalacze tworzą zdarzenia śledzenia automatycznie. Każda aktywacja wyzwalacza jest rejestrowana jako zdarzenie `trigger_shown` z identyfikatorem wyzwalacza i typem akcji. Możesz:

* Zobaczyć aktywność wyzwalaczy na wykresie **Aktywność wyzwalaczy** w Panelu analitycznym
* Przeglądać aktywacje wyzwalaczy w tabeli **Wydajność kampanii**
* Używać warunku `event_fired` do łączenia wyzwalaczy w łańcuchy — np. pokaż Wyzwalacz B dopiero po tym, jak Wyzwalacz A został zobaczony
* Łączyć z [Zdarzeniami niestandardowymi](/widget/events#custom-events-api) dla złożonych przepływów

<Tip>
  Użyj warunku **Zdarzenie wywołane**, aby tworzyć wieloetapowe sekwencje. Na przykład: Wyzwalacz 1 pokazuje teaser po 10 sekundach. Wyzwalacz 2 pokazuje pełną ofertę tylko wtedy, gdy odwiedzający kliknął przycisk Wyzwalacza 1 (śledzony jako zdarzenie niestandardowe).
</Tip>