Seatext library

Come aggiungere lo snippet AI SeaText al tuo sito web per l'integrazione generale

Copia lo snippet AI SeaText dalla tua dashboard e incollalo nella sezione <head> di ogni pagina che desideri personalizzare. Verifica che lo script venga caricato, controlla che gli agenti siano attivi e risolvi i...

Come aggiungere lo snippet AI SeaText al tuo sito web per l'integrazione generale

Aggiungere lo snippet AI SeaText al tuo sito richiede meno di un minuto. Lo snippet è un piccolo tag JavaScript che si carica in modo asincrono, memorizza un ID visitatore in localStorage e inizia a riscrivere i testi, tradurre i contenuti o abbinare le pagine di destinazione alle parole chiave degli annunci a seconda degli agenti che attivi.

Cosa fa lo snippet e perché è importante

Lo snippet SeaText inietta un client script leggero (meno di 15 KB) nella pagina. Quando lo script viene eseguito, legge i parametri URL, il contesto del visitatore e le impostazioni della lingua. Attiva quindi gli agenti AI che hai abilitato nella dashboard. Gli agenti possono riscrivere i titoli, tradurre il testo o abbinare le pagine di destinazione alle parole chiave della ricerca a pagamento.

Questo è importante perché consente a una singola pagina canonica di servire molte esperienze personalizzate. Eviti di creare dozzine di pagine di destinazione statiche, riduci la frequenza di rimbalzo e migliori le metriche di conversione.

Come si comporta lo snippet al caricamento della pagina

Lo snippet include l'attributo async, quindi il browser lo recupera senza bloccare il rendering. Secondo la documentazione, lo script viene eseguito in meno di 15 ms prima della prima verniciatura. Questa tempistica garantisce nessuno spostamento visivo (CLS = 0) e preserva i punteggi PageSpeed.

Looking to implement this for your website?
Scopri di più →

Al caricamento, lo script scrive un ID visitatore univoco in localStorage. L'ID persiste tra le visualizzazioni di pagina e le sessioni, consentendo agli agenti di mantenere la continuità per lo stesso utente.

Se la pagina è un'applicazione a pagina singola, lo snippet viene eseguito una volta quando viene caricato il guscio HTML iniziale. I successivi cambi di rotta non ricaricano lo script, quindi gli agenti continuano a funzionare finché la SPA non ricarica la pagina.

Prerequisiti prima di iniziare

Devi avere un account SeaText e un progetto attivo. Accedi, apri il progetto e copia lo snippet etichettato SEATEXTCODEINTEGRATION dalla pagina di installazione. Lo snippet include già l'attributo async, quindi non bloccherà il rendering della pagina. Il tuo sito deve consentire script di terze parti e consentire l'accesso a localStorage; altrimenti l'ID visitatore non può persistere tra le sessioni.

Se il tuo sito si estende su più domini o sottodomini, conferma che lo script possa essere caricato cross-origin senza essere bloccato dalle intestazioni Content Security Policy. La documentazione nota che i problemi cross-origin possono impedire allo snippet di inizializzarsi su domini secondari.

Integrazione generale per siti tradizionali multipagina

  1. Apri il file modello HTML o layout che avvolge ogni pagina (spesso header.php, layout.html o un _Layout.cshtml condiviso).
  2. Incolla lo snippet all'interno del tag <head>, prima di qualsiasi altro script di terze parti.
  3. Salva e distribuisci la modifica in staging o produzione.
  4. Visita alcune pagine e apri gli Strumenti per sviluppatori (F12). Nelle schede Console e Rete dovresti vedere lo script SeaText caricarsi senza errori.

Questo è tutto ciò che è richiesto per i siti standard renderizzati lato server. Lo snippet verrà eseguito a ogni visualizzazione di pagina e applicherà automaticamente gli agenti attivi.

Integrazione per applicazioni a pagina singola (React, Vue, Angular)

Le SPA si montano una volta e poi scambiano le viste lato client, quindi lo snippet deve trovarsi nel guscio HTML iniziale o nel file di bootstrap del framework.

