Come verificare che lo script SeaText venga caricato correttamente in una Single-Page Application

Risposta diretta

Per verificare SeaText in una single-page application, chiama SeaText.reinit() o SeaText.update() quando cambia la route. Conferma inoltre che il tag script di SeaText compaia solo nell'HTML iniziale. Non deve essere iniettato di nuovo durante la navigazione.

Questo è il nucleo di una corretta configurazione SPA. Se il tag script è presente una sola volta e l'hook della route chiama il metodo dopo ogni cambio di route, SeaText può continuare a funzionare mentre gli utenti navigano nella tua app.

Perché l'integrazione SPA è diversa dai siti tradizionali

I siti multi-pagina caricano un nuovo documento HTML a ogni clic. Il browser trova di nuovo lo script SeaText e lo esegue da zero. Le SPA si caricano una volta e sostituiscono il contenuto nel browser. Non richiedono mai una seconda copia di quel documento HTML.

SeaText usa un attributo async sul suo tag script. Ciò significa che lo script si carica senza bloccare il rendering della pagina. SeaText memorizza anche un ID in localStorage. Quell'ID aiuta SeaText a riconoscere lo stesso visitatore tra le route.

Poiché lo script è già in esecuzione, devi indicare a SeaText quando il contenuto visibile è cambiato. Un cambio di route lato client non reimposta l'ambiente JavaScript. Il router rimuove la vecchia vista e ne renderizza una nuova. SeaText ha bisogno di un segnale per ispezionare quella nuova vista. Quel segnale è SeaText.reinit() o SeaText.update().

Se invece aggiungi il tag script a ogni route, potresti creare più copie. La vecchia copia può continuare a funzionare. La nuova copia può avviare una nuova sessione. Ciò può reimpostare varianti, traduzioni o personalizzazione. Mantieni il tag script nel file di entry statico.

Passaggi rapidi di verifica

1. Individua il punto di entry. Trova dove viene montata la tua SPA. Di solito è index.html, main.js, main.tsx o App.vue.
2. Conferma che lo snippet sia presente. Lo snippet SeaText dovrebbe comparire una volta all'interno del tag body di quel file di entry. Non inserirlo in un template di componente che viene ri-renderizzato al cambio di route.
3. Compila e servi l'app. Esegui il tuo normale comando di sviluppo come npm start, npm run serve o ng serve.
4. Ispeziona la scheda Network. Ricarica la pagina. Verifica che la richiesta dello script SeaText restituisca HTTP 200 e che la risposta sia JavaScript.
5. Controlla la scheda Console. Cerca errori che menzionano SeaText, seatext o il dominio dello script. Una console pulita significa che lo script è stato analizzato ed eseguito.
6. Attiva una funzionalità SeaText. Cambia una lingua o mostra una variante. Conferma che la funzionalità compaia sulla route corrente.
7. Naviga verso un'altra route. Usa il router della tua app per cambiare vista. Apri di nuovo la scheda Network. Lo script SeaText non dovrebbe essere richiesto una seconda volta.

Questi passaggi verificano il caricamento iniziale. Non dimostrano ancora che SeaText si reinizializzi dopo la navigazione.

Verifica dei cambi di route

Un caricamento iniziale pulito è solo metà del test. Devi anche dimostrare che SeaText reagisca quando cambia la route. Usa un listener di route o un hook del router per chiamare SeaText.reinit() dopo il rendering della nuova route.

Ecco un pattern generico. Il nome dell'evento dipenderà dal tuo router. La parte importante è la chiamata al metodo SeaText.

window.addEventListener('navigation', function () {
  if (window.SeaText && typeof window.SeaText.reinit === 'function') {
    window.SeaText.reinit();
  }
});

Sostituisci navigation con l'evento esposto dal tuo router. Se la tua integrazione usa update(), sostituisci il nome del metodo.

Risultati attesi per ogni passaggio

Usa questi controlli dopo aver aggiunto il listener:

• Apri l'app. Atteso: lo script SeaText si carica una volta nella scheda Network.
• Naviga verso una nuova route. Atteso: il tuo listener scatta e chiama SeaText.reinit() o SeaText.update() una volta.
• Osserva di nuovo la scheda Network. Atteso: nessuna nuova richiesta per il file dello script SeaText.
• Controlla la Console. Atteso: nessun errore da SeaText.
• Attiva una funzionalità SeaText. Atteso: la funzionalità si applica sulla nuova route.

Se lo script si ricarica, riporta lo snippet nel file di entry statico. Se la funzionalità non si applica, controlla che l'hook della route venga eseguito dopo gli aggiornamenti del DOM.

Hook di route specifici per framework

Ogni router ha un punto diverso in cui agganciare i cambi di route. L'obiettivo è lo stesso: dopo il rendering della nuova route, chiama SeaText.reinit() o SeaText.update().

React Router

Usa useLocation() e useEffect(). Metti l'observer all'interno del tuo componente Router.

import { useLocation } from 'react-router-dom';
import { useEffect } from 'react';

function SeaTextRouteObserver() {
  const location = useLocation();

  useEffect(() => {
    if (window.SeaText && typeof window.SeaText.reinit === 'function') {
      window.SeaText.reinit();
    }
  }, [location]);

  return null;
}

Atteso: quando il pathname cambia, l'effect viene eseguito e SeaText si reinizializza sulla nuova pagina.

Next.js App Router

Usa usePathname() in un client component. Renderizza quel componente nel tuo root layout in modo che rimanga montato.

'use client';
import { usePathname } from 'next/navigation';
import { useEffect } from 'react';

