:::note Versione del sorgente
Nel checkout attuale, il sorgente del loader ospitato è widget.js v16; questo non identifica la versione caricata dal tuo sito. Verifica la versione effettivamente distribuita prima di affidarti al comportamento del sorgente corrente. L’SDK npm pubblicato 0.1.4 condivide mount identici: chiama remove() su ogni handle corrispondente; solo l’ultimo avvia il teardown. sendMessage() headless non ritenta automaticamente.
:::
Personalizzazione del widget ospitato
Personalizza l'interfaccia pronta all'uso caricata da https://chattybox.ai/widget.js. Per gli esempi canonici di installazione per framework e piattaforma, consulta le Guide all'installazione.
Prima di personalizzare
Crea il progetto, indicizzane i contenuti e verifica risposte rappresentative in Prova il chatbot prima di dedicare tempo alla presentazione. Consulta Per iniziare per la sequenza completa.
Configura il widget ospitato
- Vai alla dashboard e seleziona il progetto.
- Apri Personalizza → Aspetto per modificare l’aspetto, il branding e le impostazioni di Lingua.
- Controlla lo stato del salvataggio automatico pertinente; correggi gli errori di convalida o riprova i salvataggi non riusciti prima di testare il widget installato.
Il codice di installazione e le chiavi pubbliche si gestiscono in Installa. Quando sei pronto per installare:
- Apri Installa → Chiavi e domini per controllare o creare una chiave pubblica per il browser e verificarne le impostazioni delle origini. Se necessario, usa Modifica origini.
- In Installa → Installazione sul sito web, seleziona una chiave adatta e copia lo snippet generato. Una chiave creata senza restrizioni funziona su tutte le origini; una chiave preparata per un sito può essere già limitata all’origine di quel sito. Controlla la chiave selezionata prima di usarla in staging o localhost.
- Facoltativamente, abilita restrizioni esatte delle origini come protezione aggiuntiva: non autenticano i visitatori.
- Segui le Guide all'installazione per la tua piattaforma.
<script
src="https://chattybox.ai/widget.js"
data-api-key="YOUR_API_KEY"
data-api-url="https://adorable-woodpecker-629.convex.site/chat"
async
></script>
Le modifiche alla presentazione salvate nella dashboard vengono applicate alla prossima inizializzazione del widget, senza sostituire lo snippet. Le pagine già aperte non si aggiornano in tempo reale: ricaricale per recuperare le impostazioni salvate.
Nel sorgente corrente, se il recupero della configurazione fallisce o la risposta non è valida, il widget resta non disponibile e non mostra un’interfaccia di fallback. Anche una risposta valida con enabled: false lascia il widget non disponibile; l’API chat rifiuta le richieste con HTTP 403 quando il widget è disabilitato, comprese quelle dell’SDK. Questo caso è distinto dal fallimento del recupero. Se invece la configurazione viene recuperata correttamente ma il caricamento delle traduzioni fallisce, il widget può essere visualizzato con le etichette inglesi integrate. Verifica la versione del loader distribuito prima di fare affidamento su questi comportamenti del sorgente corrente.
Personalizzazione visiva
La sezione Aspetto del widget dell’editor della dashboard consente di modificare colori supportati, posizione, icona e testo senza intervenire sul codice del sito. Verifica il risultato nel widget ospitato: l’anteprima e il loader non sono identici.
Controlli della dashboard
-
Colore accento – Scegli il colore principale del brand. Influisce sul pulsante di apertura, sugli elementi in evidenza e sui messaggi degli utenti.
-
Posizione widget – Scegli dove deve comparire il widget sullo schermo.
-
Titolo intestazione – Imposta il titolo mostrato in cima alla finestra della chat.
-
Messaggio di benvenuto – Personalizza il primo messaggio che i visitatori vedono quando aprono la chat.
-
Mostra il branding di ChattyBox – Il branding è obbligatorio nel piano Free. I piani Starter e superiori possono nascondere il footer “Powered by ChattyBox”.
L’editor include anche i controlli Sfondo widget, Colore testo e Icona widget. Le opzioni dell’icona sono Predefinita, Emoji, URL immagine e Carica; Dimensione icona compare solo con URL immagine o Carica e offre le dimensioni piccola, media e grande. I file caricati devono pesare al massimo 512 KiB e avere un tipo MIME immagine accettato (PNG, JPEG, WebP, SVG, GIF o ICO). Il sorgente corrente del loader ospitato v16 usa iconSize per dimensionare il pulsante di apertura e l’icona; verifica la versione del loader distribuito prima di fare affidamento su questo comportamento.
Controlla lo stato del salvataggio automatico pertinente, quindi ricarica la pagina installata per verificare le modifiche. L’anteprima della dashboard è una simulazione, non il widget ospitato. Nei progetti bloccati su config-as-code, aspetto e lingua sono gestiti dalla configurazione; i progetti che ne hanno diritto possono comunque salvare separatamente la preferenza di branding.
Valori predefiniti della configurazione
Questi sono i valori restituiti da una richiesta pubblica di configurazione del widget riuscita quando non esiste un valore personalizzato:
| Campo | Valore predefinito |
|---|---|
enabled | true, a meno che il widget non sia disabilitato nel progetto |
themeColor | #3b82f6 |
chatBgColor | #0f172a |
textColor | #f8fafc |
position | bottom-right; sono supportati tutti e quattro gli angoli |
iconType, iconSize | default, medium; nel sorgente corrente il loader ospitato v16 usa la dimensione per il pulsante di apertura e l’icona |
iconEmoji, iconUrl | Emoji a forma di fumetto, null |
headerTitle | Chat with us (valore predefinito dell'API) |
welcomeMessage | Hi! 👋 How can I help you today? (valore predefinito dell'API) |
showBranding | true; obbligatorio per i progetti Free |
localeMode, defaultLocale, allowLocaleOverride | auto, en, true (valori predefiniti) |
Opzioni avanzate
Impostazioni della dashboard e attributi dello script
La maggior parte del comportamento del widget dovrebbe essere gestita dalla dashboard, così non dovrai ridistribuire il sito per le modifiche semplici.
Usa la dashboard per colori, posizione, icona, titolo, messaggio di benvenuto, impostazioni della lingua, gestione delle chiavi pubbliche, scraping e analisi.
Le chiavi pubbliche sono progettate per essere usate nel codice del browser: identificano il progetto, ma non sono credenziali di gestione né autenticano i visitatori. Una chiave creata senza restrizioni funziona in produzione, anteprime, staging e localhost; una chiave preparata per un sito può essere già limitata alla sua origine. Le restrizioni delle origini sono facoltative e offrono una protezione aggiuntiva; se le abiliti, mantieni le origini esatte sincronizzate con i domini su cui il widget è installato.
Usa gli attributi dello script per configurare il widget all’inizializzazione:
data-api-keyidentifica la chiave pubblica del widget.data-api-urlindica al widget dove inviare le richieste. In produzione è un URL stabilehttps://...convex.site/chatpresente nella dashboard.data-localerichiede una lingua specifica per l’interfaccia all’avvio del widget, se il progetto consente gli override dello script. Nel sorgente attuale, il loader osserva anche le modifiche successive a questo attributo.data-coloredata-positionsovrascrivono rispettivamente colore accento e posizione salvati, ma solo dopo il recupero corretto della configurazione. Preferisci i valori della dashboard: questi attributi possono nascondere modifiche successive.data-debug="true"abilita la diagnostica nella console; per impostazione predefinita è disattivata.
Per ogni nuovo messaggio, il widget ospitato del sorgente corrente prova a inviare l’origine e il percorso della pagina HTTP(S) corrente per le analisi Trigger più usati, senza verificare se la pagina è pubblica. Il contesto non valido o troppo lungo viene omesso e i retry riutilizzano quello originale. Il widget rimuove query string, frammenti e credenziali, ma il percorso può contenere identificatori sensibili. Rispetta inoltre prefers-reduced-motion, fornisce un campo messaggio con etichetta e annunci in tempo reale e mostra le citazioni nell’elemento espandibile accessibile da tastiera Fonti.
Il contesto della pagina proviene dall’URL HTTP(S) corrente, non da una verifica che la pagina sia pubblica. Non caricare il widget su percorsi sensibili solo perché le query string vengono rimosse. Il loader può inoltre inviare errori di inizializzazione, configurazione, traduzione e chat a /widget-error tramite beacon o fetch, includendo dettagli d’errore limitati, lingua, versione e origine/percorso della pagina. Per questi rapporti non è necessario attivare la modalità debug.
La chat usa risposte JSON complete, non lo streaming di token. Il sorgente corrente del loader ospitato v16 crea una chiave di idempotenza per messaggio e pianifica al massimo 10 tentativi di trasporto automatici per errori di rete, corpi di risposta riusciti interrotti, HTTP 429, HTTP 5xx e risposte 409 con un header Retry-After leggibile. Non pianifica altri retry se il ritardo supererebbe il budget di 30 secondi: non è un timeout rigido per una richiesta già in corso. CORS nel browser può nascondere Retry-After. Questo retry non è previsto da sendMessage() headless; le richieste GET iniziali del loader hanno retry separati. Per recuperare la configurazione, il loader v16 prova prima Authorization: Bearer e, solo dopo HTTP 400, riprova passando la chiave nella query string. Se window.ChattyboxSDK espone il costruttore Chattybox, il loader usa l’SDK npm pubblicato 0.1.4 per recuperare la configurazione; anche in questo caso il fallback alla query string riguarda solo la configurazione. L’invio dei messaggi usa il trasporto proprio del loader. La conversazione resta in memoria per quella specifica istanza del widget e si perde al ricaricamento o alla reinizializzazione; i messaggi già salvati sul server possono restare. Le fonti vengono deduplicate e limitate a tre voci mostrate; le risposte di fallback possono non avere fonti. Verifica la versione del loader distribuito prima di fare affidamento sul comportamento del sorgente corrente.
Per il mount tramite SDK, la versione pubblicata 0.1.4 condivide solo opzioni identiche e rifiuta modifiche a chiave, endpoint, URL dello script, lingua o debug finché tutti gli handle corrispondenti non vengono rimossi.
Se il widget non compare dopo l'installazione, consulta la Risoluzione dei problemi.
Per esempi specifici per piattaforma, inizia da Docusaurus, MkDocs, VitePress, WordPress o GitBook.
Nascondi il widget in pagine specifiche
Per nascondere visivamente il widget, applica il seguente CSS solo alle pagine selezionate (se lo applichi globalmente, lo nascondi ovunque):
.chattybox-widget {
display: none;
}
Nascondere il widget con CSS non impedisce l’inizializzazione, le richieste API o la segnalazione degli errori e non è un controllo del consenso o della privacy. Il loader non decide se il consenso è stato dato: inserisci lo script solo dopo il consenso richiesto e impediscine il reinserimento dopo la revoca o su percorsi esclusi. Per le transizioni di route lato client o la revoca del consenso, il sorgente corrente widget.js v16 espone window.ChattyBox.destroy(). Con l’SDK 0.1.4, rimuovi tutti gli handle di mount corrispondenti: l’ultimo segnala il teardown. Verifica che il loader distribuito supporti il teardown; rimuovere soltanto il tag script non basta. Il teardown rimuove UI e stili posseduti dal widget e annulla il lavoro in sospeso, ma non può annullare richieste già elaborate dal server.
Controlli del browser
Nel sorgente corrente widget.js v16, window.ChattyBox esiste già durante l’avvio con status: 'loading' e destroy(). Dopo l’inizializzazione riuscita, controlla window.ChattyBox?.status === 'ready' prima di chiamare open(), close(), toggle() o sendMessage(text). destroy() rimuove il widget e gli stili posseduti, interrompe il lavoro dell’istanza e cancella il globale; non può annullare richieste già elaborate dal server. close() chiude solo il pannello, lasciando visibile il pulsante. sendMessage(text) restituisce una promise dell’operazione UI, non una promise della risposta; gli invii mentre un messaggio è in corso vengono ignorati. Questo globale è distinto dai costruttori SDK su window.ChattyboxSDK. Verifica la versione del loader distribuito prima di fare affidamento su questo comportamento.
Temi chiaro/scuro controllati dal sito (sorgente attuale)
Il workflow config-as-code del sorgente corrente supporta le palette facoltative widget.theme.light e widget.theme.dark. Ognuna accetta primaryColor, backgroundColor e textColor come colori esadecimali a sei cifre; i colori omessi ereditano i valori base di widget.theme. Le configurazioni con un unico tema continuano a funzionare senza modifiche. Questa funzione richiede il CLI/backend del sorgente corrente e il loader ospitato v16; il CLI/config pubblicato 0.3.1 non accetta questi nuovi campi. Verifica la versione del loader distribuito prima di fare affidamento su questo comportamento.
Imposta data-theme="light" o data-theme="dark" sullo script del loader prima che venga eseguito per selezionare la palette iniziale. Collega poi l’interruttore del tuo sito all’API del browser:
window.ChattyBox?.setTheme('light');
window.ChattyBox?.setTheme('dark');
window.ChattyBox?.setTheme(null); // Restore the configured base appearance.
Il widget aggiorna gli stili esistenti senza azzerare messaggi, fonti, testo della bozza o una richiesta in sospeso. La selezione del tema non può disabilitare il widget né rimuovere l’attribuzione. Il tuo sito gestisce la persistenza delle preferenze e il comportamento in base al tema del sistema operativo; il widget seleziona solo la palette configurata.
Integrazioni personalizzate
Ti serve una configurazione più mirata rispetto al widget ospitato? Crea la tua interfaccia con l'SDK JavaScript oppure contatta support@chattybox.ai per assistenza sull'architettura.
Supporto multilingue
Nel sorgente locale corrente widget.js v16, il loader ospitato risolve la lingua UI secondo la modalità fissa o automatica del progetto e osserva le modifiche a <html lang> e a data-locale dello script. Aggiorna le etichette senza azzerare la conversazione, la bozza o un retry in sospeso. La sola navigazione non cambia lingua: aggiorna uno di questi attributi quando serve. Le modifiche alle impostazioni della dashboard richiedono una nuova inizializzazione. Verifica la versione del loader distribuito prima di affidarti agli aggiornamenti live della lingua.
Lingue ufficialmente supportate
Il widget ha cataloghi di traduzione per 14 lingue. Tutti i cataloghi attuali usano la scrittura da sinistra a destra. I testi scritti dal progetto e le risposte generate dall’AI non vengono tradotti dai cataloghi dell’interfaccia.
| Lingua | Codice |
|---|---|
| Inglese | en |
| Francese | fr |
| Tedesco | de |
| Spagnolo | es |
| Italiano | it |
| Olandese | nl |
| Portoghese | pt |
| Polacco | pl |
| Svedese | sv |
| Indonesiano | id |
| Estone | et |
| Finlandese | fi |
| Gallese | cy |
| Ceco | cs |
:::note Lingua dell'interfaccia e risposte Il loader del sorgente corrente invia la lingua UI risolta con le richieste di chat. Il backend rileva la lingua della domanda e tenta il recupero e la generazione consapevoli della lingua. Per i fallback propri del prodotto, un segnale riconosciuto della lingua della domanda prevale sulla lingua UI; se il rilevamento non è conclusivo o si basa soltanto sull’euristica inglese per testi ASCII, la lingua UI può determinare la lingua del fallback. In assenza di entrambi si applicano i valori predefiniti del prodotto. Un fallback scritto dal progetto viene usato così com’è; la lingua UI non traduce quel testo né modifica le risposte generate dall’AI. La qualità della risposta e le lingue disponibili dipendono dai contenuti indicizzati e dal modello configurato; i cataloghi UI non garantiscono la qualità delle risposte. :::
Come funziona il rilevamento della lingua
Nel sorgente locale corrente widget.js v16, il widget usa un sistema di rilevamento a cascata:
- Override dello script consentito – Un
data-localesupportato prevale seallowLocaleOverridenon è false, anche in modalità Fixed. - Modalità Fixed – Senza un override consentito supportato, viene usato
defaultLocalee si ignorano la lingua della pagina e quella del browser. - Modalità Auto – Si prova il primo valore supportato nell’ordine:
<html lang>della pagina,navigator.language, ciascuna voce dinavigator.languages,userLanguage(legacy) e infinedefaultLocale. - Normalizzazione – La corrispondenza non distingue maiuscole e minuscole; le varianti regionali riconosciute, come
fr-CA, vengono ricondotte alla lingua base supportata. I candidati non supportati vengono ignorati; se nessuno è supportato, si usa l’inglese. I valori predefiniti sono modalità Auto, inglese e override dello script consentiti.
I titoli e i messaggi di benvenuto personalizzati vengono mostrati così come sono, senza traduzione automatica. Nel sorgente corrente, i titoli e i messaggi predefiniti sono localizzati. Se il recupero della configurazione è riuscito ma il caricamento delle traduzioni fallisce, il widget si avvia con le etichette inglesi integrate. Se invece fallisce il recupero della configurazione, il widget resta non disponibile. Verifica la versione del loader distribuito prima di fare affidamento su questo comportamento.
Override manuale della lingua
Per richiedere una lingua specifica indipendentemente dalle impostazioni del browser, abilita Consenti override tramite script e aggiungi l'attributo data-locale prima dell'avvio del loader:
<script
src="https://chattybox.ai/widget.js"
data-api-key="YOUR_API_KEY"
data-locale="de"
data-api-url="https://adorable-woodpecker-629.convex.site/chat"
async
></script>
:::tip Caso d'uso
È particolarmente utile per un sito multilingue in cui ogni versione linguistica ha un proprio URL (ad esempio /de/, /fr/). Imposta data-locale in base alla lingua della pagina e verifica l'interfaccia renderizzata.
:::
Impostazioni della lingua nella dashboard
La dashboard dell'app consente di configurare le preferenze linguistiche del widget per progetto:
- Rilevamento automatico – Usa prima la lingua della pagina, poi quelle del browser e infine la lingua predefinita configurata, salvo un override da script consentito.
- Fissa – Usa la lingua UI selezionata, salvo che Consenti override tramite script sia attivo e venga fornito
data-locale. - Consenti override tramite script – Permette all’attributo
data-localedi sovrascrivere l’impostazione.
Accedi a queste impostazioni dalla dashboard → Personalizza → Aspetto → sezione Lingua. Controlla lo stato del salvataggio automatico della lingua e correggi gli errori o riprova il salvataggio prima di testare.
Corrispondenza della lingua dei contenuti
Per un'esperienza multilingue utile, indicizza contenuti pubblici nelle lingue dei visitatori e verifica le fonti; rilevamento e recupero non sono garantiti. Per farlo:
- Esegui lo scraping di tutte le versioni linguistiche della documentazione usando il file
sitemap.xml. - Lo scraper tenta di rilevare la lingua della pagina; verifica contenuti e fonti.
- Il recupero tenta di preferire la lingua della domanda, ma può usare altri contenuti indicizzati.
Configurazione nella dashboard dell'app: quando configuri lo scraping, usa l'URL sitemap.xml (ad esempio https://yourdocs.com/sitemap.xml) per individuare le versioni linguistiche, quindi verifica le pagine indicizzate. Le sitemap non aggirano limiti di crawl o esclusioni.
Risoluzione dei problemi
Il widget continua a essere visualizzato in inglese
- Ricaricamento completo come diagnosi – Ricarica con Ctrl+F5 o Cmd+Shift+R, poi controlla le richieste del widget e delle traduzioni nel pannello di rete del browser.
- Controlla
data-locale– Verifica che l'attributo sia impostato correttamente con un codice lingua supportato. - Verifica modalità e autorizzazioni – La modalità Fixed o gli override disabilitati possono ignorare intenzionalmente la lingua del browser o
data-locale. - Verifica la lingua del browser – Controlla che la lingua preferita del browser sia impostata correttamente.
- Controlla
langnell'HTML della pagina – Assicurati che la pagina contenga<html lang="de">(o il codice appropriato).
Le fonti sono nella lingua sbagliata
- Esegui nuovamente lo scraping dei contenuti – Assicurati che tutte le versioni linguistiche siano indicizzate.
- Usa sitemap.xml – Verifica che gli URL desiderati siano stati effettivamente indicizzati; limiti di crawl ed esclusioni possono ometterli.
- Controlla la lingua della query – L'AI cerca di adeguare la lingua della risposta a quella della query.
Mancano traduzioni
- Controlla le lingue supportate – Solo i 14 codici sopra elencati hanno cataloghi; le etichette mancanti possono usare il fallback inglese.
Best practice
- Imposta
<html lang>nelle pagine – Aiuta l'accessibilità e il rilevamento del widget. - Testa con
data-localedurante lo sviluppo – Verifica che ogni lingua venga visualizzata correttamente. - Esegui lo scraping di tutte le versioni linguistiche – Usa
sitemap.xmlper la scoperta e verifica le pagine indicizzate. - Esamina le domande reali – Controlla le conversazioni e le lacune di contenuto specifiche per lingua; la dashboard non mostra attualmente una distribuzione delle lingue UI del widget.