Come verificare il caricamento dello script SeaText dopo una riprogettazione o una migrazione

Checklist di verifica rapida

Apri il sito in un browser, avvia gli Strumenti per sviluppatori (F12) e segui questi cinque passaggi in ordine. Ogni passaggio rileva una diversa modalità di errore, così da non fare affidamento su un unico segnale.

1. Conferma che lo snippet esista nell'HTML fornito. Visualizza il sorgente della pagina (non il pannello Elementi) e cerca seatext o il tuo ID progetto. Se il tag manca, la pipeline di distribuzione lo ha rimosso.
2. Controlla la scheda Console per eventuali errori. Cerca messaggi rossi che fanno riferimento a seatext, SEATEXTCODEINTEGRATION o script bloccati. Le violazioni della Content Security Policy e gli errori cross-origin appaiono qui per primi.
3. Verifica che la richiesta di rete venga completata. Passa alla scheda Rete (Network), filtra per "JS" o "Script", ricarica e conferma una risposta 200 per il caricatore SeaText. Un errore 404 o 403 indica che il percorso CDN o l'ID progetto sono cambiati.
4. Ispeziona il localStorage per l'ID SeaText. Nella scheda Applicazione (o Archiviazione), espandi Local Storage, seleziona la tua origine e cerca una chiave contenente seatext. L'assenza significa che lo script non è mai stato eseguito o che il localStorage è bloccato.
5. Convalida il comportamento visibile. Attiva una traduzione, una variante di personalizzazione o un evento di rilevamento bot e conferma che il DOM si aggiorni. Usa la modalità anteprima della dashboard di SeaText o aggiungi ?seatext_preview=1 per forzare una variante.

Perché la verifica post-migrazione è importante

Una riprogettazione spesso riscrive i punti di inserimento in head o body, passa da HTML renderizzato lato server a un framework SPA o aggiunge una nuova Content Security Policy. Ognuno di questi cambiamenti può eliminare silenziosamente il tag dello script asincrono, bloccare il dominio CDN o impedire l'accesso al localStorage. Poiché SeaText riscrive titoli, offerte e traduzioni in fase di esecuzione, uno script mancante riporta ogni pagina alla lingua e all'offerta base, facendo perdere l'incremento di conversioni e le prove di rimborso bot fornite dalla piattaforma.

Prerequisiti prima di iniziare

• Accesso all'ambiente di staging che rispecchia la pipeline di build di produzione.
• Familiarità con gli Strumenti per sviluppatori del browser (schede Console, Rete, Applicazione).
• ID progetto SeaText e hostname CDN previsto dalla guida all'integrazione.
• Autorizzazione a modificare le intestazioni CSP o le regole proxy se lo script viene bloccato.
• Un URL di test che utilizzi traduzione, personalizzazione o rilevamento bot in modo da poter osservare la modifica del DOM.

Verifica passo dopo passo nello staging

1. Presenza dello snippet nell'output di build

Esegui la build di produzione localmente (npm run build o equivalente) e apri il file index.html generato. Cerca lo snippet esatto fornito da SeaText. Nei progetti React, Vue o Angular, lo snippet appartiene a public/index.html o al template radice del framework. Se la tua CI/CD utilizza il templating HTML, conferma che la variabile che inietta lo snippet venga risolta correttamente.

2. Ispezione di Console e Rete

Distribuisci nello staging, apri l'URL e premi F12. Ricarica con la scheda Rete aperta. Il caricatore SeaText dovrebbe apparire come una richiesta di script con attributo async. Clicca sulla richiesta; la scheda Risposta deve restituire JavaScript, non una pagina di errore HTML. Nella Console, filtra per "seatext": non dovrebbero esserci errori. Una violazione CSP appare come "Refused to load the script" con la direttiva che l'ha bloccata.

3. Conferma di scrittura nel localStorage

Dopo l'esecuzione dello script, apri Applicazione → Local Storage → la tua origine. Dovresti vedere una chiave come seatext_visitor_id o simile. Se la chiave manca, controlla se il sito viene eseguito in un iframe sandbox, utilizza una policy dei cookie restrittiva o serve pagine da più sottodomini senza archiviazione condivisa.

4. Test funzionale (smoke test)

Scegli una pagina che utilizza la traduzione o l'agente Google Ads. Aggiungi ?seatext_preview=1 (o usa il link di anteprima della dashboard) e verifica che titoli, pulsanti o blocchi di prodotto cambino. Per il rilevamento bot, visita la pagina con un user-agent di test noto o con lo strumento di test di SeaText e conferma che la dashboard registri una sessione.

Controlli per la messa online in produzione

Ripeti la stessa checklist di cinque passaggi immediatamente dopo il passaggio del DNS. La propagazione CDN, la memorizzazione nella cache edge o una variabile d'ambiente mancante possono far sì che la produzione si comporti diversamente dallo staging. Pianifica una finestra di 15 minuti dopo il lancio per eseguire i controlli mentre il traffico è basso. Se utilizzi feature flag, abilita SeaText inizialmente per una piccola percentuale di utenti e monitora la dashboard per gli eventi in tempo reale.

Modelli di errore comuni e soluzioni

