Widget e Codice di Incorporamento (Embed)

Percorso: /dashboard/embed · Permessi: Modulo Impostazioni

Il widget è il modo principale in cui gli utenti interagiscono con il tuo assistente AI sul tuo sito web. Questa pagina spiega come distribuirlo, cosa fa ogni attributo di incorporamento e come funziona il widget internamente.

Come ottenere il tuo codice di incorporamento

Il modo più semplice per ottenere il codice di incorporamento:

Vai su Dashboard → Embed nella barra laterale.
La pagina genera automaticamente lo script corretto per il tuo bot e dominio correnti.
Clicca su Copy per copiare l'intero snippet di incorporamento.
Incollalo nell'HTML del tuo sito web, subito prima della chiusura del tag </body>.

Riferimento dello script di incorporamento

<script 
  src="https://user.frenzy.bot/chatbot-widget/v1/js/loader.js"
  data-bot-id="sales-assistant"
  data-bot-name="Sales Assistant"
  data-theme-color="#3b82f6"
  data-backend-url="https://user.frenzy.bot"
  async>
</script>

Attributi

Attributo	Obbligatorio	Cosa fa
`data-bot-id`	Sì	L'ID slug univoco del tuo bot.
`data-bot-name`	No	L'etichetta visualizzata nella parte superiore della finestra di chat.
`data-theme-color`	No	Colore primario del widget (codice hex).
`data-backend-url`	No	L'URL del server. Il valore predefinito è `https://user.frenzy.bot` (o il tuo dominio personalizzato).

Come trovare l'ID del tuo bot

Apri la dashboard e vai su Embed o Settings.
L'ID del bot è mostrato nel codice di incorporamento e nella pagina di gestione del bot.
Formato: alfanumerico minuscolo con trattini (es. sales-assistant, support-bot).

Pagina di incorporamento dinamica

La pagina Dashboard → Embed rileva automaticamente il nome dell'host corrente e genera lo snippet di incorporamento corretto. Questo è più sicuro rispetto all'inserimento manuale degli URL perché:

Se cambi dominio in seguito, il codice di incorporamento generato riflette automaticamente il nuovo dominio.
Ogni bot riceve il proprio snippet con il data-bot-id corretto.
La copia con un clic velocizza la distribuzione.

Il widget di FRENZY.BOT è progettato per l'uso in produzione con le seguenti capacità:

Funzionalità	Cosa fa
Isolamento Shadow DOM	Impedisce al CSS del tuo sito web di interferire con il design del widget
Persistenza della sessione	La cronologia della chat sopravvive ai refresh della pagina tramite localStorage
Lazy loading	Previene rallentamenti nelle prestazioni durante conversazioni lunghe
Finestra di contesto	Ultimi 6 messaggi inviati all'AI per garantire la qualità della risposta
Multilingue	Supporta più lingue con rilevamento automatico
Supporto RTL	Layout completo da destra a sinistra per ebraico e arabo
Domande suggerite	Prompt predefiniti visualizzati sotto il messaggio di benvenuto
Modulo Lead	Acquisizione contatti in-chat con campi configurabili
Text-to-speech	Riproduzione audio opzionale per le risposte dell'AI

Prima di aggiungere il widget al tuo sito di produzione:

Conferma che il server sia attivo.
Apri la pagina di test integrata: https://user.frenzy.bot/chatbot-widget/test.html
Invia alcuni messaggi di prova.
Aggiorna la pagina — la cronologia della chat dovrebbe persistere.
Verifica che il bot risponda utilizzando i contenuti della tua Knowledge Base.

Integrazione WordPress

Per i siti WordPress, sono disponibili due opzioni:

Opzione 1: Incolla lo script

Aggiungi lo script di incorporamento al file footer.php del tuo tema o utilizza un plugin che consenta l'inserimento di script personalizzati nel footer.

Opzione 2: Plugin WordPress

Carica il file ZIP del plugin WordPress di FRENZY.BOT e attivalo.
Usa lo shortcode [FRENZY.BOT_whitelabel] per una pagina del portale di supporto integrata a schermo intero.

Errori comuni

Problema	Causa	Soluzione
Il widget appare ma non risponde	`data-bot-id` errato	Controlla l'ID del bot in Dashboard → Embed
Il widget non appare	Server irraggiungibile	Verifica che la porta 8321 sia aperta e il server sia attivo
Funziona su localhost, fallisce in produzione	`data-backend-url` mancante	Impostalo sull'URL del tuo dominio di produzione
Conflitti CSS con il sito	Shadow DOM non utilizzato	Non dovrebbe accadere — controlla eventuali stili globali forzati
Versione vecchia del widget visualizzata	Cache del browser	La gestione della cache basata sulla versione risolve il problema automaticamente

Incorporamento per singolo bot

In una configurazione multi-bot, ogni bot ha il proprio snippet di incorporamento. L'attributo data-bot-id determina quale bot gestisce la conversazione. Il widget di ogni bot utilizza i propri:

System prompt e modello AI
Branding, colori e avatar
Messaggio di benvenuto e domande suggerite
Configurazione del modulo lead
Impostazioni della lingua

Cambia bot nella dashboard per generare il codice di incorporamento corretto per ognuno.

FAQ

D: Il widget si carica ma non risponde.

Verifica che data-bot-id sia corretto.
Conferma che OpenRouter sia connesso (l'indicatore LLM dovrebbe essere verde).
Controlla che la Knowledge Base abbia dei contenuti.

D: Il widget funziona su localhost ma non in produzione.

Conferma che la porta 8321 sia aperta sul tuo server.
Imposta data-backend-url sul tuo dominio di produzione (con https://).
Se utilizzi un dominio personalizzato, verifica che l'SSL sia configurato correttamente.

D: Posso usare il widget su più domini?

Sì. Il widget funziona su qualsiasi dominio purché data-backend-url punti al tuo server. Usa la pagina di incorporamento dinamica o il dominio personalizzato per coerenza.

D: Come aggiorno il widget dopo le modifiche?

Gli aggiornamenti del widget vengono applicati automaticamente tramite il sistema di cache busting basato sulla versione. Quando il server viene aggiornato, la versione del widget aumenta e i browser scaricano la nuova versione.