Widget non visibile
Checklist diagnostica in nove passaggi per capire perché il widget BluBot non compare o non funziona sul tuo sito.
Il widget non compare sul sito, oppure compare ma non risponde. Segui la procedura nell'ordine indicato: i passaggi sono ordinati dalla causa più frequente alla più rara.
Prima verifica: l'anteprima in Console
Apri Configurazione › Progetti › Widget › Anteprima. Se il widget funziona qui ma non sul tuo sito, il problema è nell'installazione o nell'ambiente della pagina, non nella configurazione del progetto.
Procedura diagnostica
Verifica che lo script sia presente nella pagina
Apri la pagina interessata, visualizza il codice sorgente (Ctrl+U oppure Cmd+Alt+U) e cerca
loader.js. Lo snippet deve comparire prima della chiusura del tag body:
<script
src="https://console.blupantheon.com/widget/v1/loader.js"
data-project-key="pk_live_acme_srl_7f3a"
defer
></script>Cause tipiche di assenza: snippet inserito solo nella home e non nel template comune; sistema di gestione dei contenuti che rimuove i tag script dai campi di testo; snippet inserito in un'area del template non renderizzata su quella pagina; pubblicazione della modifica non effettuata.
Controlla la console del browser
Premi F12 e apri la scheda Console. Cerca errori relativi a blupantheon.
| Errore in console | Significato | Rimedio |
|---|---|---|
Failed to load resource: 404 | URL dello script errato | Ricopia lo snippet dalla Console |
Refused to load ... Content Security Policy | Bloccato dalla CSP del sito | Vedi il passaggio sulla CSP |
net::ERR_BLOCKED_BY_CLIENT | Bloccato da un'estensione | Vedi il passaggio sugli ad blocker |
401 Unauthorized | Chiave di progetto non valida | Verifica la chiave |
403 Forbidden: domain not allowed | Dominio non autorizzato | Aggiungi il dominio all'elenco |
404 project not found | Progetto inesistente o eliminato | Verifica il progetto in Console |
409 project not published | Progetto in bozza | Pubblica il progetto |
BluBot is not defined | Script non caricato o caricato dopo l'uso | Verifica ordine e attributo defer |
Controlla anche la scheda Rete: filtra su blupantheon e verifica lo stato delle richieste.
Verifica la chiave di progetto
La chiave nell'attributo data-project-key deve corrispondere esattamente a quella mostrata in
Console. Errori tipici: chiave di un altro progetto, chiave dell'ambiente di prova (pk_test_)
usata in produzione, spazi o interruzioni di riga introdotti dal copia e incolla, chiave
troncata.
Confronta carattere per carattere, oppure ricopia l'intero snippet dal pulsante di copia.
Verifica i domini autorizzati
Il widget si carica solo sui domini presenti nell'elenco. Verifiche da fare:
- il dominio esatto della pagina è presente, incluso o escluso il prefisso
wwwa seconda di come il sito è realmente raggiungibile; - i sottodomini in uso sono presenti:
www.acme.iteshop.acme.itsono domini distinti; - gli ambienti di prova e staging sono presenti se ci stai testando;
- se usi
localhostin sviluppo, va aggiunto esplicitamente.
acme.it
www.acme.it
shop.acme.it
staging.acme.it
localhostAttenzione ai caratteri jolly
*.acme.it autorizza tutti i sottodomini, inclusi quelli che potrebbero essere compromessi o
ceduti in futuro. Elenca i sottodomini realmente in uso invece di usare un carattere jolly
generico.
Verifica la Content Security Policy
Se il tuo sito espone un header Content-Security-Policy, deve autorizzare le risorse del widget.
Aggiungi le direttive seguenti a quelle già presenti, senza sostituirle:
script-src https://console.blupantheon.com
connect-src https://api.blupantheon.com wss://api.blupantheon.com
style-src https://console.blupantheon.com 'unsafe-inline'
img-src https://console.blupantheon.com data:
font-src https://console.blupantheon.com
frame-src https://console.blupantheon.comEsempio di header completo:
Content-Security-Policy: default-src 'self'; script-src 'self' https://console.blupantheon.com; connect-src 'self' https://api.blupantheon.com wss://api.blupantheon.com; style-src 'self' 'unsafe-inline' https://console.blupantheon.com; img-src 'self' data: https://console.blupantheon.com; font-src 'self' https://console.blupantheon.com; frame-src https://console.blupantheon.comLa direttiva connect-src è quella dimenticata più spesso
Senza connect-src lo script si carica e il pulsante compare, ma la conversazione non parte:
la connessione all'API viene bloccata. È il caso classico di “widget visibile che non risponde”.
Ricorda anche lo schema wss: per la connessione in tempo reale.
Se usi la direttiva nonce per gli script, applicala anche allo snippet del widget.
Verifica gli ad blocker e le estensioni
Alcune estensioni per la privacy bloccano gli script di chat classificandoli come tracciatori.
Prova in finestra privata senza estensioni
Se qui il widget compare, la causa è un'estensione.
Identifica l'estensione responsabile
Disattivale una alla volta e ricarica la pagina.
Valuta l'impatto reale
Se il blocco riguarda solo la tua postazione, non è un problema del sito. Se riguarda una quota rilevante dei tuoi utenti, considera l'ipotesi del servizio da dominio proprio.
Servizio da dominio proprio
Sui piani Business ed Enterprise puoi servire il widget da un sottodominio tuo, per esempio
chat.acme.it, con un record CNAME. Il blocco da parte delle estensioni si riduce
drasticamente. Contatta il supporto per l'attivazione.
Verifica lo z-index e la sovrapposizione
Sintomo: il widget è presente nel DOM ma non visibile, oppure è coperto da un altro elemento (banner dei cookie, barra fissa, pulsante di ritorno in cima, chat di un altro fornitore).
Ispeziona l'elemento
Con gli strumenti di sviluppo cerca l'elemento con identificativo blupantheon-widget.
Se è presente nel DOM ma non lo vedi, è un problema di livello di sovrapposizione o di
posizionamento.
Verifica il valore di z-index
Il widget usa un valore elevato. Se un elemento del tuo sito usa un valore ancora superiore, lo copre.
Regola il valore da Console
Imposta un valore superiore a quello dell'elemento che copre il widget.
Verifica i contesti di sovrapposizione
Un contenitore antenato con transform, filter o will-change crea un nuovo contesto di
sovrapposizione: in quel caso il valore di z-index del widget viene confinato all'interno del
contenitore. La soluzione è spostare lo snippet fuori da quel contenitore, direttamente sotto
il tag body.
Controlla overflow e posizionamento
Un antenato con overflow: hidden può ritagliare il widget. Anche in questo caso lo snippet va
spostato al livello del body.
Svuota cache e CDN
Se hai appena modificato il sito o la configurazione, potresti vedere una versione memorizzata.
Ricarica ignorando la cache
Ctrl+Maiusc+R su Windows e Linux, Cmd+Maiusc+R su macOS.
Invalida la cache della CDN
Se usi Cloudflare, Akamai, Fastly o un servizio analogo, esegui la purga della cache per la pagina interessata.
Svuota la cache del CMS
WordPress, Drupal, Magento e i principali CMS hanno una cache delle pagine da svuotare dopo l'inserimento dello snippet.
Verifica in finestra privata
Esclude la cache locale del browser e i dati memorizzati.
Verifica che il progetto sia pubblicato
Un progetto in stato Bozza non risponde sui domini pubblici, anche se lo snippet è corretto e il dominio è autorizzato. Verifica che lo stato sia Pubblicato e che le modifiche più recenti siano state effettivamente pubblicate: la Console segnala la presenza di modifiche non pubblicate con un indicatore accanto al nome del progetto.
Tabella di riferimento
| Sintomo | Causa probabile | Rimedio |
|---|---|---|
| Nessuna traccia dello script nel sorgente | Snippet non inserito o rimosso dal CMS | Reinserisci lo snippet nel template comune e ripubblica |
| Script presente, nessun errore, widget assente | Progetto in bozza | Pubblica il progetto |
| Errore 403 domain not allowed | Dominio non in elenco | Aggiungi il dominio esatto, www incluso o escluso |
| Errore 401 unauthorized | Chiave di progetto errata | Ricopia la chiave dalla Console |
| Errore CSP su script-src | CSP restrittiva | Aggiungi https://console.blupantheon.com |
| Pulsante visibile, conversazione non parte | connect-src mancante nella CSP | Aggiungi https://api.blupantheon.com e wss://api.blupantheon.com |
| ERR_BLOCKED_BY_CLIENT | Ad blocker | Aggiungi un'eccezione o attiva il dominio proprio |
| Widget presente nel DOM ma invisibile | z-index insufficiente | Aumenta il valore in Aspetto › Avanzate |
| Widget tagliato o parzialmente visibile | Antenato con overflow hidden | Sposta lo snippet sotto il tag body |
| Widget in posizione errata | Contesto di sovrapposizione creato da un antenato | Sposta lo snippet fuori dal contenitore |
| Funziona in anteprima, non sul sito | Dominio o CSP | Verifica domini autorizzati e CSP |
| Funzionava, ha smesso dopo un aggiornamento del sito | Snippet rimosso dal deploy | Verifica il template nel repository del sito |
| Compare solo su alcune pagine | Snippet non nel template comune, o regole di visibilità | Verifica template e regole di visibilità |
| Compare due volte | Snippet inserito due volte | Rimuovi la duplicazione: il doppio caricamento causa comportamenti imprevedibili |
| Su mobile occupa tutto lo schermo | Comportamento previsto | Nessun rimedio: è il layout mobile del pannello aperto |
Se il problema persiste
Informazioni da allegare alla richiesta
- URL esatto della pagina in cui il widget non compare
- Chiave di progetto utilizzata (non è un segreto)
- Schermata della console del browser con gli errori visibili
- Schermata della scheda Rete filtrata su blupantheon
- Header Content-Security-Policy del sito, se presente
- Browser e versione, sistema operativo, dispositivo
- Indicazione se il problema si verifica anche in finestra privata
- Elenco dei passaggi già eseguiti e relativo esito