Widget BluBot
Il widget di chat incorporabile — architettura, canali supportati, browser, impatto sulle prestazioni e privacy.
BluBot è il widget di chat che porta l'assistente Blu Pantheon sul tuo sito. Si installa con una riga di codice, si carica in modo asincrono e non interferisce con lo stile né con il JavaScript della pagina ospite.
Snippet di installazione
<script src="https://static.blupantheon.com/blubot/v1/bpblubot.umd.js" data-project-key="bp_proj_7f3a9c21" defer></script>Incollalo appena prima della chiusura del tag body.
Architettura
| Componente | Descrizione |
|---|---|
| Bundle UMD | File singolo bpblubot.umd.js servito dalla CDN, senza dipendenze esterne |
| Loader | Registra window.BluBot, legge la configurazione e crea il contenitore |
| Shadow DOM | L'interfaccia vive in una shadow root isolata: nessun conflitto di CSS |
| Trasporto | HTTPS per la configurazione, WebSocket per i messaggi in tempo reale |
| Motore widget | Renderizza le schede prodotte dal Widget Builder |
| Archivio locale | localStorage per l'identificativo della sessione e le preferenze |
Il percorso di una conversazione attraversa quattro passaggi.
| Passaggio | Origine | Destinazione | Protocollo |
|---|---|---|---|
| 1 | Pagina del sito | static.blupantheon.com | HTTPS, download del bundle |
| 2 | Loader BluBot | api.blupantheon.com | HTTPS, validazione chiave e configurazione |
| 3 | Shadow DOM isolato | api.blupantheon.com | WebSocket, messaggi in tempo reale |
| 4 | API | Modello, knowledge base, strumenti, webhook | Interno alla piattaforma |
Isolamento
- Stili: tutto il CSS è confinato nella shadow root. I tuoi reset globali, i framework di utilità e i fogli di stile del tema non toccano il widget, e viceversa.
- JavaScript: l'unica variabile globale introdotta è
window.BluBot. Non vengono modificatiArray.prototype,fetcho altri oggetti nativi. - Rete: le richieste partono solo verso
api.blupantheon.comestatic.blupantheon.com.
Nessun iframe
BluBot non usa un iframe: l'apertura è istantanea, il widget eredita il contesto di navigazione e resta accessibile alle tecnologie assistive della pagina.
Canali supportati
| Canale | Stato | Note |
|---|---|---|
| Sito web (desktop e mobile) | Stabile | Canale principale |
| Modalità incorporata in un contenitore | Stabile | Vedi Personalizzazione |
| App ibride Capacitor e Cordova | Stabile | Autorizza capacitor://localhost |
| WhatsApp Business | Stabile | Configurato in Integrazioni |
| Facebook Messenger e Instagram | Beta | Su richiesta |
| App native iOS e Android | Beta | SDK dedicati |
| Telegram | Beta | Su richiesta |
Browser supportati
| Browser | Versione minima | Note |
|---|---|---|
| Chrome, Edge | 111 | — |
| Firefox | 113 | — |
| Safari (macOS e iOS) | 16.4 | — |
| Samsung Internet | 22 | — |
| Opera | 97 | — |
Su browser non supportati il widget non si inizializza e non genera errori in console. Puoi attivare un ripiego che mostra un collegamento a una pagina di contatto.
Impatto sulle prestazioni
| Metrica | Valore |
|---|---|
| Dimensione del loader | 14 kB compressi con Brotli |
| Dimensione dell'interfaccia | 96 kB compressi, caricata alla prima apertura |
| Tempo fino a interattivo | Inferiore a 120 millisecondi sul loader |
| Impatto su Largest Contentful Paint | Nessuno con defer |
| Impatto su Cumulative Layout Shift | Nessuno: il widget è in posizione fissa |
| Richieste alla prima visita | 2 verso la CDN, 1 verso l'API |
| Font | Nessun font esterno caricato per impostazione predefinita |
Caricamento pigro
Il bundle dell'interfaccia viene scaricato solo quando l'utente apre la chat, o dopo che la pagina è diventata inattiva. La prima visita non paga il costo completo del widget.
Privacy e dati raccolti
| Dato | Raccolto | Scopo | Disattivabile |
|---|---|---|---|
| Identificativo anonimo di sessione | Sempre | Continuità della conversazione | No |
| Testo dei messaggi | Sempre | Erogazione del servizio | No |
| Lingua del browser | Sempre | Selezione della lingua di risposta | Sì |
| URL della pagina | Predefinito | Contestualizzazione della risposta | Sì |
| Referrer | Predefinito | Statistiche di origine | Sì |
| Tipo di dispositivo e browser | Predefinito | Diagnostica | Sì |
| Indirizzo IP | Predefinito | Sicurezza e antiabuso, troncato dopo 24 ore | Sì |
Dati utente passati da setUser | Solo se lo prevedi | Personalizzazione | Sì |
| Cookie di terze parti | Mai | — | — |
Consenso
Se il tuo sito richiede il consenso preventivo, attiva gdprConsentRequired:
il widget non contatta l'API finché l'utente non accetta. Vedi
Configurazione e
Conformità.
Il widget usa localStorage con due chiavi (bp_sid, bp_prefs) e non imposta cookie.
La conservazione delle conversazioni segue la politica del tenant.
Contenuti della sezione
Installazione
Snippet canonico e istruzioni per HTML, WordPress, Shopify, Next.js, React, Angular e GTM.
Configurazione
Tutte le opzioni di inizializzazione, in forma di attributi data e di oggetto JavaScript.
API JavaScript
Metodi di window.BluBot per aprire, chiudere, inviare messaggi e identificare l utente.
Eventi
Eventi emessi dal widget e inoltro verso Google Analytics 4 e Tag Manager.
Personalizzazione
Variabili CSS, launcher personalizzato, font, RTL, tema scuro e modalità incorporata.
Risoluzione dei problemi
Checklist diagnostica: CORS, CSP, domini, z-index, cache, ad blocker e proxy.
Passi successivi
- Guida rapida — dal tenant vuoto al widget pubblicato.
- Progetti — ottieni la chiave e autorizza i domini.
- Supporto — assistenza sull'integrazione.