---
title: Troubleshooting & FAQ
description: Il widget Audin non appare, problemi di iframe/CSP, eventi non ricevuti — diagnosi passo-passo e risposte alle domande frequenti.
---

Questa pagina raccoglie le situazioni più comuni nell'integrazione del widget e
come risolverle, più una FAQ finale.

## Il widget non appare

È il caso più frequente. Controlla nell'ordine:

<Steps>

### Lo snippet è prima di `</body>`?

Lo snippet va incollato **prima della chiusura del tag `</body>`**, su ogni pagina
in cui vuoi il widget. Se è in un punto in cui non viene eseguito (o non è presente
nel template effettivo della pagina), il widget non si carica.

### Il `data-widget-id` è corretto?

Verifica che il `data-widget-id` nello snippet corrisponda **esattamente** a quello
del widget nel dashboard (`app.audin.ai`), senza il placeholder `IL-TUO-WIDGET-ID`
lasciato per errore. Se manca, in console vedrai un errore come
`[AudinChat] Missing data-widget-id` (o `[AudinEmbed] ...`).

### `init()` viene davvero chiamato?

Il widget si attiva solo quando chiami `init()`. Nello snippet standard ciò avviene
nell'handler `onload` del loader (`w.AudinChat.init()` o `w.AudinEmbed.init()`). Se
hai modificato lo snippet, assicurati che `init()` sia effettivamente invocato dopo
il caricamento dello script.

### (Embedded) il container `data-target` esiste?

In modalità embedded il `<div>` puntato da `data-target` deve esistere nel DOM **al
momento dell'inizializzazione**. Se manca, in console compare
`[AudinEmbed] Target container not found: <selettore>`. Verifica che il selettore di
`data-target` corrisponda all'`id` del container e che il `<div>` abbia dimensioni
(altezza/larghezza) non nulle.

</Steps>

## Problemi di iframe / CSP

Il widget è caricato dentro un iframe servito da `https://widget.audin.ai`. Se il
tuo sito ha una **Content Security Policy** restrittiva, lo script o l'iframe possono
essere bloccati: in console vedrai errori di CSP che citano `script-src`, `frame-src`
(o `child-src`) o `connect-src`.

Per risolvere, consenti `https://widget.audin.ai` nelle direttive pertinenti (vedi la
[nota su iframe/CSP](/docs/widget/configurazione-e-comportamento#nota-su-iframe-e-csp)).
Se non usi alcuna CSP, di norma non serve alcuna configurazione.

## Gli eventi non vengono ricevuti

Se le tue callback su `on(...)` non scattano:

- **Iscriviti all'evento giusto per la modalità.** L'embedded (`AudinEmbed`) emette
  **solo** `message`: `open`/`close` non vengono mai emessi inline. Solo il popup
  (`AudinChat`) emette `open`/`close`. Vedi la tabella in
  [API & eventi](/docs/widget/api-ed-eventi#eventi).
- **Usa l'oggetto giusto.** Iscriviti su `AudinChat` per il popup e su `AudinEmbed`
  per l'embedded; non sono intercambiabili.
- **Controlla il nome dell'evento.** I nomi sono `message`, `open`, `close` (tutto
  minuscolo). Un nome diverso non genera errori ma non riceve mai callback.
- **Iscriviti dopo che lo script è caricato.** L'oggetto `window.AudinChat` /
  `window.AudinEmbed` esiste solo dopo che il loader ha caricato lo script: registra
  i listener nello stesso punto in cui chiami `init()` (es. nell'`onload`).

## FAQ

<Accordions>

<Accordion title="Devo includere il widget in tutte le pagine?">
Sì, lo snippet va incollato su **ogni pagina** in cui vuoi che il widget compaia
(tipicamente nel template/footer condiviso del sito o del CMS). In una single-page
application basta una volta: vedi [Configurazione & comportamento](/docs/widget/configurazione-e-comportamento#single-page-application-spa-e-cambio-rotta).
</Accordion>

<Accordion title="Il data-widget-id è un segreto?">
No. Il `data-widget-id` finisce nell'HTML pubblico della tua pagina ed è sicuro
esporlo. È diverso dall'**Account API Key**, che invece va usata **solo lato server**
e non va mai messa nel browser.
</Accordion>

<Accordion title="Posso avere popup ed embedded sulla stessa pagina?">
Sì. Sono oggetti distinti (`window.AudinChat` e `window.AudinEmbed`) e si
inizializzano separatamente. Vedi l'esempio in
[Configurazione & comportamento](/docs/widget/configurazione-e-comportamento#popup-ed-embedded-sulla-stessa-pagina).
</Accordion>

<Accordion title="Come cambio l'aspetto o i testi del widget?">
Dal dashboard (`app.audin.ai`): colori, stile, posizione, bot collegato e messaggi
si configurano lì. Non ci sono opzioni di tema o testo nel codice di embed — l'unica
opzione di `init()` è `user`. Vedi [Configurazione & comportamento](/docs/widget/configurazione-e-comportamento#dashboard-vs-codice).
</Accordion>

<Accordion title="Come collego una conversazione a un utente loggato?">
Passa i suoi dati a `init({ user: { email, phone, fullName, customData } })`. Tutti
i dettagli e la nota privacy sono in [Dati utente & lead matching](/docs/widget/dati-utente).
</Accordion>

<Accordion title="Posso aprire la chat da un mio bottone?">
Sì, ma **solo in modalità popup**: chiama `AudinChat.open()` (e `AudinChat.close()`
per chiuderla). L'embedded è sempre inline e non ha `open()`/`close()`. Vedi
[API & eventi](/docs/widget/api-ed-eventi#open--close--solo-popup).
</Accordion>

</Accordions>

## Prossimi passi

<Cards>
  <Card href="/docs/widget/api-ed-eventi" title="API & eventi" description="Metodi ed eventi per modalità (popup vs embedded)." />
  <Card href="/docs/widget/configurazione-e-comportamento" title="Configurazione & comportamento" description="Dashboard vs codice, SPA, coesistenza e nota iframe/CSP." />
</Cards>