getting-started

Skrypt śledzący Flowsery Analytics obsługuje kilka atrybutów danych do dostosowania śledzenia. Ten przewodnik opisuje wszystkie dostępne opcje konfiguracji.

Pierwszy raz z Flowsery Analytics?

Na początek warto skorzystać z przewodnika instalacji, aby dodać skrypt śledzący do witryny.

Atrybuty skryptu

ID witryny: Data-Fl-Website-ID (wymagane)

Unikalny identyfikator witryny z Flowsery Analytics. To jedyny wymagany atrybut.

Podstawowy tag skryptu
<script
  defer
  data-fl-website-id="flid_******"
  src="https://cdn.flowsery.com/main.js"
></script>

Domena: Data-Domain (opcjonalnie)

Określa zakres cookie dla identyfikatorów odwiedzającego i sesji. Domyślnie location.hostname, więc witryny z jedną domeną mogą go pominąć. Przydaje się, gdy jedno cookie odwiedzającego ma działać w subdomenach: na przykład data-domain="example.com" pozwala example.com, app.example.com i blog.example.com współdzielić ten sam identyfikator odwiedzającego. Nie działa w trybie bez cookie.

Śledzenie subdomen

Flowsery Analytics domyślnie śledzi wszystkie subdomeny domeny głównej. data-domain określa zakres cookie, a nie to, które hosty są śledzone. Na przykład przy domenie głównej example.com Flowsery Analytics działa też na app.example.com, blog.example.com, shop.example.com itd.

Dozwolone hosty: Data-Allowed-Hostnames (opcjonalnie)

Lista dodatkowych domen rozdzielonych przecinkami do śledzenia między domenami.

  • Domyślnie: puste (bez śledzenia między domenami)
  • Przykład: app.io,shop.example.com
  • Zastosowanie: śledzenie użytkowników w różnych domenach głównych
Śledzenie między domenami
<script
  defer
  data-fl-website-id="flid_******"
  data-allowed-hostnames="app.io,myapp.org"
  src="https://cdn.flowsery.com/main.js"
></script>

Adres API: Data-API (opcjonalnie)

Własny punkt końcowy API do wysyłania zdarzeń. Przyjmuje pełny adres URL lub ścieżkę względną.

  • Przykład: https://api.example.com/events lub /custom-events
  • Zastosowanie: własne punkty końcowe API, proxy analityki podmiotów trzecich lub zaawansowane konfiguracje proxy

Ścieżka względna jest dołączana do domeny witryny.

Automatyczne wykrywanie proxy

Flowsery Analytics automatycznie wykrywa konfiguracje z proxy. Tej opcji należy użyć tylko przy własnej ścieżce punktu końcowego lub wysyłaniu zdarzeń na zupełnie inny serwer.

Zezwolenie na localhost: Data-Local (opcjonalnie)

Włącza śledzenie na localhost na potrzeby programowania i testów. Przyjmuje "true" lub "false". Domyślnie: false.

Zezwolenie na protokół file: Data-Allow-File-Protocol (opcjonalnie)

