Manuale Utente - Sistema Analytics Bot

---

Introduzione

Il sistema Analytics è una piattaforma che permette di monitorare e analizzare le performance del bot conversazionale. L'interfaccia fornisce una visualizzazione completa delle interazioni, dei passaggi agli operatori (handover), delle conversioni lead e dei flussi di sessione.

Funzionalità Principali

• Visualizzazione grafici interattivi per l'analisi delle performance del bot
• Analisi degli handover per monitorare i passaggi agli operatori umani
• Tracciamento delle sessioni con metriche dettagliate
• Diagrammi Sankey per visualizzare i flussi di sessione
• Download report personalizzati in formato Excel e CSV
• Selezione intervalli temporali con range predefiniti e personalizzati

---

Accesso al Sistema

URL di Accesso

L'applicazione è accessibile tramite l'URL della piattaforma Crafter. Dopo l'autenticazione, l'utente viene reindirizzato alla dashboard principale.

Autenticazione

Il sistema utilizza un meccanismo di autenticazione basato su token con refresh automatico per garantire sessioni persistenti senza interruzioni.

Lingue Supportate

L'interfaccia è disponibile in tre lingue:

• Italiano (it-IT) - predefinita
• Inglese (en-US)
• Portoghese Brasiliano (pt-BR)

La lingua dell'interfaccia può essere modificata dal menu utente nella toolbar superiore.

---

Interfaccia Principale

Layout

L'interfaccia è composta da:

1. Toolbar superiore - contiene il logo, il titolo dell'applicazione e il menu utente
2. Pannello laterale (HUD) - selettore date, totali e controlli
3. Area principale - visualizzazione grafici e tab analytics
4. Footer - informazioni sul copyright

Navigazione

La navigazione principale prevede due tab:

• Transcripts - visualizzazione e ricerca delle sessioni
• Analytics - visualizzazione grafici e metriche (focus di questo manuale)

Pannello HUD (Heads-Up Display)

Il pannello laterale sinistro è sempre visibile e contiene:

• Selettore intervallo temporale con calendario interattivo
• Visualizzazione totali (quando disponibili)
• Pulsante download report per esportare i dati

Il pannello può essere chiuso/aperto tramite il pulsante menu in alto a sinistra.

---

Selezione Intervallo Temporale

Date Picker

Il calendario interattivo permette di selezionare un intervallo temporale personalizzato per l'analisi dei dati.

Funzionalità

• Selezione range di date - cliccare sulla data iniziale e finale per definire l'intervallo
• Visualizzazione corrente - le date selezionate sono mostrate in badge nella parte superiore
• Formato data - DD/MM/YYYY per italiano, MM/DD/YYYY per inglese
• Auto-apply - le modifiche sono applicate automaticamente alla selezione

Range Predefiniti

Per velocizzare la selezione, sono disponibili i seguenti intervalli predefiniti:

Range	Descrizione
Oggi	Giorno corrente
Ieri	Giorno precedente
Questa settimana	Dal lunedì alla domenica della settimana corrente
Settimana precedente	Dal lunedì alla domenica della settimana scorsa
Mese corrente	Dal primo all'ultimo giorno del mese in corso
Mese precedente	Tutto il mese scorso
Trimestre corrente	I tre mesi del trimestre in corso
Trimestre precedente	I tre mesi del trimestre passato
Anno corrente	Dal 1° gennaio al 31 dicembre dell'anno in corso
Anno precedente	Dal 1° gennaio al 31 dicembre dell'anno precedente

Comportamento al Cambio Date

Quando si modifica l'intervallo temporale:

1. Caricamento automatico - il sistema mostra un indicatore di caricamento
2. Aggiornamento dati - i dati vengono ricaricati per il nuovo intervallo
3. Refresh grafico - il grafico viene rigenerato con i nuovi dati
4. Aggiornamento totali - le metriche nel pannello HUD vengono ricalcolate

Nota: Il fuso orario utilizzato è quello del browser dell'utente

---

Sezioni Analytics

Il tab Analytics è suddiviso in quattro sezioni principali, accessibili tramite tab orizzontali.

1. Bot

Visualizza le metriche generali del bot nel periodo selezionato.

Grafici Disponibili

• Grafico a linee con andamento temporale delle metriche
• Serie multiple per confrontare diverse metriche
• Linee con riempimento per evidenziare le aree sotto la curva

Metriche Visualizzate