export default function SeaTextRouteObserver() {
  const pathname = usePathname();

  useEffect(() => {
    if (window.SeaText && typeof window.SeaText.reinit === 'function') {
      window.SeaText.reinit();
    }
  }, [pathname]);

  return null;
}

Atteso: ogni navigazione dell'App Router cambia pathname e attiva l'effect.

Next.js Pages Router

Usa l'hook useRouter() e l'evento routeChangeComplete. Monta l'observer in _app.js o _app.tsx.

import { useRouter } from 'next/router';
import { useEffect } from 'react';

export default function SeaTextRouteObserver() {
  const router = useRouter();

  useEffect(() => {
    const handleRouteChange = () => {
      if (window.SeaText && typeof window.SeaText.reinit === 'function') {
        window.SeaText.reinit();
      }
    };

    router.events.on('routeChangeComplete', handleRouteChange);
    return () => router.events.off('routeChangeComplete', handleRouteChange);
  }, [router]);

  return null;
}

Atteso: l'handler scatta dopo ogni cambio di route completato e chiama SeaText una volta.

Vue Router

Usa l'hook afterEach del router nel tuo file di configurazione del router.

router.afterEach(() => {
  if (window.SeaText && typeof window.SeaText.reinit === 'function') {
    window.SeaText.reinit();
  }
});

Atteso: dopo ogni navigazione, l'hook viene eseguito. Il tag script di SeaText rimane in index.html.

Angular Router

Filtra l'evento NavigationEnd in AppComponent o in un servizio root.

import { Router, NavigationEnd } from '@angular/router';
import { filter } from 'rxjs/operators';

export class AppComponent {
  constructor(private router: Router) {
    this.router.events
      .pipe(filter((event) => event instanceof NavigationEnd))
      .subscribe(() => {
        (window as any).SeaText?.reinit?.();
      });
  }
}

Atteso: SeaText si reinizializza dopo ogni navigazione Angular completata.

Se la versione installata espone update() invece di reinit(), sostituisci il nome del metodo in questi esempi. Verifica con il fornitore se non sei sicuro.

Problemi comuni e come risolverli

• Lo script si carica ma le funzionalità non compaiono. Controlla che localStorage sia accessibile. Alcune modalità privacy o iframe in sandbox lo bloccano. Conferma inoltre che l'hook della route chiami SeaText.reinit() o SeaText.update().
• Richieste dello script a ogni cambio di route. Probabilmente lo snippet si trova dentro un componente che viene rimontato. Spostalo nell'index.html statico.
• Errori cross-origin nella Console. Se la tua SPA serve contenuti da più domini, consenti il dominio dello script SeaText nella tua Content Security Policy e negli header CORS.
• 404 sulla richiesta dello script. L'URL dello snippet potrebbe essere obsoleto. Copia lo snippet più recente dalla tua dashboard SeaText.
• La re-init viene eseguita più di una volta. Aggiungi l'observer di route in un solo punto. Se lo monti in più componenti, potresti chiamare il metodo più volte.

Limitazioni e quando questo consiglio non si applica

Questa guida copre il caricamento lato client dello script e la reinizializzazione sulle route. Non convalida la logica di riscrittura AI, traduzione o A/B testing di SeaText. Quelle richiedono test funzionali separati.

I passaggi presuppongono una SPA standard con un file di entry statico. Se la tua SPA usa un'architettura a micro-frontend in cui ogni frammento inietta i propri script, la regola dello snippet unico potrebbe non valere. Consulta il supporto SeaText per quella topologia.

Se la tua app usa il server-side rendering, controlla che lo snippet non sia duplicato nell'output del server. Gli hook di route appartengono comunque al client.

Gli strumenti di test headless devono attendere l'esecuzione dello script. Un semplice caricamento della pagina potrebbe non bastare. Attendi che il metodo SeaText sia disponibile prima di verificare i risultati.

FAQ

Devo chiamare SeaText.reinit() a ogni cambio di route?

Sì, per i cambi di route lato client. Lo scambio di route modifica il DOM visibile, quindi SeaText deve ri-scansionare la pagina. Non ricaricare lo script SeaText durante la navigazione. Mantieni il tag script nell'HTML iniziale e chiama SeaText.reinit() o SeaText.update() dall'hook del router.

Quando dovrei usare SeaText.update() invece di SeaText.reinit()?

Usa il metodo fornito dalla tua integrazione. Come pattern generale, reinit() si adatta a un cambio di route completo, mentre update() si adatta a una modifica di contenuto più piccola sulla stessa pagina. Se la tua build espone un solo metodo, usa quello. Verifica con il fornitore se non sei sicuro.

Posso caricare lo script SeaText dinamicamente via JavaScript?

Non consigliato. Lo snippet è progettato per il posizionamento statico nell'HTML iniziale. L'iniezione dinamica può causare race condition, doppio caricamento o errori di Content Security Policy.

E se la mia SPA usa una Content Security Policy rigorosa?

Aggiungi il dominio dello script SeaText alla direttiva script-src. Poiché lo script comunica con gli endpoint SeaText, consenti anche connect-src. Poi ripeti i controlli su Network e Console.

Come verifico questo in una build di produzione?

Esegui npm run build e servi l'output. Apri DevTools, controlla le schede Network e Console, naviga tra le route e conferma che lo script SeaText non si ricarichi.

Ulteriori letture e fonti di confronto

Queste fonti esterne forniscono contesto aggiuntivo per valutare l'argomento. La loro inclusione non costituisce un'approvazione.

• Load Testing Single-Page Applications - LoadView
• Test a single page application - SPA
• Load Testing a Single-Page Application (SPA) - LoadForge Docs

Scopri di più

Visita il sito web per maggiori informazioni.