Personalizzazione

Variabili CSS, launcher su misura, font, supporto RTL, tema scuro, modalità incorporata e accessibilità.

BluBot vive in una shadow root isolata: i tuoi fogli di stile non lo raggiungono. La personalizzazione avviene tramite variabili CSS personalizzate dichiarate sull'elemento host, che attraversano il confine della shadow root.

Selettore dell elemento host

blubot-widget

Applica le variabili CSS a questo elemento o a :root.

Variabili CSS

ConsoleConfigurazioneProgettiacme-srlAspetto

Le impostazioni della Console valgono come predefiniti; le variabili CSS della pagina hanno la precedenza.

Colori

Variabile	Predefinito	Effetto
`--bp-color-primary`	`#1e3a8a`	Launcher, pulsanti, bolle dell'utente
`--bp-color-primary-hover`	Derivato	Stato al passaggio del puntatore
`--bp-color-on-primary`	`#ffffff`	Testo su fondo primario
`--bp-color-surface`	`#ffffff`	Fondo della finestra
`--bp-color-surface-alt`	`#f4f5f7`	Fondo delle bolle dell'assistente
`--bp-color-text`	`#111827`	Testo principale
`--bp-color-text-muted`	`#6b7280`	Testo secondario e orari
`--bp-color-border`	`#e5e7eb`	Bordi e separatori
`--bp-color-success`	`#15803d`	Conferme
`--bp-color-warning`	`#b45309`	Avvisi
`--bp-color-error`	`#b91c1c`	Errori
`--bp-color-header-bg`	`--bp-color-primary`	Fondo dell'intestazione
`--bp-color-header-text`	`--bp-color-on-primary`	Testo dell'intestazione

Tipografia

Variabile	Predefinito	Effetto
`--bp-font-family`	Stack di sistema	Font di tutta l'interfaccia
`--bp-font-size-base`	`15px`	Dimensione del testo dei messaggi
`--bp-font-size-small`	`13px`	Orari, note, didascalie
`--bp-line-height`	`1.55`	Interlinea
`--bp-font-weight-bold`	`600`	Peso del testo in evidenza

Forme e spaziature

Variabile	Predefinito	Effetto
`--bp-radius-window`	`16px`	Raggio della finestra
`--bp-radius-bubble`	`12px`	Raggio delle bolle
`--bp-radius-launcher`	`9999px`	Raggio del launcher
`--bp-radius-button`	`8px`	Raggio dei pulsanti nei widget
`--bp-spacing-unit`	`4px`	Unità base delle spaziature
`--bp-shadow-window`	Ombra morbida	Ombra della finestra

Dimensioni e posizione

Variabile	Predefinito	Effetto
`--bp-window-width`	`400px`	Larghezza della finestra su desktop
`--bp-window-height`	`640px`	Altezza massima della finestra
`--bp-launcher-size`	`56px`	Diametro del launcher
`--bp-offset-x`	`20px`	Distanza orizzontale dal bordo
`--bp-offset-y`	`20px`	Distanza verticale dal bordo
`--bp-z-index`	`2147483000`	Livello di sovrapposizione

styles/blubot.css

:root {
  --bp-color-primary: #0f766e;
  --bp-color-primary-hover: #0d5f59;
  --bp-color-surface: #ffffff;
  --bp-color-surface-alt: #f0fdfa;
  --bp-color-text: #0f172a;
  --bp-font-family: 'Inter', system-ui, sans-serif;
  --bp-font-size-base: 15px;
  --bp-radius-window: 20px;
  --bp-radius-bubble: 14px;
  --bp-window-width: 420px;
  --bp-launcher-size: 60px;
  --bp-offset-y: 88px;
}

Contrasto

Verifica sempre il contrasto tra --bp-color-primary e --bp-color-on-primary: deve essere almeno 4,5 a 1 per il testo normale. Un launcher elegante ma illeggibile è un difetto di accessibilità.

Tema scuro

