Risoluzione dei problemi

Hai problemi? Sei nel posto giusto. Questa guida copre i problemi più comuni che gli sviluppatori incontrano durante l'integrazione del widget, insieme a soluzioni passo-passo. La maggior parte dei problemi può essere risolta in pochi minuti.

Widget non caricato

Se il widget non appare affatto sulla tua pagina, segui questi passaggi di risoluzione dei problemi in ordine:

❌ Problema: lo script del widget non riesce a caricarsi

✅ Soluzione: verifica gli attributi richiesti

Assicurati che tutti gli attributi data richiesti siano presenti nel tag script:

<script src="https://widget.companin.tech/widget.js" data-widget-key="YOUR_WIDGET_KEY" data-locale="en"></script>

❌ Problema: autenticazione fallita

✅ Soluzione: controlla la configurazione OAuth

I problemi di autenticazione sono solitamente facili da risolvere. Lavora attraverso questi controlli:

• Verifica che client_id sia corretto nella tua applicazione OAuth - Copialo direttamente dal tuo dashboard per evitare errori di battitura
• Assicurati che l'app OAuth sia attiva e non disabilitata nel tuo dashboard
• Controlla che l'app OAuth abbia URI di reindirizzamento corretti configurati - Il dominio del widget deve essere autorizzato
• Verifica che il dominio del widget sia autorizzato nelle impostazioni CORS sul tuo backend
• Se hai recentemente rigenerato le credenziali, assicurati di utilizzare i nuovi valori

Sei ancora bloccato? Prova a creare una nuova applicazione OAuth nel tuo dashboard. A volte iniziare da zero risolve problemi di configurazione oscuri.

❌ Problema: /api/v1/auth/widget-token restituisce 400 (Origine non consentita)

✅ Soluzione: Allinea origine host e lista di autorizzazione OAuth

• Aggiungi l'origine della tua pagina di incorporamento (ad esempio http://localhost:3000) agli allowed_origins OAuth.
• Usa il formato completo schema + host (+ porta), senza percorso finale.
• Quando incorpori in un iframe, assicurati che le chiamate al token portino l'origine della pagina host in X-Embed-Origin.
• Verifica che l'URL della richiesta sia /api/v1/auth/widget-token (non percorsi legacy).

Suggerimento di convalida: Controlla la scheda di rete del browser per le intestazioni della richiesta del token e confronta X-Embed-Origin con la tua voce allowed_origins OAuth.

Widget non visibile

❌ Problema: il widget appare collassato ma il pulsante è invisibile

✅ Soluzione: controlla il posizionamento della configurazione

• Verifica l'impostazione di posizione della configurazione del widget
• Controlla eventuali conflitti CSS con position: fixed
• Assicurati che i contenitori genitori non abbiano overflow: hidden

❌ Problema: widget nascosto su mobile

✅ Soluzione: regola le impostazioni mobile

Se hide_on_mobile è abilitato nella configurazione, il widget sarà nascosto sui dispositivi mobili. Disabilita questa impostazione o regola il breakpoint mobile.

Problemi di stile

I problemi visivi sono comuni e di solito facili da risolvere. Il widget è progettato per essere visivamente isolato dalla tua pagina, ma a volte possono verificarsi conflitti.

❌ Problema: i colori non si applicano

✅ Soluzione: cancella la cache e controlla la configurazione

Segui questi passaggi per diagnosticare i problemi di colore:

• Cancella la cache del browser e ricarica la pagina (Ctrl+Shift+R o Cmd+Shift+R per un ricaricamento forzato)
• Verifica che i valori dei colori siano codici esadecimali validi (devono iniziare con # e avere 6 caratteri, ad esempio, #FF5733)
• Controlla che la configurazione sia stata salvata nel dashboard - Cerca una conferma di "salvato"
• Assicurati di modificare la configurazione corretta - Controlla che l'ID di configurazione corrisponda al tuo tag script
• Aspetta qualche secondo dopo aver salvato - Le modifiche alla configurazione possono richiedere 5-10 secondi per propagarsi

Suggerimento per il debug: Apri il widget nel tuo browser e usa lo strumento di ispezione degli elementi per verificare quali valori CSS vengono effettivamente applicati. Questo ti mostrerà se i tuoi colori si stanno caricando o vengono sovrascritti.

❌ Problema: i font non si caricano

✅ Soluzione: configurazione del font

• Assicurati che la famiglia di font sia impostata su "system-ui" o un font web-safe
• I font personalizzati potrebbero non caricarsi a causa di restrizioni CORS
• Controlla che i valori di font-weight siano supportati

Problemi di funzionalità

Quando il widget si carica correttamente ma le funzionalità non funzionano come previsto, queste soluzioni ti aiuteranno.

❌ Problema: i messaggi non vengono inviati

✅ Soluzione: controlla sessione e rete

I problemi di invio dei messaggi di solito riguardano la connettività di rete o sessioni scadute. Diagnostica in modo sistematico:

• Verifica che gli endpoint API siano accessibili - Prova ad accedere all'URL dell'API direttamente nel tuo browser
• Controlla che il token di autenticazione sia valido - Cerca errori 401/403 nella scheda di rete
• Assicurati che la sessione non sia scaduta - Le sessioni di solito durano 30 minuti di inattività
• Controlla eventuali problemi di connettività di rete - La tua connessione internet è stabile?
• Cerca errori CORS nella console - Questi indicano che il tuo dominio potrebbe non essere nella lista bianca
• Verifica che il software firewall/sicurezza non stia bloccando l'API - Le reti aziendali a volte bloccano le API esterne

Test rapido: Se i messaggi funzionano in una finestra in incognito ma non nel tuo browser normale, il problema è probabilmente legato alle estensioni del browser o ai dati di autenticazione memorizzati nella cache.

❌ Problema: i flussi di conversazione non funzionano

✅ Soluzione: convalida la configurazione del flusso

• Controlla che le parole chiave di attivazione corrispondano esattamente
• Verifica che le risposte del flusso siano configurate correttamente
• Assicurati che le azioni del pulsante siano valide

Problemi di prestazioni

❌ Problema: il widget si carica lentamente

✅ Soluzione: ottimizza il caricamento

• Usa la build di produzione invece di quella di sviluppo
• Abilita la cache del browser per le risorse statiche
• Minimizza CSS e immagini personalizzate
• Considera il caricamento pigro se non critico

❌ Problema: alto utilizzo di memoria

✅ Soluzione: riduci l'uso delle risorse

• Limita la lunghezza della cronologia dei messaggi
• Ottimizza immagini e media
• Disabilita funzionalità non utilizzate

Compatibilità del browser

❌ Problema: il widget non funziona nei browser più vecchi

✅ Soluzione: controlla il supporto del browser

Il widget richiede funzionalità moderne del browser:

• Supporto JavaScript ES6+
• API PostMessage
• CSS Grid e Flexbox
• Capacità moderne degli iframe

Browser minimi supportati: Chrome 60+, Firefox 55+, Safari 12+, Edge 79+

Ottenere aiuto

Quando hai bisogno di ulteriore assistenza oltre a questa guida, questi strumenti e risorse ti aiuteranno a diagnosticare problemi o ottenere supporto.

Modalità di debug

Abilita la modalità di debug per vedere registrazioni dettagliate nella console del tuo browser. Questo fornisce informazioni su cosa sta facendo il widget ad ogni passo:

<script  src="https://widget.companin.tech/widget.js"  data-widget-key="YOUR_WIDGET_KEY"  data-dev="true"></script>

Strumenti per sviluppatori del browser

• Controlla la scheda Console per errori JavaScript
• Controlla la scheda Rete per richieste fallite
• Controlla la scheda Applicazione per problemi di archiviazione locale
• Usa la scheda Elementi per ispezionare il DOM del widget

Passaggi comuni per il debug

1. Cancella la cache e i cookie del browser
2. Prova in modalità in incognito/navigazione privata
3. Testa con browser diversi
4. Controlla la connettività di rete
5. Verifica tutti i valori di configurazione