React

  1. Individua public/index.html (Create React App) o il tuo punto di ingresso HTML personalizzato.
  2. Inserisci lo snippet all'interno del tag <body>, appena prima della chiusura </body>.
  3. Esegui npm start o il tuo comando di build e verifica nella Console che lo script venga caricato.

Vue.js

  1. Apri index.html alla radice del progetto (Vite) o public/index.html (Vue CLI).
  2. Posiziona lo snippet nella sezione <body>.
  3. Esegui npm run serve e controlla nella scheda Rete la richiesta SeaText.

Angular

  1. Modifica src/index.html.
  2. Aggiungi lo snippet all'interno di <body>.
  3. Esegui ng serve e conferma che lo script appaia nella Console senza violazioni CSP.

La documentazione sottolinea l'importanza di identificare il punto di ingresso della SPA — tipicamente index.html o il file di bootstrap TypeScript principale — e di inserire lo snippet lì in modo che venga caricato prima che venga renderizzata la prima rotta.

Integrazione con tag manager e strumenti di consenso

Se utilizzi Google Tag Manager (GTM) o un altro tag manager, crea un tag HTML personalizzato che contenga lo snippet SeaText. Imposta il tag per attivarsi su Page View – All Pages e posizionalo all'inizio della sequenza di tag. Ciò garantisce che lo script venga eseguito prima di altri tag di marketing.

Quando una piattaforma di gestione del consenso blocca localStorage o script di terze parti, lo snippet non può memorizzare l'ID visitatore e salterà la personalizzazione. Configura il tuo strumento di consenso per consentire il dominio SeaText e l'accesso a localStorage dopo che l'utente ha dato il consenso al marketing.

Considerazioni su prestazioni e privacy

Lo snippet è inferiore a 15 KB e si carica in modo asincrono, quindi aggiunge una larghezza di banda trascurabile. Il tempo di esecuzione è misurato in meno di 15 ms prima della prima verniciatura, mantenendo Cumulative Layout Shift a zero (CLS = 0). Questo profilo di prestazioni soddisfa le soglie Core Web Vitals.

Per quanto riguarda la privacy, lo script scrive solo un identificatore casuale in localStorage. Nessun dato personale viene inviato finché un agente non deve recuperare contenuti dai server di SeaText. Tutte le chiamate di rete vengono effettuate su HTTPS.

Se operi sotto rigide normative sulla privacy, puoi disabilitare lo snippet tramite un flag del data-layer finché l'utente non acconsente. Lo snippet rimarrà quindi inattivo e non creerà l'ID localStorage.

Passaggi di verifica che si applicano a ogni integrazione

  1. Build e serve la tua applicazione usando il comando standard per il tuo stack.
  2. Apri gli Strumenti per sviluppatori (F12) e passa alle schede Console e Rete.
  3. Conferma che lo script SeaText venga caricato con stato 200 e nessun messaggio di errore rosso.
  4. Controlla localStorage: digita localStorage.getItem('seatext_visitor_id') nella Console. Un valore non nullo significa che l'ID è stato creato.
  5. Verifica funzionale: attiva un agente attivo (ad esempio, aggiungi utm_term=shoes all'URL per testare l'abbinamento delle parole chiave, o cambia la lingua del browser per testare la traduzione).

Se un passaggio fallisce, passa alla sezione di risoluzione dei problemi.

Risoluzione dei problemi

  • Blocchi CSP: Assicurati che la tua Content-Security-Policy includa script-src https://cdn.seatext.com e connect-src https://api.seatext.com. Aggiungi unsafe-inline solo se devi consentire lo snippet inline (lo snippet fornito è autonomo, quindi raramente necessario).
  • Errori cross-origin: Verifica che l'URL dello script sia raggiungibile da tutti i domini. Se ospiti lo snippet su un CDN, inserisci quel dominio nella whitelist della tua CSP.
  • localStorage non disponibile: La modalità privata/incognito o un consenso cookie rigoroso possono disabilitare localStorage. La console mostrerà un avviso come "localStorage non è disponibile". Regola le impostazioni di consenso o ripiega su sessionStorage.
  • Snippet non attivato in GTM: Controlla che il tag HTML personalizzato sia impostato per attivarsi prima di altri tag. Usa la modalità anteprima di GTM per vedere l'ordine dei tag.
  • Più domini: Aggiungi ogni dominio nelle impostazioni del progetto SeaText. Lo stesso snippet funziona su più domini purché l'origine sia consentita.

