In un precedente articolo abbiamo presentato uno dei più completi set di API dedicate allo sviluppo di giochi e applicativi con Flash: le MochiMedia API. Gli strumenti offerti da queste API sono vari, come abbiamo visto: dall'integrazione completa con i più diffusi Social Network fino ad arrivare alle cosiddette micro-transazioni e alla creazione di negozi online (interni al nostro applicativo) sui quali vendere prodotti, passando per un complesso e completo sistema di tracking delle statistiche.
MochiMedia promette una grande facilità d'integrazione e un risultato garantito. In questo articolo metteremo alla prova queste affermazioni, concentrando i nostri sforzi su una in particolare delle API: la Analytics API.
Le features principali le abbiamo già descritte. Permettono di tracciare ogni aspetto desiderato, in modo tale da avere un report sempre aggiornato, un fattore questo particolarmente importante per tutti coloro che vogliono monitorare la diffusione della loro applicazione e accertarsi del suo successo. Non si parla, quindi, semplicemente di visite o visitatori unici: il tracking abbraccia anche i tempi di gioco e la rilevazione delle singole sessioni di gioco, con tempistiche decise dallo sviluppatore. Oppure, ancora, si può decidere di rilevare un certo obiettivo raggiunto dal giocatore, una sorta di sistema di “achievements”, di azioni, molto usato oggi in svariati ambiti e piattaforme, specie con lo spostamento del gioco in maniera totale verso l'online.
Detto questo, per prima cosa vediamo come “aggiungere” il nostro gioco al sistema. Per prima cosa dobbiamo avere un account su www.mochimedia.com. Dopo il processo di registrazione entreremo nella nostra area privata e nella nostra pagina potremo vedere il menu principale, come nell'immagine qui sotto (figura 1):
Come prima cosa, quindi, dobbiamo aggiungere il nostro gioco al sistema, in modo tale da farci restituire un “Game ID”, identificatore univoco per il nostro gioco su MochiMedia. Sarà questo Game ID la base per l'utilizzo di tutti gli strumenti offerti dalla API. Ecco come si presenta la pagina della nostra registrazione, alla quale possiamo accedere cliccando su “Add Game” (figura 2):
Dobbiamo specificare il nome del nostro gioco (da usare come identificativo), la risoluzione del gioco nel formato aaaxbbb (esempio: 500x400). Bisogna inoltre accettare i termini d'uso di MochiMedia e decidere se si vuole avere accesso al servizio Live Updates, usato da molti per dare una marcia in più alla protezione del proprio file SWF (tematica che non tratteremo in questa occasione ma cara a molti sviluppatori che in passato si sono visti 'rubare' i propri giochi).
Una volta inviato il form veniamo riportati nella nuova pagina, interamente dedicata al nostro gioco. Qui ogni informazione è a portata di mano: dal numero di impression di eventuali canali pubblicitari al numero delle sessioni di gioco. Nel menu a sinistra, a lato, possiamo vedere il nostro Game ID appena generato. Il primo passo è fatto, ora dobbiamo andare avanti e integrare a tutti gli effetti, nel codice, le API:
Appena al di sotto del box contenente l'ID del nostro gioco troveremo un link dal quale scaricare il package completo delle MochiMedia API. Dopo il download ci ritroveremo con un pacchetto che al suo interno presenta una struttura molto simile a quella che vediamo in figura 4:
Come si può immaginare, la cartella “docs” contiene tutta la documentazione necessaria a comprendere il funzionamento delle librerie: è ben fatta e soprattutto spiega per bene come iniziare da zero, cosa assolutamente non da poco, considerando che i “primi approcci” possono essere traumatici.
Subito dopo troviamo un'altra cartella importantissima: “examples”. Qui troveremo un file di esempio (sia compilato che in formato “originario” con il codice sorgente a corredo) che copre tutte le features contemplate. Ottima quindi come riferimento nel caso ci siano dei problemi pratici: i progetti possono essere trovati in formato Actionscript 2, Actionscript 3 e Flex.
Infine, la cartella più importante: in “mochi” troveremo i file delle librerie da importare nei nostri progetti, sia in formato Actionscript 2 che Actionscript 3. Non c'è un pacchetto specifico per quello che è il nostro obiettivo, ovvero le Analytics API, ma bisognerà sempre scaricare tutto il pacchetto per intero.
Dopo questa spiegazione sulla struttura dei file, veniamo alla pratica e vediamo come implementare a tutti gli effetti nel nostro progetto le Analytics API. Facendo un passo alla volta, vediamo come includere i file necessari e fare la chiamata iniziale, la cosiddetta “unica linea di codice” promessa dagli sviluppatori delle API.
La funzione fondamentale da utilizzare è “mochi.as3.MochiServices.connect”. Deve essere usata nel momento in cui abbiamo bisogno di connettere il gioco al sistema MochiMedia per calcolare le statistiche. Ovviamente, è consigliato sistemare la chiamata al metodo nella classe principale del gioco. Il metodo in questione presenta una sintassi come questa:
connect(id, clip, onError);
Il parametro id è l'identificativo univoco del gioco che vogliamo connettere al sistema. Bisogna inserire qui il Game ID ottenuto in fase di registrazione al servizio MochiMedia.
Il secondo argomento passato, clip, di tipo generico Object, è l'oggetto (generalmente un MovieClip o uno Sprite) al quale vogliamo lasciare il compito di caricare tutti i componenti legati alle API.
onError, invece, rappresenta il nome di una funzione creata dall'utente da usare come error handler nel caso di problemi di comunicazione con le API. La sintassi da usare per realizzare la funzione interessata sarà simile a questa:
public function onConnectError(status:String):void {
// qui va il codice di gestione dell'errore!
}
L'argomento status rappresenta i risultati della chiamata al sistema. Sapremo quindi a quale variabile rivolgerci nel caso di problemi nella connessione. La chiamata al metodo Connect, ovviamente, deve essere fatta una volta sola. Altre chiamate ad altre funzioni (facenti parte delle API) fatte prima della connessione al sistema vengono messe in coda, per poi essere eseguite una volta avvenuto il collegamento ai server MochiMedia. In fase di debug potremo verificare tranquillamente il corretto funzionamento del tutto. Nella finestra di output verranno mostrate infatti le seguenti stringhe:
MochiServices Connecting… Waiting for Mochi services to connect… connected!
Una volta che vedremo questo messaggio, saremo sicuri dell'avvenuta connessione e potremo iniziare a lavorare con qualsiasi componente delle API. A questo punto, quindi, rimane solo l'ultimo passo da esaminare nel dettaglio: capire come è possibile iniziare a registrare le sessioni di gioco o l'esecuzione di determinate azioni, che successivamente portano a determinati achievements.
Per quanto riguarda le sessioni, questo è sicuramente uno degli aspetti più interessanti: alla base di questo concetto troviamo due metodi. Il primo è mochi.as3.MochiEvents.startPlay, che nel codice indica l'inizio vero e proprio della sessione da tracciare. A quel punto bisogna gestire tutto il codice relativo al livello. Appena la partita termina, si va in Game Over o viene raggiunto il punto di cui abbiamo bisogno, basta richiamare il metodo mochi.as3.MochiEvents.endPlay. Non ci sono altri metodi o complicazioni, tutto viene gestito velocemente da queste due funzioni. L'unico neo del sistema, però, è che non è possibile tracciare due sessioni contemporaneamente: le API non ancora lo permettono. Occorre specificare, però, che la sintassi di queste due funzioni non è assolutamente complicata.
Per il metodo startPlay, la sintassi è la seguente:
mochi.as3.MochiEvents.startPlay(stringa);
Dove “stringa” è una variabile di tipo String e dà un'identificazione testuale della sessione. Ad esempio, potremmo utilizzare questa funzionalità per distinguere il tempo medio delle giocate a difficoltà facile, media e difficile di un gioco, oppure per differenziare il tempo di giocata di uno specifico scenario. Le possibilità di implementazione sono infinite.
Per il metodo endPlay, invece, la sintassi è semplicemente:
mochi.as3.MochiEvents.endPlay();
Qui non dobbiamo neanche specificare un identificativo per la sessione da terminare, dato che già l'abbiamo specificata in precedenza e non abbiamo la possibilità di tracciare più sessioni contemporaneamente. Per le sessioni non c'è altro da dire: la funzionalità offerta dalle Analytics API si presenta sicuramente semplice, ma efficace e veloce da implementare.
Vediamo adesso come implementare la funzionalità relativa alle azioni che vengono intraprese dall'utente del nostro applicativo. Il fulcro essenziale stavolta è solamente una funzione: parliamo di mochi.as3.MochiEvents.trackEvent. Questo metodo prende in input due parametri: il primo è tag, di tipo String, che proprio come per le sessioni ha un ruolo puramente identificativo, assicurando un associazione efficace al valore che andremo a memorizzare. Il secondo parametro invece è value, che invece memorizza il valore vero e proprio da segnare:
mochi.as3.MochiEvents.trackEvent(tag, value);
Un esempio pratico di utilizzo di questa funzionalità può essere il seguente: il nostro giocatore ha superato il limite di 10.000 punti e quindi vogliamo segnarlo, per vedere quanti giocatori hanno raggiunto lo stesso risultato. O ancora, possiamo verificare quanti giocatori hanno finito il gioco, e così via.
L'integrazione del nostro progetto con MochiMedia Analytics è avvenuta con successo. In questo articolo non sono stati inseriti esempi di classi complete, in quanto l'implementazione è così facile e intuitiva che non necessita una tale spiegazione. Per quanto riguarda la visualizzazione delle statistiche collezionate dal sistema, per averle tutte sotto controllo, basta andare sulla Dashboard di MochiMedia.com, selezionando il nostro gioco tra le voci nel menu per aprirne la rispettiva pagina.
