Configurazione & comportamento
Cosa si configura nel dashboard vs lato codice, come usare il widget Audin in una single-page application, far coesistere popup ed embedded e una nota su iframe e CSP.
Versione Markdown di questa pagina
Scarica o copia il contenuto di questa pagina in formato .md — utile per fornirlo a un agente AI che integra questa specifica feature.
Il widget si divide nettamente in due piani: cosa si configura nel dashboard e cosa controlli dal tuo codice. Capire questo confine evita di cercare opzioni "di codice" che non esistono.
Dashboard vs codice
L'aspetto e il comportamento del widget vivono nel dashboard (app.audin.ai):
quando il widget si carica, recupera la sua configurazione dal server tramite il
data-widget-id. Dal tuo codice di embed controlli solo l'integrazione
(quando caricarlo, quali dati utente passare, come reagire agli eventi).
| Aspetto | Dove si configura |
|---|---|
| Colori, stile, posizione, icona della bolla | Dashboard |
| Bot/assistente collegato e suo comportamento | Dashboard |
| Messaggi (saluto, testi, placeholder) | Dashboard |
| Quale widget caricare | Codice — data-widget-id |
| Popup o embedded | Codice — quale script + data-target |
| Dati dell'utente loggato | Codice — init({ user }) |
| Quando aprire/chiudere il popup | Codice — open() / close() |
| Reagire ai messaggi / apertura | Codice — on(...) |
Non esistono opzioni di codice per tema, lingua o testi: cambiarli si fa nel
dashboard. L'unica opzione accettata da init() è user (vedi
Dati utente). Modifiche fatte nel dashboard valgono
per tutte le pagine che usano quel data-widget-id, senza toccare lo snippet.
Single-page application (SPA) e cambio rotta
In una SPA (React, Vue, Angular…) la pagina non viene ricaricata a ogni navigazione: lo snippet nel tuo HTML viene eseguito una volta sola. Questo va benissimo per il widget.
Inizializza una sola volta
Chiama init() una volta sola, al primo caricamento dell'applicazione. È idempotente:
chiamate successive sono no-op, ma non ha senso ripeterle a ogni cambio rotta. Il
widget e la conversazione persistono tra le navigazioni interne.
Non re-inizializzare a ogni navigazione
Cambiare rotta nella SPA non richiede di re-inizializzare il widget. Lascialo vivere: la sua connessione e lo stato della chat restano attivi mentre l'utente naviga.
Usa destroy() solo se devi rimuoverlo davvero
Se in certe sezioni vuoi rimuovere completamente il widget (es. un'area dove non deve
comparire), chiama destroy(): smonta l'iframe e chiude la connessione. Per
ripristinarlo dovrai chiamare di nuovo init().
Evita di montare/smontare il widget a ogni transizione di rotta: ricreare
l'iframe a ripetizione è inutilmente costoso e interrompe la conversazione in
corso. Inizializzalo una volta e, se serve, usa open()/close() (popup) per
mostrarlo/nasconderlo invece di destroy()/init().
Popup ed embedded sulla stessa pagina
Le due modalità possono coesistere sulla stessa pagina: una bolla popup in basso
a destra e, contemporaneamente, una chat embedded inline. Sono oggetti distinti
(window.AudinChat e window.AudinEmbed) e si inizializzano separatamente.
<!-- Chat inline -->
<div id="audin-chat" style="width: 400px; height: 600px;"></div>
<!-- Loader embedded -->
<script>(function(w,d,s,u,i){var f=d.getElementsByTagName(s)[0],
j=d.createElement(s);j.async=true;j.src=u;
j.setAttribute('data-widget-id',i);
j.setAttribute('data-target','#audin-chat');
j.onload=function(){w.AudinEmbed.init()};
f.parentNode.insertBefore(j,f);
})(window,document,'script','https://widget.audin.ai/widget-embedded.js','IL-TUO-WIDGET-ID');</script>
<!-- Loader popup -->
<script>(function(w,d,s,u,i){var f=d.getElementsByTagName(s)[0],
j=d.createElement(s);j.async=true;j.src=u;
j.setAttribute('data-widget-id',i);
j.onload=function(){w.AudinChat.init()};
f.parentNode.insertBefore(j,f);
})(window,document,'script','https://widget.audin.ai/widget.js','IL-TUO-WIDGET-ID');</script>Usa script (e window.*) distinti per le due modalità: widget.js →
AudinChat, widget-embedded.js → AudinEmbed. Inizializza ciascuno con il
proprio init().
Nota su iframe e CSP
Il widget è renderizzato dentro un iframe servito da https://widget.audin.ai,
isolato dal DOM e dagli stili della tua pagina (e viceversa). Per la maggior parte
dei siti non serve alcuna configurazione aggiuntiva.
Se il tuo sito adotta una Content Security Policy (CSP) restrittiva, devi consentire il caricamento dello script e dell'iframe del widget. A livello alto, le direttive coinvolte sono tipicamente:
script-src→ per caricare il loader/script dahttps://widget.audin.aiframe-src(ochild-src) → per consentire l'iframe della chat dahttps://widget.audin.aiconnect-src→ per la connessione in tempo reale del widget verso i server Audin
Se il widget non appare e in console vedi errori di CSP (es. blocco di script-src
o frame-src), aggiungi https://widget.audin.ai alle direttive pertinenti.
Vedi anche Troubleshooting.
Prossimi passi
API & eventi
L'API JavaScript del widget Audin — i metodi e gli eventi di AudinChat (popup) e AudinEmbed (embedded), con le differenze tra le due modalità.
Troubleshooting & FAQ
Il widget Audin non appare, problemi di iframe/CSP, eventi non ricevuti — diagnosi passo-passo e risposte alle domande frequenti.