Con theme: 'auto' il widget segue prefers-color-scheme. Puoi sovrascrivere le variabili per il solo tema scuro.

Personalizzazione del tema scuro

@media (prefers-color-scheme: dark) {
  :root {
    --bp-color-surface: #0f172a;
    --bp-color-surface-alt: #1e293b;
    --bp-color-text: #e2e8f0;
    --bp-color-text-muted: #94a3b8;
    --bp-color-border: #334155;
    --bp-color-primary: #38bdf8;
    --bp-color-on-primary: #0f172a;
  }
}

Se il tuo sito gestisce il tema con una classe sull'elemento radice, sincronizzalo esplicitamente.

Sincronizzazione con il tema del sito

function sincronizzaTema() {
  const scuro = document.documentElement.classList.contains('dark');
  document.querySelector('blubot-widget')?.setAttribute('data-theme', scuro ? 'dark' : 'light');
}

new MutationObserver(sincronizzaTema).observe(document.documentElement, {
  attributes: true,
  attributeFilter: ['class']
});

Launcher personalizzato

Nascondi il launcher predefinito e usa un tuo elemento.

Disattiva il launcher integrato

Aggiungi data-launcher="none" al tag script oppure launcher: 'none' in init.

Inserisci il tuo pulsante

Usa un elemento button, non un div, per ottenere gratuitamente il comportamento da tastiera.

Collega toggle e stato

Aggiorna aria-expanded in risposta agli eventi open e close.

Launcher su misura

<button
  id="assistenza-launcher"
  type="button"
  class="acme-launcher"
  aria-expanded="false"
  aria-controls="blubot-window"
>
  <span class="acme-launcher__icona" aria-hidden="true"></span>
  <span class="acme-launcher__testo">Assistenza</span>
  <span id="acme-badge" class="acme-launcher__badge" hidden>1</span>
</button>

<script>
  (function () {
    var launcher = document.getElementById('assistenza-launcher');
    var badge = document.getElementById('acme-badge');

    launcher.addEventListener('click', function () {
      window.BluBot?.toggle();
    });

    window.addEventListener('blubot:ready', function () {
      window.BluBot.on('open', function () {
        launcher.setAttribute('aria-expanded', 'true');
        badge.hidden = true;
      });
      window.BluBot.on('close', function () {
        launcher.setAttribute('aria-expanded', 'false');
      });
      window.BluBot.on('message:received', function () {
        if (!window.BluBot.isOpen()) badge.hidden = false;
      });
    });
  })();
</script>

Font personalizzati

Il widget non carica font esterni. Per usare il tuo, dichiaralo nella pagina e indicane il nome nella variabile.

Font caricato dalla pagina ospite

@font-face {
  font-family: 'Acme Sans';
  src: url('/fonts/acme-sans-var.woff2') format('woff2-variations');
  font-weight: 300 700;
  font-display: swap;
}

:root {
  --bp-font-family: 'Acme Sans', system-ui, sans-serif;
}

Font e prestazioni

I font dichiarati con @font-face nel documento principale sono ereditati dalla shadow root. Usa font-display: swap per evitare testo invisibile durante il caricamento.

Supporto da destra a sinistra

Il widget rileva automaticamente la direzione dal contesto: se l'elemento html ha dir="rtl" oppure se locale è impostato su ar, l'intera interfaccia si specchia.

Elemento	Comportamento in RTL
Posizione del launcher	`bottom-right` diventa in basso a sinistra
Allineamento delle bolle	Utente a destra, assistente a sinistra, invertiti
Icone direzionali	Frecce e indicatori specchiati
Numeri, date, orari	Restano in direzione da sinistra a destra
Campo di scrittura	Cursore e segnaposto allineati a destra

Attivazione esplicita

<html lang="ar" dir="rtl">
  <script
    src="https://static.blupantheon.com/blubot/v1/bpblubot.umd.js"
    data-project-key="bp_proj_7f3a9c21"
    data-locale="ar"
    defer
  ></script>
</html>