Le metriche esatte dipendono dalla configurazione del bot, ma tipicamente includono:

• Numero totale di sessioni
• Sessioni con almeno un messaggio
• Sessioni senza messaggi
• Numero totale di messaggi
• Lead generate

Totali Disponibili

Nel pannello laterale vengono mostrati i totali aggregati per:

• Sessioni
• Handover Gestiti
• Lead

2. Handover

Analisi dettagliata dei passaggi del bot agli operatori umani.

Grafici Disponibili

Visualizzazione dell'andamento temporale degli handover con distinzione tra:

• Handover espliciti - richiesti direttamente dall'utente
• Handover proposti e accettati - suggeriti dal bot e accettati
• Handover generati - totale handover innescati
• Handover gestiti - presi in carico da un operatore
• Handover non gestiti - rimasti senza risposta

Totali Disponibili

• Espliciti (total_explicit)
• Proposti Accettati (total_proposed)
• Handover Generati (total_handovers_triggered)
• Gestiti (total_managed)
• Non gestiti (total_unmanaged)

Colori

• Handover Accettati: Rosa (#FF2D7D)
• Handover Non gestiti: Blu primario (#22325d)

3. Sessioni (Sessions)

Fornisce una visione completa delle conversazioni gestite dal bot.

Grafici Disponibili

Andamento temporale con focus su:

• Sessioni con almeno un messaggio
• Sessioni senza messaggi
• Numero totale di messaggi
• Miss consecutivi (quando il bot non riesce a rispondere)

Totali Disponibili

• Sessioni con almeno un messaggio (conv_con_almeno_un_mess)
• Sessioni senza messaggi (total_conv_no_mess)
• Messaggi (total_messages)
• Miss (total_misses)

Colori

• Sessioni: Blu primario (#22325d)
• Miss: Rosa (#FF2D7D)

4. Sankey

Visualizzazione avanzata dei flussi di sessione tramite diagramma Sankey.

Caratteristiche

Il diagramma Sankey è un tipo di grafico che mostra il flusso da una serie di nodi di origine a una serie di nodi di destinazione.

• Visualizzazione flussi - mostra come gli utenti si muovono attraverso il bot
• Nodi di origine - rappresentano i punti di partenza delle conversazioni
• Nodi di destinazione - rappresentano i punti di arrivo o azioni
• Larghezza collegamenti - proporzionale al volume del flusso

Colori

• Flusso da: Rosa (#FF2D7D)
• Flusso verso: Blu primario (#22325d)

Utilizzo

Questa visualizzazione è particolarmente utile per:

• Identificare i percorsi più comuni degli utenti
• Individuare colli di bottiglia nel flusso conversazionale
• Ottimizzare l'albero decisionale del bot
• Comprendere dove gli utenti abbandonano la sessione

Schema Colori

Il sistema utilizza una palette di colori consistente:

• Primario (#22325d): Blu scuro
• Secondario (#FF2D7D): Rosa
• Accent (#14CDF0): Azzurro

---

Totali e Metriche

Visualizzazione Totali

Nel pannello HUD laterale, sotto il selettore date, vengono visualizzati i totali delle metriche per il periodo selezionato.

Formato Visualizzazione

• Valori < 100: mostrati in avatar circolare colorato
• Valori ≥ 100: mostrati in badge arrotondato più ampio

Colore

Tutti i totali utilizzano il colore secondario (rosa #FF2D7D) per coerenza visiva.

Aggiornamento Automatico

I totali vengono aggiornati automaticamente quando:

• Si cambia l'intervallo temporale
• Si passa da una sezione analytics all'altra
• Si ricarica la pagina

---

Download Report

Accesso ai Report

Il pulsante per il download dei report è disponibile nel footer del pannello HUD, identificato dall'icona cloud_download e la label "Download reports".

Tipi di Report

Cliccando sul pulsante si apre un menu con i report disponibili:

Report Standard

I report standard sono sempre disponibili e includono tipicamente:

• Report conversazioni
• Report handover
• Report lead
• Report messaggi

Ogni report standard è identificato da:

• Icona rappresentativa
• Label descrittiva
• Endpoint API dedicato

Report Personalizzati

La piattaforma offre la possibilità di avere dei report personalizzati in base alle richieste specifiche dell'azienda.

Sono evidenziati con:

• Sfondo accent (azzurro #14CDF0)
• Icona personalizzata
• Label definita dall'amministratore

Formati di Esportazione

Per ogni report è possibile scegliere tra due formati:

• Excel: ".xlsx"
• CSV: ".csv"

Processo di Download

1. Selezione intervallo - assicurarsi che le date siano corrette nel date picker
2. Click sul pulsante - aprire il menu download report
3. Scelta report - selezionare il report desiderato
4. Scelta formato - cliccare su "xlsx" o "csv"
5. Attesa elaborazione - il sistema mostra un indicatore di caricamento
6. Download automatico - il file viene scaricato automaticamente nel browser

Contenuto dei Report

I report includono:

• Dati grezzi filtrati per l'intervallo temporale selezionato
• Timestamp con timezone dell'utente
• Metadati sulle conversazioni (ID, canale, pagina, etc.)
• Metriche aggregate quando applicabile

---

Glossario delle Metriche

Metriche Generali Bot

Metrica	Descrizione
Sessioni	Numero totale di sessioni uniche di sessione avviate nel periodo
Sessioni con messaggi	Sessioni in cui è stato inviato almeno un messaggio
Sessioni senza messaggi	Sessioni aperte ma senza scambio di messaggi
Messaggi	Numero totale di messaggi scambiati (bot + utente)
Lead	Numero di conversioni lead completate

Metriche Handover

Metrica	Descrizione
Handover Gestiti	Handover totali presi in carico da operatori
Espliciti	Handover richiesti esplicitamente dall'utente
Proposti Accettati	Handover suggeriti dal bot e accettati dall'utente
Handover Generati	Numero totale di handover innescati
Gestiti	Handover a cui ha risposto un operatore
Non gestiti	Handover rimasti senza risposta

Metriche Qualità

Metrica	Descrizione
Miss	Numero di volte che il bot non è riuscito a fornire una risposta adeguata
Miss consecutivi	Sequenze di miss di fila nella stessa sessione

---

Caratteristiche Tecniche

Grafici Interattivi

I grafici utilizzano la libreria Chart.js con le seguenti caratteristiche:

• Font: Work Sans (bold)
• Animazioni: transizioni fluide tra cambi di dati
• Responsive: adattamento automatico alle dimensioni dello schermo
• Tensione curve: 0.25 per linee morbide
• Opacità riempimento: 0.6 (60%)

Performance

Il sistema implementa diverse ottimizzazioni:

• Lazy loading: i dati vengono caricati solo quando necessario
• Distruzione grafici: i grafici precedenti vengono eliminati prima di renderizzarne di nuovi
• Timeout rendering: ritardo di 100ms per garantire il caricamento completo dei dati
• Prevenzione caricamenti duplicati: flag isLoading per evitare richieste multiple simultanee

Gestione Dati Vuoti

Quando non ci sono dati disponibili per il periodo selezionato:

• Viene mostrato un feedback visivo "Nessun dato disponibile"
• Un suggerimento invita a modificare l'intervallo temporale
• I grafici non vengono renderizzati (evitando errori)
• I totali non vengono visualizzati nel pannello HUD

Timezone

Tutte le date e gli orari rispettano il fuso orario del browser dell'utente.

---

Best Practices

Per l'Analisi

1. Iniziare con intervalli brevi (settimana/mese) per analisi dettagliate
2. Confrontare periodi simili (stessa settimana di mesi diversi) per identificare trend
3. Analizzare tutti i tab per una visione completa delle performance
4. Esportare report regolarmente per analisi storiche
5. Monitorare gli handover non gestiti per migliorare il servizio clienti

Per le Performance

1. Evitare intervalli troppo lunghi (> 1 anno) per mantenere grafici leggibili
2. Attendere il caricamento completo prima di cambiare tab
3. Non modificare rapidamente le date per evitare richieste multiple

Per i Report

1. Scegliere Excel per analisi complesse con formule
2. Scegliere CSV per integrazioni con altri sistemi
3. Verificare sempre l'intervallo temporale prima del download
4. Documentare i report esportati con data e contesto

---

Supporto e Assistenza

Risoluzione Problemi Comuni

Il grafico non si carica

1. Verificare la connessione internet
2. Controllare che ci siano dati per il periodo selezionato
3. Provare a ricaricare la pagina

Il download del report non parte

1. Verificare la connessione internet
2. Controllare che ci siano dati per il periodo selezionato
3. Provare a ricaricare la pagina
4. Verificare lo spazio disponibile sul disco