Architettura e flusso

I componenti

Nel browser dei visitatori:

• loader.js: un piccolo componente di caricamento di pochi kilobyte. Legge la configurazione, verifica il consenso, disegna un pulsante della chat provvisorio nella posizione definitiva (senza spostamenti del layout) e crea window.ReactiveChat con una coda di comandi. Non fa altro.
• Il nucleo (core.<hash>.js): finestra della chat, connessione, mascheramento dei dati personali, regole. Si carica solo quando scatta un attivatore: browser inattivo, mouse o dito sul pulsante della chat, comando API, segnale di frustrazione da MousePlayer. La maggior parte dei visitatori non apre mai la chat e quindi non lo carica subito.
• Moduli su richiesta: tour del prodotto, testo sulla privacy, funzioni del negozio; ciascuno solo quando serve.
• Isolamento: tutto risiede in uno shadow DOM chiuso; stili tramite fogli di stile costruibili, nessuno script inline, nessun eval, nessun cookie.

Presso reactive.chat:

• Distribuzione su https://cdn.reactive.chat/ — caricatore, nucleo, moduli.
• Server della chat su wss://ws.reactive.chat/rc_wss/: WebSocket con protocollo rc.v1; lo stesso indirizzo con https:// per fallback HTTP, modulo offline, caricamenti, testo sulla privacy e Smart Answer.
• Account su https://reactive.chat/app — impostazioni del progetto, design, knowledge base e pannello del team.
• API server su https://reactive.chat/v1/ — REST e MCP per il Suo backend.

Dalla Sua parte (facoltativo):

• Il Suo backend firma l’identità degli utenti autenticati, risponde alla richiesta di dati dei clienti, riceve webhook e chiama l’API server.
• Il Suo proxy distribuisce tutto tramite un sottodominio personalizzato (Dominio personalizzato).

Flusso di una visita alla pagina

1. Il browser carica loader.js (in modo asincrono, senza bloccare nulla).
2. Il caricatore legge data-rc-*, ReactiveChatSettings e le chiamate boot in coda, verifica chiave del sito e consenso e disegna il pulsante provvisorio.
3. Scatta un attivatore; il caricatore carica il nucleo dalla stessa directory.
4. Il nucleo prende in carico il pulsante provvisorio e la coda ed esegue i comandi in ordine.
5. Apre la connessione e invia init con chiave del sito, identificativi, lingua, consenso, eventuale identità firmata e contesto della pagina.
6. Il server verifica origine, progetto e identità e risponde con init_ok: design e testi dell’account, regole, funzionalità, limiti e cronologia della conversazione fino a quel momento.
7. Il widget è pronto (evento ready). Segnala autonomamente i cambi di pagina nelle applicazioni a pagina singola.

Flusso di una domanda

1. Il visitatore scrive; i dati personali vengono mascherati nel browser e il messaggio ha un identificativo univoco.
2. Il server lo memorizza (riconosce le ripetizioni dall’identificativo), lo maschera di nuovo e lo conferma con un’eco.
3. L’assistente IA cerca nella knowledge base e, per domande sugli ordini da parte di un utente confermato, anche tramite l’endpoint dei dati dei clienti, quindi trasmette progressivamente la risposta. Nell’account si imposta quando passa al team (Manuale).
4. In parallelo, gli eventi passano tramite una coda a webhook e integrazioni. La chat non li attende mai.

Versioni e distribuzione

• loader.js non ha un numero di versione nel nome e viene sostituito con gli aggiornamenti. Per questo lo incorpori da cdn.reactive.chat (o tramite il Suo proxy), non come copia.
• Il nucleo si chiama core.<hash>.js; l’hash deriva dal contenuto e ogni caricatore conosce esattamente il proprio nucleo. Così i due corrispondono sempre e il nucleo può restare a lungo nella cache.
• La configurazione (design, testi, regole, tour) arriva dal server a ogni connessione. Le modifiche nell’account non richiedono un nuovo codice di incorporamento; hanno effetto dopo poco tempo (a seconda dell’impostazione, fino a un minuto).
• La versione del protocollo è 1. Vengono aggiunti nuovi campi; quelli sconosciuti vengono ignorati.
• ReactiveChat.version restituisce la versione del nucleo dopo che è stato caricato.

Dove impostare che cosa

• Nell’account: aspetto, testi, schermata iniziale, regole, tour, test A/B, personalità dell’IA (Personalizzazione), team, knowledge base, canali (Manuale).
• Nel tag script: ciò che deve valere per pagina (Riferimento del tag script).
• Nello script della pagina: identità, contesto, apertura da elementi personalizzati (API JavaScript).
• Sul Suo server: firme, dati dei clienti, webhook, API (Identità, Dati dei clienti, Webhook, API server).

Successivo: Avvio rapido