Seatext library

Come risolvere gli errori JavaScript nell'integrazione di SeaText AI

Inizia aprendo la console del browser per visualizzare il messaggio di errore esatto. Verifica che la tua chiave API sia corretta e che lo script di SeaText venga caricato dopo che il DOM è...

Sintomi comuni degli errori di integrazione JavaScript

Quando lo script di SeaText AI non funziona, di solito si riscontra uno dei tre sintomi seguenti. La console del browser mostra una riga di errore rossa come Uncaught ReferenceError: SeaText is not defined oppure Failed to load resource: net::ERR_BLOCKED_BY_CLIENT. La dashboard di SeaText non visualizza il nome del tuo sito web accanto al logo, nemmeno dopo aver atteso dieci minuti. Oppure le funzionalità AI — traduzioni, varianti, chat — semplicemente non appaiono sulla pagina.

Questi sintomi indicano cause profonde diverse. Un errore nella console significa che lo script non è stato eseguito o è andato in crash durante l'inizializzazione. L'assenza del nome del sito web nella dashboard indica che l'handshake di attivazione non è stato completato. La mancanza di funzionalità spesso significa che lo script è stato caricato, ma l'AI non è stata attivata nel Main AI Hub.

Sequenza diagnostica: risoluzione dei problemi passo dopo passo

Looking to implement this for your website?

Scopri di più →

Apri la console del browser. In Chrome premi F12, scegli la scheda Console, ricarica la pagina e annota ogni riga rossa che menziona seatext o SeaText.
Controlla il posizionamento dello script. Lo snippet di SeaText deve essere incollato prima del tag di chiusura </body>, in modo che il DOM sia completamente analizzato prima dell'esecuzione dello script. Se il tuo CMS inserisce gli script nell'<head>, sposta lo snippet in un hook del footer o utilizza un plugin che stampi il codice alla fine del <body>.
Verifica la chiave API. Lo snippet contiene un identificatore univoco dell'account. Accedi al tuo account SeaText, copia nuovamente lo snippet esatto e sostituisci quello presente sul tuo sito. Un singolo errore di battitura interrompe l'handshake.
Conferma l'idoneità del dominio. SeaText limita gli URL di sviluppo come localhost e i domini di anteprima dinamici. Devi utilizzare un dominio reale e valido. Se stai effettuando test su un sottodominio di staging, crea un account SeaText separato per quel sottodominio.
Completa il rituale di attivazione. Dopo il caricamento dello script, visita o aggiorna il tuo sito web diverse volte e rimani sulla pagina per almeno 40 secondi. Quindi attendi almeno cinque minuti. Il nome del sito web dovrebbe apparire accanto al logo SeaText nella tua dashboard. Se non appare dopo dieci minuti, contatta l'assistenza.
Attiva l'AI nel Main AI Hub. Anche dopo che l'handshake ha avuto successo, l'AI rimane inerte finché non vai nel Main AI Hub, scegli gli agenti di cui hai bisogno e fai clic su Attiva. Senza questo passaggio, non verranno renderizzate traduzioni, varianti o widget di chat.

Cause più frequenti e relative soluzioni

Lo script viene caricato prima che il DOM sia pronto

Posizionare lo snippet nell'<head> senza defer causa l'errore SeaText is not defined perché la libreria tenta di collegarsi a elementi che non esistono ancora. Sposta lo snippet nel footer o aggiungi defer al tag script.

Chiave API errata o obsoleta

Ogni account SeaText è collegato a un singolo URL principale. Se hai copiato lo snippet da un account diverso o hai rigenerato la chiave senza aggiornare il sito, l'handshake fallisce. Copia lo snippet fresco dall'account corretto.

Localhost o dominio di anteprima

SeaText blocca localhost, 127.0.0.1 e gli URL di anteprima dinamici per motivi di sicurezza. Utilizza un dominio reale (es. staging.example.com) e crea un account dedicato per esso.

Domini multipli su un unico account

Un account SeaText serve un unico URL principale. Se gestisci example.com e shop.example.com sullo stesso account, solo l'URL principale si connetterà. Crea un account separato per ogni dominio.

WPEngine o hosting gestito che blocca gli script inline

WPEngine rimuove il JavaScript personalizzato per impostazione predefinita. La guida ufficiale: scarica il plugin di WP Engine che ti consente di aggiungere codice JavaScript personalizzato alle tue pagine. Installalo e applicalo a tutte le tue pagine.

Mancato rispetto dei 40 secondi di permanenza e dei cinque minuti di attesa

L'handshake di attivazione richiede sessioni di navigazione reali. Crawler automatizzati, curl o controlli headless non contano. Devi aprire la pagina in un browser reale, rimanere 40 secondi, quindi attendere cinque minuti affinché la dashboard si aggiorni.

Problemi specifici della piattaforma

WordPress (standard)

Utilizza un plugin per header/footer (es. WPCode, Insert Headers and Footers) per incollare lo snippet nel campo Body Footer. Svuota la cache del server e la cache del browser, quindi esegui la sequenza diagnostica.

WPEngine

Installa il plugin JavaScript personalizzato di WP Engine menzionato sopra. Incolla lo snippet lì. Il livello di cache di WPEngine potrebbe servire una versione obsoleta; svuota la cache di WPEngine dopo aver salvato.

Shopify

Modifica theme.liquid e incolla lo snippet appena prima di </body>. Salva, quindi visita il negozio dal vivo (non l'anteprima dell'editor del tema) per attivare l'attivazione.

