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:
Il parametro id
Il secondo argomento passato, clip
Object
onError
public function onConnectError(status:String):void {
// qui va il codice di gestione dell'errore!
}
L'argomento status
Connect
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
mochi.as3.MochiEvents.endPlay
non è possibile tracciare due sessioni contemporaneamente
Per il metodo startPlay
mochi.as3.MochiEvents.startPlay(stringa);
Dove “stringa
String
Per il metodo endPlay
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
tag
String
value
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.
