Il sistema Analytics è composto da tre parti:
- Un sistema di raccolta dati incluso nel framework operativo dell’applicazione (il framework Analytics)
- Un sistema di memorizzazione (il server Analytics) che riceve i dati dalle applicazioni, il elabora e li memorizza in un database Postgres.
- Un sistema di visualizzazione dati incluso nella console che, interrogando via API il server Analytics, è in grado di visualizzare le informazioni raccolte dalle applicazioni.
![Installazione ed uso di Analytics Instant Developer image5 Instant Developer](https://www.instantdeveloper.com/wp-content/uploads/2024/03/image5.png)
Il framework Analytics è incluso in ogni applicazione compilata con Instant Developer Cloud ed è quindi disponibile sia in web app installate nel cloud che in applicazioni mobile distribuite tramite gli store. Le web app possono essere installate in qualunque tipo di server di produzione: sia quelli di Instant Developer Cloud, che i My Cloud che i Self Managed.
Il server Analytics è un’applicazione web che viene installata tramite la console su uno dei propri server di produzione. Può essere installata su un server di produzione di Instant Developer Cloud o su un server di tipo My Cloud. Nel primo caso, essa conta come una delle applicazioni installate sul server, per quanto riguarda il limite di applicazioni installabili.
Installazione del server Analytics #
Vediamo ora come viene installato e configurato il server Analytics. Questa operazione avviene tramite il menu Analytics della pagina di un server nella console di Instant Developer Cloud, come vediamo nell’immagine seguente.
L’installazione avviene tramite il pulsante in alto al centro Installa server Analytics. Il pulsante è verde se è possibile installare Analytics sul server selezionato.
Se invece appare una videata di errore come la seguente, significa che il server non è acceso o che non è stato acquistato il modulo Analytics e Feedback per quel server, oppure che non si possiedono i permessi sufficienti per installare sul server.
Per acquistare il modulo è possibile selezionare la voce di menu Impostazioni e poi cliccare il pulsante verde Upgrade che appare nella prima zona della pagina.
Dopo aver eseguito l’installazione, essa è disponibile anche nella pagina delle installazioni del server ed è controllabile come ogni altra applicazione su tale server.
L’applicazione AnalyticsServer non ha un’interfaccia utente specifica. Aprendola, si ottiene solo un messaggio che mostra il titolo e la versione del server. È essenziale che l’applicazione abbia il flag server session attivo, in quanto l’acquisizione dei dati avviene tramite API, ma la loro elaborazione avviene tramite una server session che tratta i dati arrivati senza sovraccaricare il server stesso.
Aggiornamento di Analytics Server #
Quando viene rilasciata una nuova versione del server, ne viene data comunicazione nella console. A questo punto è possibile aggiornarla semplicemente cliccando nuovamente il pulsante Installa server Analytics come abbiamo visto in precedenza.
Configurazione di Analytics Server #
Dopo aver installato il server, si dovranno configurare le seguenti impostazioni:
- Traccia i clic dell’utente: tutti i clic su ogni controllo azionabile verranno tracciati. È importante raccogliere questi dati per conoscere come l’utente usa l’interfaccia dell’applicazione. Default: true.
- Traccia l’apertura delle videate: tutti i passaggi da una videata all’altra verranno tracciati. È importante raccogliere questi dati per vedere quali processi l’utente esegue usando l’applicazione. Default: true.
- Giorni di validità dei dati: periodo dopo il quale i dati raccolti verranno cancellati. Default 180 giorni.
- Giorni di validità delle eccezioni: periodo dopo il quale i dati relativi alle eccezioni verranno cancellati. Default 30 giorni.
- Username dell’account SendGrid: per inviare gli allarmi tramite e-mail, il server Analytics può utilizzare un account SendGrid specifico. Se non si specifica alcun dato, verrà utilizzato l’account SendGrid di community che è sottoposto ad una quota di invio. Si consiglia di inserire i propri dati di un proprio account per evitare di non ricevere messaggi a causa di un superamento di quote.
- Chiave dell’account SendGrid: è la chiave API per utilizzare l’account SendGrid specificato nel campo precedente.
- Frequenza di controllo degli allarmi: l’attivazione di alcuni tipi di allarmi può essere controllata solo a tempo. La frequenza predefinita è 5 minuti.
- Chiave di sicurezza del server Analytics: rappresenta la chiave per poter utilizzare le API del server Analytics. Si consiglia di cliccare il pulsante Nuova chiave API per il server per generarne una tramite la console. Se non si specifica nessuna chiave, tutti potranno accedere al server, inviare dati o consultare quelli esistenti.
Oltre alle impostazioni generali del server, è possibile anche specificare impostazioni diverse per ogni applicazione che ha inviato i dati al server Analytics.
Configurazione dell’applicazione #
Dopo aver installato il server è necessario configurare il framework Analytics nel codice dell’applicazione per attivare l’invio dei dati. Il metodo più semplice per farlo è quello di inserire il seguente codice nell’evento app.onStart.
app.analytics.appName = "AnalyticsServer";
app.analytics.serverUrl = "https://<nome server>.instantdevelopercloud.com";
app.analytics.apiKey = "<chiave impostata nella console>";
app.analytics.enabled = true;
La prima riga suppone che il nome con cui è stato installato il server Analytics sia AnalyticsServer, che è appunto il default. La seconda riga contiene la URL completa del server; la terza riga comunica la chiave API per il server, quella che è stata configurata nella console. Infine la quarta riga attiva la raccolta ed il caricamento dei dati.
I dati vengono quindi raccolti dall’applicazione e memorizzati in un file locale. Ogni 15 secondi o quando l’applicazione viene mandata in background o quando viene terminata, i dati vengono inviati al server Analytics e poi cancellati dal file system locale.
L’oggetto app.analytics #
Di solito dopo la configurazione iniziale non è necessario scrivere altro codice per il funzionamento di Analytics. Tuttavia l’oggetto app.analytics contiene diversi metodi che possono essere usati per tracciare eventi particolari o inviare dati con frequenze diverse dal default.
Tramite app.analytics è inoltre possibile effettuare query su un proprio server Analytics per estrarre le stesse informazioni fornite come visualizzazione dalla console e costruirsi così propri report di analisi dati.
Vediamo ora i metodi principali per il tracciamento di eventi personalizzati:
app.analytics.logEvent(evName, params): questo metodo permette di tracciare un evento personalizzato come, ad esempio, la conclusione di un’operazione di acquisto, passando anche un oggetto di parametri dell’evento. Un esempio di oggetto parametri è il seguente:
{
labels: nomeProdotto,
prezzo: prezzoProdotto,
qta: qtaProdotto
}
Specificando la proprietà labels, le altre proprietà numeriche contenute nei parametri verranno visualizzate raggruppate per il valore della proprietà labels. Nell’esempio potremmo quindi tracciare l’acquisto di ogni prodotto, visualizzando la somma delle quantità ed il prezzo medio di vendita.
app.analytics.logPage(view): questo metodo permette di tracciare il passaggio ad una view particolare dell’applicazione. Normalmente il sistema traccia automaticamente tutte le videate aperte tramite il metodo show e quelle aperte tramite il metodo push dell’oggetto page controller del framework IonicUI. In alcuni casi è possibile voler tracciare anche altri tipi di cambio di stato dell’interfaccia utente.
Se, ad esempio, si desidera tracciare anche il cambio di visualizzazione di una tabbed view (elemento IonTabs) è possibile chiamare il metodo passando come parametro la view selezionata nella tabbed view. Un esempio di codice è il seguente:
$tabs.onChangePage = function (pageInfo)
{
app.analytics.logPage(this.elements[pageInfo.newPage]);
};
Si noti che il metodo app.analytics.logPage richiede come parametro un’istanza di view.
app.analytics.send(): invia i dati raccolti al server Analytics. Normalmente non è necessario utilizzare esplicitamente questo metodo.
Analisi dei dati #
Vediamo infine come visualizzare i dati raccolti tramite la console. Si noti che i dati rimangono memorizzati solamente nel server in cui è stata installata l’applicazione AnalyticsServer. La console in questo caso è solo un mero visualizzatore.
Per accedere alla visualizzazione dei dati analitici di un’applicazione, occorre utilizzare la voce Analytics del menu di progetto e poi selezionare l’applicazione di cui vedere i dati dalla combo box evidenziata nell’immagine seguente.
La pagina principale permette di impostare i filtri sulle date, sui periodi di confronto e su altri parametri delle sessioni, compresi gli eventi personalizzati. I dati mostrati riguardano un riassunto dei dati delle sessioni, degli utenti, delle interazioni, delle eccezioni ed infine della sincronizzazione. In ogni sezione della pagina principale è possibile modificare la misura da visualizzare selezionandola dalla relativa combo box.
Pagina delle sessioni #
La pagina delle sessioni mostra i dati relativi all’andamento nel tempo delle sessioni.
#
In particolare viene evidenziato il totale, il numero di sessioni per utente e la durata, il tutto confrontato con il periodo precedente. Cliccando sul riquadro degli utenti sarà possibile vedere il grafico relativo al numero di utenti suddiviso fra nuovi e di ritorno. Nella lista sotto al grafico è possibile vedere la distribuzione della durata delle sessioni e la distribuzione del numero di giorni di utilizzo alla settimana.
Pagina degli utenti #
La pagina relativa agli utenti mostra le informazioni relative agli utenti, la provenienza geografica, la lingua ed il dispositivo utilizzato.
Pagina degli eventi #
La pagina è particolarmente importante per comprendere come gli utenti utilizzano l’applicazione. Ci sono tre sezioni principali: interazioni, pagine visitate ed eventi personalizzati.
Il dettaglio interazioni, sotto al grafico, mostra il numero di interazioni per ogni oggetto attivabile dell’applicazione. In questo modo è possibile capire quali parti dell’interfaccia utente vengono usate di più o di meno.
Cliccando sulla sezione Pagine visitate, oltre al grafico con i totali di pagine visualizzate per giorno verrà mostrato anche il flusso di navigazione, filtrabile per singola pagina. Nella lista sotto al grafico, per ogni pagina sarà possibile sapere il numero di visualizzazioni, la durata della visita alla pagina e il numero di interazioni.
Cliccando infine nella sezione Eventi personalizzati è possibile vedere il grafico delle occorrenze di un evento nel tempo e la lista dei valori dell’evento con la valutazione dei valori minimi, medi massimi e la totalizzazione dei parametri numerici ad esso associati.
Pagina delle eccezioni #
La pagina delle eccezioni riporta i dati relativi alle eccezioni JavaScript generate nell’applicazione e non gestite.
La lista sotto al grafico riporta per ogni tipo di eccezione il numero di occorrenze e gli utenti coinvolti. Cliccando su un’eccezione verranno visualizzati i dati di dettaglio, fra cui lo stack trace, il nome della sessione, i dati della build e l’eventuale query se l’eccezione riguarda il database. Se l’applicazione è stata compilata con il supporto di debug a runtime attivo e il parametro di applicazione trackCodeLine vale true, allora sarà possibile aprire la versione del progetto installata già posizionata sulla riga di codice che ha generato l’eccezione.
Diverse opzioni nel caso di debug a runtime e trackCodeLine attivo
Pagina della sincronizzazione #
La pagina riporta le performance del sistema di sincronizzazione dei database locali con il cloud. Ci sono quattro sezioni: Sessioni, Completa, Differenziale ed Errori.
Nella sezione Sessioni viene riportato il numero di sessioni di sincronizzazione e il grafico che ne mostra l’andamento nel tempo. Il rapporto tra sincronizzazioni complete e differenziali è particolarmente importante per comprendere la corretta impostazione del sistema. La lista sotto al grafico mostra la distribuzione delle sessioni in relazione alla loro durata e il tipo di rete utilizzata. Anche la durata delle sessioni è molto importante perché riflette i tempi di attesa degli utenti prima di poter vedere i dati aggiornati.
La sezione Completa riguarda la sincronizzazione completa, cioè l’operazione di resincronizzazione dell’intero database locale. La lista sotto al grafico è particolarmente importante perché riporta per ogni classe documento il numero di istanze sincronizzate, oltre alla durata del caricamento e del salvataggio.
La sezione Differenziale riguarda la sincronizzazione differenziale e riporta il numero di variazioni differenziali ricevute. La lista sotto al grafico riporta la distribuzione della durata della sessione di sincronizzazione.
Infine la sezione Errori mostra gli errori di sincronizzazione. La lista sotto al grafico mostra l’elenco dei vari tipi di errore e il numero di occorrenze. Cliccando su un errore sarà possibile leggerne i dettagli.
Pagina degli allarmi #
La pagina degli allarmi permette di configurare una serie di allarmi che vengono attivati se si verificano una o più condizioni.
Nell’esempio seguente, l’allarme scatta quando il numero di eccezioni giornaliere è maggiore di 10.
Per aggiungere una condizione, specificare la metrica e la condizione e poi cliccare il pulsante + sulla destra. Fra le metriche sono presenti anche gli eventi personalizzati; in questo modo è possibile essere avvertiti se l’andamento di questi eventi è diverso da quello atteso.
È inoltre possibile impostare un periodo di osservazione e inserire dei filtri sui parametri delle sessioni da prendere in considerazione per valutare le condizioni dell’allarme. Dopo aver creato l’allarme è possibile condividerlo con altri utenti o gruppi della propria organizzazione.
Quando un allarme è verificato, viene inviata una mail all’utente che lo ha inserito e agli altri utenti con cui esso è condiviso, usando l’account SendGrid configurato nel server Analytics.