Risoluzione dei problemi e lista di controllo

Strumenti

• Strumenti per sviluppatori → Rete: loader.js, core.<hash>.js, connessione WebSocket (la scheda «Messaggi» o «Frame» mostra init, init_ok, error) oppure richieste del fallback HTTP (h/auf, …/sse, …/tx).
• Attivare la diagnostica: data-rc-debug="true" nel tag del caricatore oppure localStorage.setItem('rc_debug','1') nella console, poi ricaricare.
• Console: ReactiveChat('getSession'), ReactiveChat('getEndpoint'), ReactiveChat('isOpen'), ReactiveChat.version.

Nessun pulsante della chat visibile

• Chiave del sito mancante o non valida. Il caricatore si interrompe senza avvisi. Verifichi data-rc-site-key (8–64 caratteri tra A–Z a–z 0–9 _ -) sul tag eseguito: tag manager e componenti ausiliari dei framework talvolta omettono attributi.
• type="module" sul tag script: il caricatore non riesce a trovare il proprio tag. Lo incorpori come script classico.
• data-rc-hide-launcher="true", oppure «Solo tramite i Suoi link (nessuna icona della chat)» impostato nell’account.
• Nessun colore del marchio nel codice: senza un colore data-rc-brand valido, il pulsante compare solo dopo che la connessione è stabilita. Copi nuovamente il codice dall’account.
• Progetto in pausa o chiave sconosciuta: il server risponde con unknown_site_key (chiusura 4002); in questa scheda il widget non riprova per dieci minuti.
• Il nucleo non si carica: la console mostra [reactive.chat] core.js …. Spesso script-src o un blocco pubblicitario impedisce l’accesso all’indirizzo; vedere Dominio personalizzato.

Il pulsante c’è, ma non arriva alcun messaggio

• loader.js ospitato sul proprio server senza data-rc-ws-url: il widget cerca il server della chat sotto il Suo dominio. Nella scheda Rete vede tentativi inutili verso wss://ws.<your-domain>/rc_wss/. Soluzione: data-rc-ws-url="wss://ws.reactive.chat/rc_wss/".
• origin_denied, chiusura 1008: il dominio della pagina manca in Origini consentite. Inserisca il dominio del sito, non il sottodominio della chat.
• La CSP blocca: la console mostra un messaggio CSP su wss://… o https://…/rc_wss/h/auf. Aggiunga entrambe le forme a connect-src.
• Rete aziendale senza WebSocket: dopo due tentativi falliti, il widget passa al fallback HTTP. Se neanche questo funziona, cerchi proxy che interrompono richieste prima di 30 secondi o memorizzano le risposte nel buffer (Trasporto).
• Blocco della protezione dagli abusi (chiusura 1008 blocked): tipico dietro un proxy proprio senza chiave valida, perché tutti i visitatori hanno lo stesso indirizzo.
• Messaggio troppo lungo: il widget non invia testi oltre il limite del piano (1000 o 4000 caratteri).

Un utente autenticato risulta anonimo

La trama error contiene auth_failed con detail.reason:

• no_hash: manca userHash in identify.
• no_secret: nel progetto non è stato configurato alcun segreto.
• bad_exp: exp è in millisecondi anziché secondi, oppure non è un intero.
• expired: pagina aperta a lungo o orologio del server errato; calcoli un hash nuovo al caricamento della pagina.
• exp_too_far: più di 24 ore nel futuro.
• bad_hash: segreto, ordine (userId + "." + exp) o set di caratteri non corrispondono; il segreto è la chiave come stringa, non come byte decodificati. Con un indirizzo e-mail, questo deve essere firmato esattamente come viene passato.

Dettagli: Identificare i visitatori.

I dati dei clienti non arrivano

• L’assistente chiede all’utente di accedere anche se è autenticato: exp manca o è scaduto; senza exp non sono disponibili dati dei clienti.
• Verifica connessione nell’account indica il motivo (http_401, zeitueberschreitung, umleitung, adresse_privat…). La stringa firmata è X-RC-Zeit + "." + raw body: verifichi i byte ricevuti, non JSON ricodificato.
• Manca un campo nella risposta dell’assistente: non è abilitato nell’account oppure appartiene all’elenco dei campi mai acquisiti.

Dettagli: Endpoint dei dati dei clienti.

I webhook non arrivano

• Integrazione attiva, evento selezionato (nessuna selezione = tutti)? Dopo l’attivazione attenda fino a 15 secondi.
• Il Suo endpoint impiega più di 10 secondi a rispondere oppure risponde con un reindirizzamento.
• Il Suo endpoint ha risposto una volta con 410: questo disattiva l’integrazione. La riattivi.
• La firma non corrisponde: calcoli sul corpo grezzo e su X-RC-Timestamp + "." + body, prestando attenzione al prefisso sha256=.
• Manca contenuto in data: i campi di ogni evento sono elencati in Webhook; un evento non selezionato non arriva affatto.

API server

• 401 auth_failed: chiave revocata, errata o creata da una persona che non è più amministratore.
• 403 insufficient_scope: ambito insufficiente; required_scope indica quello necessario.
• 429: superate 120 richieste al minuto; rispetti Retry-After.
• 415/413: manca Content-Type: application/json oppure il corpo supera 64 KiB.

Il testo sulla privacy non compare

• Il caricatore manca sulla pagina o è bloccato dalla piattaforma di consenso: incorpori direttamente datenschutz.js.
• Il sito non è inserito come dominio nel progetto oppure il progetto è in pausa.
• data-rc-privacy-state="error" sull’elemento indica una richiesta fallita.

Lista di controllo prima dell’avvio

1. Tutti i domini del sito inseriti in Origini consentite.
2. Codice dell’account invariato su tutte le pagine in cui deve comparire la chat, inclusa quella della privacy.
3. CSP: script-src con la posizione di distribuzione, connect-src con wss:// e https://, img-src per le immagini.
4. Consenso: data-rc-consent o piattaforma di consenso (TCF v2 / consented.eu) verificati, con prove sia con sia senza consenso.
5. Informativa sulla privacy integrata (<div data-rc-privacy> o blocco di testo).
6. Identità: userHash con exp calcolato sul server, segreto solo nell’ambiente server, init_ok.identity.verified è true.
7. Aree con testo riservato contrassegnate con data-rc-private.
8. Con dominio personalizzato: tutti e cinque i passi della verifica «OK», chiave del proxy solo nella sua configurazione, /rc_wss/h/ escluso dal registro degli accessi.
9. Webhook: firma e timestamp verificati, duplicati rilevati tramite X-RC-Delivery, risposta 2xx rapida.
10. Fallback HTTP provato una volta con data-rc-transport="http".
11. Vista mobile (sotto 480 pixel la chat si apre a schermo intero) e uso da tastiera verificati.