Nagrywanie sesji za pomocą skryptu Flowsery
Nagrywanie sesji pozwala odtworzyć, co prawdziwi odwiedzający robili w twojej witrynie: ruchy myszy, kliknięcia, wypełnianie formularzy i przejścia między stronami. Wystarczy dodać do HTML niewielki skrypt. Rejestrator to pakiet JS oddzielny od głównego skryptu analitycznego, więc ładuje się tylko wtedy, gdy go włączysz.
Rejestrator jest zbudowany na rrweb i wysyła zdarzenia mutacji DOM do Flowsery w postaci fragmentów skompresowanych gzipem. Pierwszy fragment to pełna migawka, a kolejne są przyrostowe.
Wymagania wstępne
- Nagrywanie musi być włączone dla witryny w panelu Flowsery (
Ustawienia witryny → Ogólne → Nagrywanie sesji). Gdy jest wyłączone, serwer odrzuca żądaniarecording_start. - Główny skrypt analityczny (
/js/main.js) musi już działać. Nagrywanie korzysta z tego samegodata-fl-website-id, tych samych plików cookie odwiedzającego i sesji oraz tego samego endpointu/events.
Szybki start (CDN)
Dodaj tag script zaraz po głównym skrypcie analitycznym:
<script defer data-fl-website-id="flid_******" src="https://cdn.flowsery.com/main.js"></script>
<script defer data-fl-website-id="flid_******" src="https://cdn.flowsery.com/recording.js"></script>Rejestrator stosuje te same warunki co główny skrypt (wykrywanie botów, localhost, iframe, file://, samowykluczenie) i bezpiecznie kończy działanie, gdy któryś z nich zachodzi.
Wolisz jeden tag? Dodaj do głównego skryptu atrybut data-recording, a Flowsery samo wstawi rejestrator, bez drugiego <script>:
<script defer data-fl-website-id="flid_******" data-recording src="https://cdn.flowsery.com/main.js"></script>Włączanie przez npm SDK
Jeśli inicjujesz Flowsery przez npm SDK, włącz nagrywanie jedną flagą zamiast tagu script:
import { initFlowsery } from 'flowsery';
await initFlowsery({
websiteId: 'flid_******',
recording: true,
});SDK pobiera pakiet rejestratora z CDN Flowsery przy pierwszej inicjalizacji, więc rrweb nigdy nie trafia do pakietu twojej aplikacji. Zdarzenia śledzenia nadal przechodzą przez apiBase, jeśli jest ustawiony. Aby nagrywać tylko część sesji, dodaj recordingSampleRate, a aby analizować przez AI tylko część z nich, dodaj aiSampleRate (oba 0–100, domyślnie 100): zobacz Próbkowanie. Wszystko, co opisano poniżej, czyli wymaganie w panelu, tryby prywatności, warunki i obsługa przeglądarek, obowiązuje tak samo.
Konfiguracja z odwrotnym proxy (zalecana w produkcji)
Blokery reklam i rozszerzenia chroniące przed śledzeniem blokują skrypty zewnętrzne oraz bezpośrednio analytics.flowsery.com. Skierowanie przez własną domenę zarówno skryptu, jak i endpointu zdarzeń rozwiązuje ten problem, a adresy IP odwiedzających i dokładność danych pozostają bez zmian.
Rejestrator sam wyznacza bazowy adres API na podstawie własnego <script src>, tak samo jak główny skrypt. Dopóki pakiet nagrywania jest serwowany pod /js/recording.js w twojej domenie, dodatkowa konfiguracja nie jest potrzebna.
Next.js
// next.config.js
async rewrites() {
return [
{ source: '/js/main.js', destination: 'https://cdn.flowsery.com/main.js' },
{ source: '/js/recording.js', destination: 'https://cdn.flowsery.com/recording.js' },
{ source: '/api/track', destination: 'https://analytics.flowsery.com/analytics/events' },
];
}<script defer data-fl-website-id="flid_******" src="/js/main.js"></script>
<script defer data-fl-website-id="flid_******" src="/js/recording.js"></script>Inne proxy
Ten sam schemat działa z każdym odwrotnym proxy. Zmapuj wszystkie trzy ścieżki:
| Ścieżka publiczna | Źródło |
|---|---|
/js/main.js | https://cdn.flowsery.com/main.js |
/js/recording.js | https://cdn.flowsery.com/recording.js |
/api/track | https://analytics.flowsery.com/analytics/events |
Przewodniki proxy dla konkretnych frameworków (Astro, Caddy, Express, FastAPI, Nginx, PHP, Vue itd.) znajdziesz w przewodnikach proxy w centrum pomocy.
Konfiguracja
Rejestrator odczytuje konfigurację z tych samych atrybutów tagu <script> co główny skrypt. Większość opcji dziedziczy automatycznie, a poniższe dotyczą tylko nagrywania.
data-rrweb-src (opcjonalny)
Zastępuje URL, z którego rejestrator ładuje rrweb. Domyślnie https://cdn.jsdelivr.net/npm/rrweb@2/dist/rrweb.min.js.
<script defer data-fl-website-id="flid_******" data-rrweb-src="/js/rrweb.min.js" src="/js/recording.js"></script>Przydaje się, gdy CSP zabrania cdn.jsdelivr.net albo gdy chcesz hostować rrweb samodzielnie, aby uniknąć żądań do podmiotów zewnętrznych.
data-recording-sample (opcjonalny)
Nagrywa tylko określony procent sesji. Przyjmuje liczbę całkowitą 0–100.
- Domyślnie:
100: nagrywanie każdej sesji. Aby nagrywać wszystko, pomiń ten atrybut. - Przykład:
data-recording-sample="30"nagrywa ok. 30% sesji.
<script defer data-fl-website-id="flid_******" data-recording-sample="30" src="https://cdn.flowsery.com/recording.js"></script>Decyzja jest deterministyczna dla każdej sesji: odwiedzający jest nagrywany albo pomijany konsekwentnie przez całą sesję, także po przeładowaniach i przejściach między stronami, więc nie powstają nagrania urwane w połowie wizyty. Sesje spoza próby w ogóle nie pobierają rejestratora. O łączeniu tej opcji z próbkowaniem analizy AI przeczytasz w sekcji Próbkowanie.
data-ai-sample (opcjonalny)
Spośród nagrywanych sesji wysyła do analizy AI tylko określony procent. Przyjmuje liczbę całkowitą 0–100.
- Domyślnie:
100: analiza każdej nagranej sesji. - Przykład:
data-ai-sample="50"wysyła do analizy AI ok. 50% nagranych sesji.
<script defer data-fl-website-id="flid_******" data-recording-sample="30" data-ai-sample="50" src="https://cdn.flowsery.com/recording.js"></script>Rejestrator przekazuje ten współczynnik do Flowsery podczas uzgadniania recording_start. Serwer zapisuje go przy nagraniu i stosuje w chwili dodania analizy do kolejki (przeglądarki dawno już wtedy nie ma). Zobacz Próbkowanie.
Poziomy prywatności
Tryb prywatności ustala serwer i przekazuje go rejestratorowi w odpowiedzi na recording_start. Obecnie każda witryna otrzymuje tryb balanced, a panel nie ma dla niego ustawienia. Dostępne tryby:
- balanced (domyślny): maskuje pola hasła, e-maila i telefonu. Pozostałe pola i tekst są nagrywane bez zmian.
- strict: maskuje wszystkie pola i całą treść tekstową, blokuje
<video>,<audio>i<canvas>oraz wyłącza nagrywanie canvas. - relaxed: bez maskowania. Używaj tylko w aplikacjach wewnętrznych, w których kontrolujesz wprowadzane dane.
Aby uzyskać inny tryb na danej stronie, trzeba by przetwarzać nagrania po stronie serwera; skrypt stosuje to, co zwróci serwer.
Próbkowanie
W witrynach o dużym ruchu rzadko trzeba nagrywać każdą wizytę. Flowsery próbkuje w dwóch niezależnych etapach, oba konfigurowane w skrypcie (lub npm SDK), więc w panelu nie trzeba niczego ustawiać:
- Współczynnik próbkowania nagrań: odsetek sesji, które są w ogóle nagrywane. Ustawiasz go przez
data-recording-sample(lub opcję SDKrecordingSampleRate),0–100, domyślnie100. Decyduje przeglądarka, więc sesje spoza próby nigdy nie pobierają rejestratora. - Współczynnik próbkowania analizy AI: odsetek sesji już nagranych, które trafiają do analizy AI. Ustawiasz go przez
data-ai-sample(lub opcję SDKaiSampleRate),0–100, domyślnie100. Rejestrator przekazuje go do Flowsery podczas uzgadnianiarecording_start, a serwer stosuje go dla każdego nagrania, ponieważ analiza AI odbywa się po zamknięciu strony.
Oba współczynniki się mnożą. Przy 30% nagrań i 50% analizy AI nagrywanych jest ok. 30% sesji, a ok. 15% (30% × 50%) otrzymuje ocenę AI. Pozostałe można w pełni odtworzyć, tyle że bez analizy AI.
Próbkowanie jest deterministyczne, a nie losowe: decyzja o nagrywaniu zależy od sesji, więc odwiedzający jest nagrywany (lub nie) konsekwentnie przez całą sesję i po przeładowaniach. Domyślne wartości 100 zachowują pierwotne działanie, czyli nagrywanie i analizę wszystkiego, więc nic się nie zmieni, dopóki nie obniżysz współczynnika.
Jak to działa
- Skrypt odczytuje
data-fl-website-idz własnego tagu oraz identyfikatory UID odwiedzającego i sesji z plików cookie ustawionych przez główny skrypt (_fs_vid,_fs_sid). - Wysyła POST
recording_startdo/events. Jeśli serwer odrzuci żądanie (nagrywanie wyłączone, przekroczony limit itp.), skrypt się zatrzymuje. - Po akceptacji ładuje rrweb i zaczyna zapisywać zdarzenia w buforze w pamięci.
- Co 15 sekund (lub wcześniej, jeśli bufor przekroczy 500 zdarzeń / 256 KB) bufor jest zamieniany na JSON Lines → kompresowany gzipem → kodowany w base64 → wysyłany przez POST jako
recording_chunk. Serwer przechowuje fragmenty w R2 i agreguje metryki (liczby zdarzeń, flagi kliknięć/wprowadzania/błędów/rage clicków, czas trwania) w wierszu nagrania. - Przy
pagehide/beforeunloadostatni fragment jest wysyłany zfinalize: trueprzez kanał odporny na zamknięcie strony:navigator.sendBeaconw konfiguracjach z proxy w tym samym originie albo żądaniefetchz keepalive w konfiguracjach bezpośrednich (cross-origin), dzięki czemu ostatni fragment nie przepada przy zamykaniu strony. Serwer zmienia status nagrania naready, a nagranie pojawia się na liście nagrań w panelu.
Obsługa przeglądarek
- Chrome/Edge 80+, Firefox 113+, Safari 16.4+: pełna obsługa, kompresja gzip przez
CompressionStream. - Starsze Safari / Firefox: rejestrator przechodzi na fragmenty bez gzipa. Są one przechowywane, ale odtwarzanie w panelu wymaga kodowania gzip, więc nagrań ze starszych przeglądarek nie da się odtworzyć, dopóki dekoder ich nie obsłuży.
- Tryb prywatny Safari:
sessionStoragedziała osobno dla każdej karty, więc przy każdym otwarciu karty powstaje nowy UID nagrania. Poza tym wszystko działa. - Tryb bez plików cookie (
data-cookielessw głównym skrypcie): nagrywanie jest wyłączone, ponieważ nie ma UID odwiedzającego ani sesji, do których można je przypisać.
Koszty i wydajność
- Sieć: typowa sesja to 50–500 KB po kompresji, czyli znacznie mniej niż wideo. Fragmenty są wysyłane co 15 s przez połączenie
keepalivelub przez Beacon API przy zamykaniu strony. - CPU: rrweb uruchamia bezczynny MutationObserver: obciążenie jest mierzalne, ale na typowych stronach wynosi znacznie poniżej 1% CPU. Odciążanie przez
requestIdleCallbackjest wbudowane w rrweb 2.x. - Prywatność: rejestrator respektuje
Do Not Tracktylko po ustawieniudata-respect-dnt="true". W przeciwnym razie nagrywa wszystkich odwiedzających, którzy dotrą dorecording_start.
Wyłączanie nagrywania
Masz trzy możliwości:
- Globalnie: wyłącz nagrywanie w ustawieniach witryny. Serwer odrzuci
recording_start, a skrypt się zatrzyma. - Dla strony: nie dodawaj tagu
<script src="/js/recording.js">. - Dla odwiedzającego: ustaw
localStorage.setItem('flowsery_ignore', 'true'), czyli tę samą rezygnację, której używa główny skrypt.
Rozwiązywanie problemów
Karta Nagrania jest pusta
- Sprawdź, czy nagrywanie jest włączone dla witryny.
- Otwórz DevTools → Network. Powinno być widać udany POST
recording_start, a po nim cykliczne POST-yrecording_chunk. - Sprawdź odpowiedź na
recording_start: przyaccepted: falseskrypt się zatrzymuje, a odpowiedź podaje też przyczynę (przekroczony limit, wyłączone nagrywanie).
"Nagranie jest za krótkie do odtworzenia"
Nagranie istnieje, ale ma mniej niż 2 zdarzenia. Typowe przyczyny:
- Odwiedzający zamknął kartę, zanim wysłano pierwszy fragment.
- Bloker reklam uniemożliwił załadowanie rrweb. Sprawdź w konsoli błędy CSP lub sieci.
- Zabrakło
CompressionStream, a kodowanie zastępcze zapisało fragment, którego odtwarzacz w panelu nie potrafi jeszcze zdekodować.
Nagrywanie się ładuje, ale nie działa obejście przez odwrotne proxy
Upewnij się, że skrypt jest serwowany dokładnie z /js/recording.js. Wyrażenie regularne automatycznego wykrywania dopasowuje script.js, main.js i recording.js (z opcjonalnym sufiksem .hash.js), a inne ścieżki kierują na wpisany na stałe host analityczny. Jeśli musisz serwować skrypt z innej ścieżki, ustaw jawnie data-api="https://yourdomain.com/api".