Applicazioni a pagina singola e cambi di pagina

In un’applicazione a pagina singola, il browser carica la pagina una sola volta; poi il framework sostituisce i contenuti e cambia l’indirizzo tramite history.pushState. Il widget rileva questi cambiamenti autonomamente. Non deve segnalare né riavviare nulla.

Incorporamento: esattamente una volta

Inserisca il caricatore una sola volta nella struttura dell’app (index.html, layout principale, _document), non in un componente renderizzato nuovamente a ogni cambio di percorso. Un secondo incorporamento non causa problemi (il secondo caricatore non fa nulla; vedere Tag script), ma rimuovere e reinserire il tag non riavvia il widget.

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

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

Il modo più semplice per verificare se un componente ausiliario del framework trasmette gli attributi data-* allo <script> generato è l’ispettore degli elementi. Se lì manca data-rc-site-key, non parte nulla.

Come vengono rilevati i cambi di pagina

Il widget non intercetta history.pushState; si limita a osservare:

1. la Navigation API del browser (navigation.currententrychange), dove disponibile;
2. altrimenti popstate e hashchange;
3. inoltre, un timer che rileva cambi di indirizzo senza evento (ogni secondo, ogni 5 secondi con la Navigation API);
4. pageshow al ritorno dalla cache avanti/indietro.

Conta come cambio di pagina: un nuovo indirizzo (percorso o query) e percorsi hash nel formato #/… e #!/…. Non conta come cambio di pagina: un semplice salto a un’ancora (#section) e replaceState verso lo stesso indirizzo.

Che cosa viene comunicato

400 ms dopo il cambiamento (per non contare gli stati intermedi dei reindirizzamenti), il widget invia al server una trama di contesto, solo con consenso:

• url, path, title, referrer: da url e referrer vengono prima rimossi i parametri di query sensibili (come email, password, token, key, card).
• locale, tz, viewport, screen, ua_hint.
• utm_source, utm_medium, utm_campaign, gclid, msclkid, fbclid dall’indirizzo.
• nav: tipo di cambiamento: load, push, replace, reload, back, forward o traverse.

Se l’app imposta il titolo solo dopo il cambiamento, il widget invia una correzione dopo 2 secondi. Così gli operatori nel pannello vedono la pagina attuale del visitatore e l’assistente riferisce la risposta a quella pagina.

Il widget rilegge anche il testo visibile della pagina (per rispondere su quella attuale e per «Me lo mostri»): non prima di 1,2 secondi dall’ultima modifica, al massimo ogni 5 secondi, mai su pagine come account, checkout o carrello e mai dai campi dei moduli. Contrassegni le aree che l’assistente non deve leggere con data-rc-private (Tag script).

Trasmettere un contesto personalizzato per pagina

Non esiste un metodo dedicato per segnalare un cambio di pagina e non è necessario. Se vuole trasmettere dettagli aggiuntivi sulla pagina attuale, come il prodotto mostrato, usi track dopo il cambio di percorso:

// 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]);

I campi che vengono ricevuti sono elencati in Identificare i visitatori e trasmettere il contesto.

Turbo, htmx, Livewire

I framework che sostituiscono l’intero <body> rimuovono anche l’elemento del widget. Il widget si riaggancia quindi autonomamente (al massimo dieci volte al minuto); la conversazione prosegue.

Utenti autenticati nelle SPA

Se qualcuno accede senza ricaricare, chiami poi identify con un hash appena ottenuto dal server. Se cambia l’utente, il widget separa la bozza di inserimento da quella dell’utente precedente. Dettagli in Identificare i visitatori.

Testo sulla privacy nelle SPA

Se l’app inserisce l’informativa sulla privacy solo dopo il caricamento, il widget trova comunque l’elemento data-rc-privacy (osserva il documento). Vedere Integrazione della privacy.

Successivo: Sicurezza e CSP