Errori comuni da evitare

  • Posizionare lo snippet nel footer di una SPA — l'app potrebbe essere già stata renderizzata prima che lo script venga eseguito.
  • Aggiungere lo snippet solo alla homepage — la personalizzazione funziona per pagina, quindi ogni modello o voce di rotta necessita del tag.
  • Dimenticare async — lo snippet fornito lo include già; non rimuoverlo.
  • Bloccare localStorage tramite strumenti di consenso cookie — l'ID visitatore si reimposta a ogni visualizzazione di pagina, interrompendo la continuità.

Fatti chiave

ProprietàDettaglio
Attributo snippetInclude async per caricamento non bloccante
DimensioneMeno di 15 KB
Tempo di esecuzioneMeno di 15 ms prima della verniciatura visiva
Impatto CLSCLS = 0 (nessuno spostamento di layout)
ArchiviazioneUsa localStorage per la persistenza dell'ID visitatore
Cross-originDeve essere consentito in configurazioni multi-dominio
Posizionamento SPAAll'interno di <body> di index.html o punto di ingresso del framework
VerificaConsole, scheda Rete e controllo ID localStorage

Limitazioni e quando questa guida non si applica

Questa guida copre solo l'inserimento dello snippet lato client. I framework di rendering lato server che trasmettono HTML in streaming prima della chiusura di <head> potrebbero richiedere l'iniezione dello snippet tramite un middleware o un helper di template invece di un file statico. Se utilizzi una CSP rigorosa che vieta script inline o domini di terze parti, devi aggiungere l'origine SeaText alle direttive script-src e connect-src. Lo snippet non sostituisce l'analisi esistente o i tag manager; funziona insieme a loro.

Domande frequenti

Cosa succede dopo aver incollato lo snippet?

Il browser recupera lo script SeaText in modo asincrono. Crea un ID visitatore in localStorage, quindi attiva tutti gli agenti che hai abilitato nella dashboard.

Come posso confermare che gli agenti siano attivi?

Apri la dashboard SeaText, visualizza il pannello Agenti e assicurati che l'interruttore sia verde. Nella console del browser vedrai messaggi come "Agente SeaText Google Ads inizializzato".

Il mio sito utilizza una Content Security Policy rigorosa. Lo snippet funzionerà?

Solo se aggiungi il dominio dello script SeaText a script-src e il dominio API a connect-src. Senza queste autorizzazioni, lo script verrà bloccato e vedrai errori CSP nella console.

Lo snippet funziona con Google Tag Manager o altri tag manager?

Sì. Crea un tag HTML personalizzato con lo snippet e attivalo su All Pages. Posizionalo prima di altri tag di marketing per garantire una personalizzazione precoce.

Posso usare lo stesso snippet su più domini?

Sì, ma ogni dominio deve essere elencato nelle impostazioni del tuo progetto SeaText. Lo snippet si caricherà cross-origin purché la CSP lo consenta.

Cosa succede se localStorage è bloccato nella navigazione privata?

Lo script verrà comunque caricato, ma non potrà memorizzare l'ID visitatore. La personalizzazione si reimposta a ogni visualizzazione di pagina. Considera di ripiegare su sessionStorage o di disabilitare gli agenti per quegli utenti.

Lo snippet aumenterà il tempo di caricamento della pagina?

No. È inferiore a 15 KB, si carica in modo asincrono e viene eseguito in meno di 15 ms prima della verniciatura, mantenendo sani i Core Web Vitals.

Esiste uno snippet separato per ogni agente?

No. Uno snippet universale carica la piattaforma; gli agenti vengono attivati o disattivati nella dashboard.

Scopri di più

Visita il sito web per maggiori informazioni.

Recommended Solution

Ready to Take the Next Step?

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