React / Next.js / SPA

SeaText si aspetta un caricamento di pagina tradizionale. In una single-page app, lo script viene eseguito una volta al caricamento iniziale ma non si reinizializza al cambio di rotta. Devi chiamare manualmente la funzione di inizializzazione di SeaText dopo ogni cambio di rotta, o utilizzare un componente di layout che inietti lo script a ogni caricamento di pagina.

Processo di attivazione e verifica

Il flusso di integrazione ufficiale prevede tre passaggi visibili:

Aggiungi SeaText al tuo sito in meno di 1 minuto — incolla lo snippet.
Attiva gli agenti autonomi di cui hai bisogno — nel Main AI Hub, scegli gli agenti (Ottimizzatore CRO, Traduzione, Chat, ecc.) e fai clic su Attiva.
Guarda crescere il tuo tasso di conversione e il traffico — la dashboard inizia a riportare i dati una volta che i visitatori reali attivano gli agenti.

Se il passaggio 1 viene completato ma il passaggio 2 non mostra agenti disponibili, probabilmente l'handshake è fallito. Torna alla sequenza diagnostica.

Fatti chiave

Fatto	Dettaglio	Fonte
Posizionamento script	Incollare prima del tag di chiusura `</body>`	S1
Requisito account	Un account SeaText per dominio principale	S1
Restrizione Localhost	Gli URL di sviluppo come localhost sono limitati per sicurezza	S1
Tempo di permanenza attivazione	Rimanere sulla pagina almeno 40 secondi, poi attendere 5 minuti per la dashboard	S1
Escalation supporto	Contattare l'assistenza se il nome del sito non è visibile dopo 10 minuti	S1
Soluzione WPEngine	Utilizzare il plugin WP Engine per aggiungere JavaScript personalizzato	S1
AI inerte fino all'attivazione	L'installazione è sicura; l'AI rimane inerte finché non viene attivata nel Main AI Hub	S1
Flusso in tre passaggi	Aggiungi script → Attiva agenti → Vedi risultati	S2

Limitazioni e quando questa guida non è applicabile

Questa guida copre solo l'integrazione JavaScript lato client. Le integrazioni API lato server, le configurazioni webhook o le configurazioni CMS headless sono fuori scopo.
Se il tuo sito utilizza una Content Security Policy (CSP) rigorosa che blocca gli script di terze parti, devi aggiungere i domini di SeaText alla tua direttiva script-src della CSP. Il pacchetto sorgente non elenca tali domini; controlla la documentazione o l'assistenza di SeaText.
Gli errori originati all'interno dei server di SeaText (es. risposte 5xx dalla loro API) non possono essere risolti dal tuo lato. La sequenza diagnostica mostrerà errori di rete nella console; in tal caso, contatta l'assistenza.
Le modifiche personalizzate allo snippet di SeaText (minificazione, bundling, caricamento asincrono) non sono supportate e potrebbero interrompere l'handshake.

Terminologia

Snippet: Il breve tag <script> fornito nel tuo account SeaText che carica la libreria SeaText e il tuo identificatore di account.
Handshake: Il processo in background in cui lo script caricato contatta i server SeaText, convalida l'account e registra il dominio.
Main AI Hub: La sezione della dashboard in cui abiliti specifici agenti AI (traduzione, CRO, chat, ecc.) per il tuo sito.
Modifica Varianti: L'interfaccia per rivedere e modificare manualmente le traduzioni automatiche e le varianti di contenuto generate da SeaText.
URL Principale: Il singolo dominio collegato permanentemente a un account SeaText. Domini aggiuntivi richiedono account separati.

FAQ

Perché la console mostra "SeaText is not defined"?

Lo script non è stato caricato (errore di rete, blocco CSP) o è stato eseguito prima che il DOM fosse pronto. Sposta lo snippet nel footer o aggiungi defer.

Posso testare su localhost?

No. SeaText limita localhost e i domini di anteprima dinamici per sicurezza. Utilizza un dominio di staging reale e crea un account dedicato.

Quanto tempo ci vuole perché la dashboard mostri il mio sito?

Almeno cinque minuti dopo una sessione di navigazione reale di oltre 40 secondi. Se non è visibile dopo dieci minuti, contatta l'assistenza.

Ho bisogno di un account separato per un sottodominio?

Sì. Ogni URL principale richiede il proprio account SeaText. Un sottodominio conta come un URL principale separato.

Cosa succede se uso WPEngine?

Installa il plugin WP Engine che consente JavaScript personalizzato, incolla lo snippet lì e svuota la cache di WPEngine.

Perché le traduzioni non appaiono dopo l'attivazione?

Verifica di aver attivato l'Agente di Traduzione Sito Web nel Main AI Hub. Verifica inoltre che la pagina abbia contenuti testuali rilevabili; SeaText traduce solo i nodi di testo renderizzati.

Posso raggruppare lo script SeaText con il mio bundle JS?

Non consigliato. Lo snippet deve caricarsi direttamente dalla CDN di SeaText per mantenere l'handshake e ricevere aggiornamenti. Il raggruppamento interrompe il collegamento account-dominio.

Ulteriori letture e fonti di confronto

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

Scopri di più

Visita il sito web per maggiori informazioni.

Ready to Take the Next Step?

See how our verified tools and services help you put this guide into practice.

Scopri di più →