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: Il caricamento dello script del widget non riesce

✅ Soluzione: Verifica gli attributi richiesti

Assicurati che tutti gli attributi dati richiesti siano presenti sul 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 di solito 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 configurato correttamente gli URI di reindirizzamento - Il dominio del widget deve essere consentito
• Verifica che il dominio del widget sia consentito 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 whitelist 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 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 posizionamento 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 mobili

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

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: Colori non applicati

✅ 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 ricarica forzata)
• Verifica che i valori dei colori siano codici esadecimali validi (devono iniziare con # e avere 6 caratteri, ad es., #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 di debug: Apri il widget nel tuo browser e usa lo strumento di ispezione elemento per verificare quali valori CSS vengono effettivamente applicati. Questo ti mostrerà se i tuoi colori vengono caricati o sovrascritti.

❌ Problema: Caratteri non caricati

✅ Soluzione: Configurazione del carattere

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

Problemi di funzionalità

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

❌ Problema: Messaggi non inviati

✅ Soluzione: Controlla sessione e rete

I problemi di invio messaggi di solito riguardano la connettività di rete o sessioni scadute. Diagnostica sistematicamente:

• Verifica che gli endpoint API siano accessibili - Prova ad accedere direttamente all'URL API 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 firewall/software di 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: Flussi di conversazione non funzionanti

✅ Soluzione: Valida 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 dei pulsanti 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 personalizzati
• 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: Widget non funzionante 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à iframe moderne

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à debug

Abilita la modalità debug per vedere registrazioni dettagliate nella console del tuo browser. Questo fornisce informazioni su cosa sta facendo il widget a 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 non riuscite
• 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