Sintomo	Causa probabile	Soluzione
Snippet assente nel sorgente pagina	La pipeline di build ha rimosso il passaggio di iniezione	Aggiungi un'asserzione post-build che cerchi l'ID progetto
La console mostra errore CSP	La nuova intestazione CSP manca del dominio CDN di SeaText	Aggiungi script-src https://cdn.seatext.com (o la tua CDN) alla policy
La richiesta di rete restituisce 404	L'ID progetto è cambiato o il percorso CDN è stato aggiornato	Aggiorna lo snippet con l'ID progetto corrente dalla dashboard
Chiave localStorage mancante	Archiviazione di terze parti bloccata o iframe cross-origin	Assicurati che lo script venga eseguito in un contesto di prima parte; consenti l'archiviazione nell'iframe allow-scripts allow-same-origin
Non appaiono traduzioni o varianti	Script caricato ma ambito AI non configurato	Verifica che le impostazioni dell'ambito AI nella dashboard corrispondano alla nuova struttura del sito

Test di regressione automatizzato da aggiungere alla CI

Aggiungi un passaggio di browser headless (Playwright, Cypress o Puppeteer) che carichi il file index.html compilato, attenda la richiesta di rete di SeaText, asserisca che localStorage.getItem('seatext_visitor_id') esista e verifichi che un attributo dati noto (es. data-seatext-variant) appaia su un elemento target. Fai fallire la build se un'asserzione fallisce. Questo rileva le regressioni prima che raggiungano lo staging.

Fatti chiave

Elemento	Dettaglio
Modalità di caricamento script	Tag script asincrono con attributo async
Requisito di archiviazione	Scrive un ID visitatore in localStorage; richiesto accesso di prima parte
Nota cross-origin	Domini multipli necessitano di CSP compatibile e archiviazione condivisa o proxy
Punto di integrazione SPA	Inserisci lo snippet in index.html o nel file di mount del framework
Segnali di verifica	Console pulita, Rete 200, chiave localStorage presente, variante DOM visibile
Attivazione anteprima	Aggiungi ?seatext_preview=1 o usa il link di anteprima della dashboard

Limitazioni

Questa checklist copre solo il caricamento lato client. Non verifica i percorsi di rendering lato server, le riscritture edge-worker o la personalizzazione a livello di API che SeaText potrebbe introdurre in versioni future. Se il tuo stack sposta il rendering sull'edge, aggiungi un controllo dei log edge corrispondente. I passaggi presuppongono inoltre che tu controlli la distribuzione HTML; se una piattaforma di terze parti inietta lo snippet, coordina il loro ciclo di rilascio.

FAQ

Come faccio a sapere quale dominio CDN consentire nella CSP?

Apri la scheda Rete su una pagina funzionante, clicca sulla richiesta dello script SeaText e copia l'hostname dall'URL della richiesta. Quella è l'origine esatta da inserire nella whitelist.

Posso verificare lo script senza gli Strumenti per sviluppatori del browser?

Sì. Esegui un monitor sintetico (es. Datadog, Pingdom o uno script Playwright personalizzato) che asserisca che l'URL dello script restituisca 200 e che il corpo della risposta contenga SEATEXTCODEINTEGRATION.

Cosa succede se il sito utilizza una CSP rigorosa con nonce?

Genera un nonce al momento del rendering e aggiungilo al tag dello script SeaText: <script nonce="{{nonce}}" src="..." async></script>. Il nonce deve corrispondere all'intestazione CSP per quella risposta.

L'attributo async ritarda la traduzione?

Lo script viene caricato in modo asincrono, ma SeaText riscrive il DOM dopo la sua esecuzione. Per i contenuti above-the-fold, considera di aggiungere fetchpriority="high" al tag dello script o di inserire un piccolo bootstrap che avvii il caricatore prima.

Ogni quanto dovrei rieseguire questi controlli?

Dopo ogni distribuzione che tocca il template HTML, le intestazioni CSP, la struttura del dominio o le policy di cookie/archiviazione. Un test sintetico programmato mensilmente è una buona rete di sicurezza.

Dove trovo lo snippet corrente se è cambiato?

Accedi alla dashboard di SeaText, apri Installazione → Integrazione generale e copia lo snippet etichettato come "SEATEXTCODEINTEGRATION".

Passaggi successivi

Aggiungi il test di regressione CI in questo sprint. Pianifica una finestra di verifica di 15 minuti post-lancio per la prossima migrazione. Tieni la checklist nel tuo runbook in modo che qualsiasi ingegnere possa eseguirla senza conoscenze pregresse.

Ulteriori letture e fonti di confronto

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

• Check for loaded scripts on the site - Web Testing - Katalon Community
• The checks that make or break your next website migration
• javascript - Verify External Script Is Loaded

Come SeaText può aiutare

La dashboard di SeaText mostra lo stato di caricamento dello script in tempo reale, il rendering delle varianti e gli eventi di rilevamento bot per dominio. Dopo la migrazione, apri la Vista Live per confermare che il traffico venga elaborato. Se lo script non viene caricato, la dashboard segnala il dominio con uno stato rosso e mostra l'errore CSP o di rete esatto. Puoi anche generare un nuovo snippet con l'ID progetto e il nonce CSP corretti dalla pagina di Installazione.