Aplikacje jednostronicowe i zmiany stron

W aplikacji jednostronicowej przeglądarka ładuje stronę tylko raz; potem twój framework podmienia treści i zmienia adres przez history.pushState. Widżet rozpoznaje te zmiany sam. Nie musisz niczego zgłaszać ani niczego uruchamiać ponownie.

Osadzenie: dokładnie raz

Wstaw loader raz w szkielet swojej aplikacji (index.html, główny layout, _document), a nie w komponent, który jest renderowany od nowa przy każdej zmianie trasy. Drugie osadzenie jest wprawdzie nieszkodliwe (drugi loader nic nie robi, zobacz Tag script), ale usunięcie i ponowne wstawienie tagu nie uruchamia widżetu od nowa.

// Next.js (App Router), app/layout.tsx
import Script from 'next/script';

export default function RootLayout({ children }) {
  return (
    <html lang="de">
      <body>
        {children}
        <Script src="https://cdn.reactive.chat/loader.js"
                data-rc-site-key="SITE_KEY"
                strategy="afterInteractive" />
      </body>
    </html>
  );
}

Czy pomocnik frameworku przekazuje atrybuty data-* do wygenerowanego <script>, najłatwiej sprawdzisz w inspektorze elementów. Jeśli brakuje tam data-rc-site-key, nic się nie uruchomi.

Jak rozpoznawane są zmiany stron

Widżet nie ingeruje w history.pushState, tylko obserwuje:

1. Navigation API przeglądarki (navigation.currententrychange), jeśli jest dostępne;
2. w przeciwnym razie popstate i hashchange;
3. dodatkowo cykliczne sprawdzanie, które znajduje zmiany adresu bez zdarzenia (co sekundę, z Navigation API co 5 sekund);
4. pageshow przy powrocie z pamięci back/forward cache.

Za zmianę strony uznawane są: nowy adres (ścieżka lub query) i trasy hash w formie #/… i #!/…. Za zmianę strony nie są uznawane: sam skok do kotwicy (#abschnitt) i replaceState na ten sam adres.

Co jest przy tym zgłaszane

400 ms po zmianie (żeby stany pośrednie przekierowań się nie liczyły) widżet wysyła do serwera ramkę kontekstu – tylko za zgodą:

• url, path, title, referrer – url i referrer są wcześniej czyszczone z wrażliwych parametrów query (np. email, password, token, key, card).
• locale, tz, viewport, screen, ua_hint.
• utm_source, utm_medium, utm_campaign, gclid, msclkid, fbclid z adresu.
• nav – rodzaj zmiany: load, push, replace, reload, back, forward albo traverse.

Jeśli twoja aplikacja ustawia tytuł dopiero po zmianie, widżet po 2 sekundach wysyła poprawkę. Dzięki temu agenci widzą w panelu, na której stronie jest właśnie odwiedzający, a asystent odnosi swoją odpowiedź do tej strony.

Widoczny tekst strony widżet również wczytuje od nowa (do odpowiedzi o bieżącej stronie i do „Pokaż mi”) – najwcześniej 1,2 sekundy po ostatniej zmianie, najwyżej co 5 sekund, nigdy na stronach takich jak konto, checkout czy koszyk i nigdy z pól formularzy. Obszary, których asystent nie powinien czytać, oznaczasz data-rc-private (Tag script).

Własny kontekst dla każdej strony

Osobnej metody do zgłaszania zmiany strony nie ma i nie jest potrzebna. Jeśli chcesz przekazać dodatkowe informacje o bieżącej stronie, np. wyświetlany produkt, użyj track po zmianie trasy:

// React Router
const location = useLocation();
useEffect(() => {
  if (produkt) {
    window.ReactiveChat('track', 'produktseite', {
      page_type: 'product', product_id: produkt.sku, price: produkt.preis,
      currency: 'EUR', in_stock: produkt.lieferbar
    });
  }
}, [location.pathname, produkt]);

Jakie pola docierają, opisuje Identyfikacja odwiedzających i przekazywanie kontekstu.

Turbo, htmx, Livewire

Frameworki, które podmieniają cały <body>, usuwają przy tym także element widżetu. Widżet sam się wtedy ponownie dołącza (najwyżej dziesięć razy na minutę); rozmowa trwa dalej.

Zalogowani użytkownicy w SPA

Jeśli ktoś zaloguje się bez przeładowania strony, wywołaj potem identify z hashem świeżo pobranym z serwera. Gdy użytkownik się zmienia, widżet oddziela wersję roboczą wiadomości od poprzedniego użytkownika. Szczegóły w Identyfikacji odwiedzających.

Tekst o ochronie danych w SPA

Jeśli twoja aplikacja wstawia politykę prywatności dopiero po załadowaniu, widżet i tak znajdzie element data-rc-privacy (obserwuje dokument). Zobacz Ochrona danych.

Dalej: Bezpieczeństwo i CSP