Risoluzione dei problemi

Sintomo. Nessun launcher in basso a destra, nessun messaggio di errore evidente.

Cause possibili.

1. Lo script non è presente nel documento finale.
2. Un plugin di ottimizzazione lo ha rimandato, unito o rimosso.
3. La pagina lo include ma il body viene sostituito da un framework dopo il caricamento.
4. Il progetto è archiviato.

Verifica.

document.querySelectorAll('script[src*="blubot"]').length;
window.BluBot?.version;

Il primo comando deve restituire 1. Se restituisce 0 lo script non c'è; se restituisce 2 o più hai una doppia installazione.

Rimedio.

• Controlla il sorgente della pagina servita, non il template.
• Escludi bpblubot.umd.js da combinazione, minificazione e caricamento ritardato del tuo plugin di ottimizzazione.
• Su applicazioni a singola pagina, monta il widget con la strategia descritta in Installazione.

Sintomo. In console compare un messaggio del tipo "Access to fetch at api.blupantheon.com has been blocked by CORS policy".

Causa. L'API risponde con gli header CORS corretti solo per le origini autorizzate del progetto. Un errore CORS indica quasi sempre un dominio non in allowlist, oppure un proxy intermedio che riscrive o rimuove gli header.

Rimedio.

window.location.origin;

Sintomo. In console: "Refused to load the script ... because it violates the following Content Security Policy directive".

Causa. La CSP del sito non elenca i domini di Blu Pantheon.

Rimedio. Aggiungi le direttive seguenti alla tua policy.

script-src   'self' https://static.blupantheon.com;
connect-src  'self' https://api.blupantheon.com wss://api.blupantheon.com;
img-src      'self' data: https://static.blupantheon.com https://assets.blupantheon.com;
media-src    'self' https://static.blupantheon.com;
font-src     'self' data:;
style-src    'self' 'unsafe-inline';
frame-src    'none';

Esempio di header completo:

Content-Security-Policy: default-src 'self'; script-src 'self' https://static.blupantheon.com; connect-src 'self' https://api.blupantheon.com wss://api.blupantheon.com; img-src 'self' data: https://static.blupantheon.com https://assets.blupantheon.com; style-src 'self' 'unsafe-inline'; font-src 'self' data:; frame-src 'none'

Sintomo. Il widget non si inizializza; in console compare BluBot: origin not allowed e l'API risponde 403 origin_not_allowed.

Causa. L'origine della pagina non è tra i domini autorizzati dell'ambiente a cui appartiene la chiave usata.

Rimedio.

https://www.acme.it
https://acme.it
https://*.acme.it
https://staging.acme.it
http://localhost:3000

Punti da controllare:

• Protocollo obbligatorio: acme.it senza https:// non è valido.
• Il carattere jolly copre un solo livello di sottodominio.
• In production è ammesso solo https.
• La propagazione richiede fino a 60 secondi.
• Verifica di usare la chiave dell'ambiente giusto: una chiave di development su un dominio di produzione produce lo stesso errore.

Sintomo. Il widget esiste nel DOM ma è coperto da un banner cookie, da una barra fissa o da un menu, oppure risulta tagliato.

Cause.

1. Un elemento della pagina ha uno z-index superiore.
2. Un antenato del widget crea un contesto di sovrapposizione (transform, filter, will-change, contain).
3. Un contenitore ha overflow: hidden.

Verifica.

const host = document.querySelector('blubot-widget');
console.log(host.parentElement.tagName, getComputedStyle(host).zIndex);

Il genitore deve essere BODY.

Rimedio.

:root {
  --bp-z-index: 2147483600;
}

Se il genitore non è body, sposta lo snippet: deve essere incluso come figlio diretto del body e non dentro un contenitore con trasformazioni. Per il banner cookie, coordinane lo z-index in modo che resti sopra il widget finché il consenso non è espresso.

Sintomo. Le modifiche pubblicate nella Console non si vedono, oppure BluBot.version riporta una versione superata.

Cause. Cache del browser, cache di un CDN intermedio (Cloudflare, Akamai), cache di un plugin di ottimizzazione, service worker che serve una copia locale.

Verifica.

window.BluBot.version;
performance.getEntriesByType('resource')
  .filter((r) => r.name.includes('blubot'))
  .map((r) => ({ url: r.name, transferSize: r.transferSize }));

Un transferSize uguale a 0 indica una risposta servita dalla cache.

Rimedio.

1. Ricarica ignorando la cache con Ctrl + Maiusc + R.
2. Svuota la cache del tuo CDN per il percorso /blubot/*.
3. Verifica che il service worker non intercetti il dominio della CDN.
4. Le configurazioni del progetto non sono nel bundle: se cambiano colori o messaggi e non li vedi, il problema è la cache della configurazione, che si aggiorna entro 60 secondi.

Sintomo. Il widget non compare solo per alcuni utenti; nella scheda Rete la richiesta risulta annullata o con stato net::ERR_BLOCKED_BY_CLIENT.

Causa. Estensioni come uBlock Origin, AdGuard, Ghostery e le protezioni integrate di Brave e Firefox bloccano gli script categorizzati come chat o analytics.

Verifica. Apri il sito in una finestra anonima con le estensioni disattivate. Se il widget compare, il blocco è lato client.

Rimedio.

• Nessuna azione tecnica elimina completamente il problema: le liste sono gestite da terze parti.
• Riduci l'impatto con un dominio personalizzato per la CDN, disponibile sui piani Business ed Enterprise: chat.acme.it è raramente presente nelle liste.
• Prevedi un percorso alternativo sempre visibile (numero di telefono, modulo di contatto) per non perdere l'utente.
• Non tentare di aggirare i blocchi con offuscamento: viola le condizioni d'uso dei browser e peggiora la reputazione del dominio.

Sintomo. La chat si apre, i messaggi partono ma le risposte arrivano con diversi secondi di ritardo o non arrivano. In console compare BluBot: websocket_failed.

Causa. Proxy, firewall o soluzioni di ispezione TLS che non supportano l'aggiornamento del protocollo a WebSocket, oppure che chiudono le connessioni persistenti dopo un timeout breve.

Verifica.

const ws = new WebSocket('wss://api.blupantheon.com/blubot/v1/echo');
ws.onopen = () => console.log('WebSocket disponibile');
ws.onerror = () => console.log('WebSocket bloccato');

Rimedio.

Chiedi al reparto IT di autorizzare quanto segue.

Destinazione: api.blupantheon.com
Porte:        443
Protocolli:   HTTPS e WSS (aggiornamento a WebSocket consentito)
Timeout:      almeno 120 secondi sulle connessioni persistenti
Ispezione:    escludere il dominio dall ispezione TLS

Il widget ripiega automaticamente sul polling ogni 3 secondi quando il WebSocket non è disponibile: il servizio resta utilizzabile, con latenza superiore.

Sintomo. Funzionalità documentate non disponibili, metodi dell'API assenti, comportamenti divergenti tra ambienti.

Causa. L'URL punta a una versione bloccata, oppure a un file copiato sul tuo server invece che alla CDN.

Verifica.

console.log(window.BluBot.version);
console.log(document.querySelector('script[src*="blubot"]').src);

Rimedio.