Per forzare la direzione indipendentemente dalla pagina, usa data-direction="rtl" oppure direction: 'rtl' in init.

Modalità incorporata

Invece della finestra flottante puoi montare il widget dentro un contenitore della pagina: utile per pagine di assistenza dedicate o per una schermata a tutto schermo.

Montaggio in un contenitore

<div id="assistenza-incorporata" style="height: 640px; max-width: 720px;"></div>

<script
  src="https://static.blupantheon.com/blubot/v1/bpblubot.umd.js"
  data-project-key="bp_proj_7f3a9c21"
  data-auto-init="false"
  defer
></script>

<script>
  window.addEventListener('blubot:loaded', function () {
    window.BluBot.init({
      projectKey: 'bp_proj_7f3a9c21',
      mode: 'inline',
      container: '#assistenza-incorporata',
      launcher: 'none',
      autoOpen: true
    });
  });
</script>

Opzioni della modalità incorporata

Parametro	Tipo	Obblig.	Default	Descrizione
`mode`	`string`	Sì	—	Valore inline per il montaggio in un contenitore, floating per la finestra flottante. Predefinito floating.
`container`	`string`	Sì	—	Selettore CSS o elemento DOM di destinazione. Deve avere un altezza definita.
`launcher`	`string`	No	—	Impostalo a none in modalità incorporata: il pulsante flottante non serve.
`fullscreen`	`boolean`	No	—	Occupa l intera area visibile su schermi sotto i 768 pixel. Predefinito true.
`showHeader`	`boolean`	No	—	Mostra l intestazione con titolo e avatar. Predefinito true.

Il contenitore deve avere un altezza

Un contenitore senza altezza esplicita (o senza un genitore flex che gliela dia) collassa a zero pixel: il widget viene montato ma non si vede. È la causa più frequente di segnalazione in modalità incorporata.

Accessibilità

BluBot è conforme a WCAG 2.2 livello AA. Le personalizzazioni possono comprometterla: verifica sempre i punti seguenti.

Aspetto	Comportamento nativo	Cosa non rompere
Navigazione da tastiera	Tabulazione completa, `Esc` chiude	Non usare `div` cliccabili nel launcher
Focus visibile	Contorno a contrasto elevato	Non impostare `outline: none`
Trappola del focus	Il focus resta nella finestra aperta	Non spostare il focus da codice esterno
Lettori di schermo	Regione live per i nuovi messaggi	Non nascondere il widget con `display: none` da CSS
Contrasto	Almeno 4,5 a 1	Verifica i colori personalizzati
Dimensione dei bersagli	Almeno 44 x 44 pixel	Non ridurre `--bp-launcher-size` sotto `44px`
Movimento ridotto	Animazioni disattivate con `prefers-reduced-motion`	Non forzare transizioni via CSS
Ingrandimento	Utilizzabile fino al 200%	Non fissare la finestra in pixel assoluti su mobile

Tasto	Azione
`Tab`	Sposta il focus tra gli elementi interattivi
`Invio` o `Spazio`	Attiva l'elemento con il focus
`Esc`	Chiude la finestra e riporta il focus sul launcher
`Ctrl` + `Invio`	Invia il messaggio dal campo di scrittura
`Freccia su`	Richiama l'ultimo messaggio inviato

Rispetta le preferenze di movimento

@media (prefers-reduced-motion: reduce) {
  :root {
    --bp-transition-duration: 0ms;
  }
}

Anteprima delle personalizzazioni

ConsoleConfigurazioneProgettiacme-srlAspettoAnteprima

L'anteprima nella Console applica le variabili in tempo reale e consente di verificare tema chiaro e scuro, larghezze mobile e desktop e direzione RTL, senza pubblicare il progetto.

Passi successivi

Configurazione — opzioni di inizializzazione.
Avatar — nome, immagine e tono dell'assistente.
Risoluzione dei problemi — widget invisibile o mal posizionato.

Personalizzazione

Auf dieser Seite