Włącza śledzenie przy otwieraniu plików HTML bezpośrednio w przeglądarce (protokół file://). Przyjmuje "true" lub "false". Domyślnie: false.

Tryb debugowania: Data-Debug (opcjonalnie)

Włącza tryb debugowania, który pozwala na śledzenie w ramkach iframe. Przyjmuje "true" lub "false". Domyślnie: false. Domyślnie Flowsery Analytics nie śledzi w ramkach iframe, aby uniknąć duplikatów.

Wyłączenie konsoli: Data-Disable-Console (opcjonalnie)

Wyłącza wszystkie logi skryptu Flowsery Analytics w konsoli. Przyjmuje "true" lub "false". Domyślnie: false.

Wyłączenie płatności: Data-Disable-Payments (opcjonalnie)

Wyłącza automatyczne śledzenie płatności i atrybucję przychodów z parametrów URL (Stripe session_id, LemonSqueezy order_id, Polar checkout_id). Przyjmuje "true" lub "false". Domyślnie: false.

  • Zastosowanie: atrybucja przychodów po stronie serwera, aby uniknąć zduplikowanych zdarzeń płatności

Ręczne śledzenie płatności

Ręczne wywołania window.flowsery("payment", { email }) nadal działają po włączeniu tej opcji. Wyłączone jest tylko automatyczne wykrywanie z parametrów URL.

Atrybuty elementów HTML

Te atrybuty dodaje się do elementów HTML na stronie, aby włączyć automatyczne śledzenie.

Śledzenie celów: Data-Fs-Goal (opcjonalnie)

Śledzi kliknięcia dowolnego elementu jako własny cel. Tylko małe litery, cyfry, podkreślenia i myślniki. Maksymalnie 64 znaki.

<button data-fs-goal="add_to_cart">Add to Cart</button>

Parametry celu: Data-Fs-Goal-* (opcjonalnie)

Dodaje własne parametry do zdarzeń celu. Nazwa parametru pochodzi od nazwy atrybutu (kebab-case zamieniany na snake_case). Maksymalnie 10 parametrów na zdarzenie. Nazwy parametrów: do 64 znaków. Wartości: do 255 znaków.

Cel z parametrami
<button
  data-fs-goal="product_added"
  data-fs-goal-product-id="prod_123"
  data-fs-goal-product-name="Premium Plan"
  data-fs-goal-price="49">
  Add to Cart
</button>

Śledzenie przewijania: Data-Fs-Scroll (opcjonalnie)

Automatycznie rejestruje moment, gdy element staje się widoczny podczas przewijania. Domyślny próg: 50% widocznego elementu. Te same zasady nazewnictwa co dla data-fs-goal.

<section data-fs-scroll="viewed_pricing">
  <h2>Pricing</h2>
</section>

Próg przewijania: Data-Fs-Scroll-Threshold (opcjonalnie)

Dostosowuje próg widoczności dla śledzenia przewijania. Liczba dziesiętna od 0 do 1. Domyślnie: 0.5 (widoczne 50% elementu). Typowe wartości: 0.1 (10%), 0.5 (50%), 0.9 (90%), 1.0 (100%).

Opóźnienie przewijania: Data-Fs-Scroll-Delay (opcjonalnie)

Dodaje opóźnienie w milisekundach przed zarejestrowaniem zdarzenia przewijania. Domyślnie: 0 (bez opóźnienia).

Śledzenie przewijania z progiem i opóźnieniem
<section
  data-fs-scroll="read_testimonials"
  data-fs-scroll-threshold="0.7"
  data-fs-scroll-delay="3000">
  <!-- Tracks only if element stays visible for 3 seconds -->
</section>

Parametry przewijania: Data-Fs-Scroll-*

Dodaje własne parametry do zdarzeń przewijania, podobnie jak data-fs-goal-*.

Typowe przykłady konfiguracji

Środowisko programistyczne

<script
  defer
  data-fl-website-id="flid_******"
  data-local="true"
  src="https://cdn.flowsery.com/main.js"
></script>

Produkcja z proxy

<script
  defer
  data-fl-website-id="flid_******"
  src="/js/main.js"
></script>

Flowsery Analytics automatycznie wykrywa konfiguracje z proxy. data-api nie jest potrzebne, jeśli proxy obsługuje zarówno /js/main.js, jak i /api/track.

Śledzenie między domenami

<script
  defer
  data-fl-website-id="flid_******"
  data-domain="example.com"
  data-allowed-hostnames="app.io,shop.example.net"
  src="https://cdn.flowsery.com/main.js"
></script>

We wszystkich śledzonych domenach należy użyć tej samej konfiguracji.

Śledzenie nawigacji opartej na hashu

Dla aplikacji jednostronicowych z routingiem przez hash:

<script
  defer
  data-fl-website-id="flid_******"
  src="https://cdn.flowsery.com/main.hash.js"
></script>

Podsumowanie zasad walidacji

Nazwy celów i zdarzeń

  • Znaki: małe litery, cyfry, podkreślenia (_), myślniki (-)
  • Długość: maksymalnie 64 znaki

Nazwy własnych parametrów

  • Znaki: małe litery, cyfry, podkreślenia (_), myślniki (-)
  • Długość: maksymalnie 64 znaki
  • Konwersja: atrybuty kebab-case są automatycznie zamieniane na snake_case

Wartości własnych parametrów

  • Długość: maksymalnie 255 znaków
  • HTML/XSS: niebezpieczne znaki są automatycznie oczyszczane
  • Limit: maksymalnie 10 własnych parametrów na zdarzenie

Próg przewijania

Liczba dziesiętna z zakresu od 0.0 do 1.0, domyślnie 0.5.

Opóźnienie przewijania

Liczba całkowita (milisekundy), 0 lub więcej, domyślnie 0.

Rozwiązywanie problemów

Śledzenie nie działa na localhost

Aby włączyć śledzenie lokalne, należy dodać data-local="true".

Własne cele się nie uruchamiają

Należy sprawdzić, czy nazwa celu spełnia zasady walidacji: tylko małe litery, bez spacji i znaków specjalnych (poza _ i -), maksymalnie 64 znaki.

Śledzenie między domenami nie działa

Należy sprawdzić: ten sam data-fl-website-id we wszystkich domenach, wszystkie dodatkowe domeny w data-allowed-hostnames oraz czy użytkownicy klikają linki między domenami.

Śledzenie przewijania się nie uruchamia

Typowe przyczyny: element zbyt krótko w obszarze widoku, zbyt wysoki próg, brak obsługi IntersectionObserver.