Gapi: un'interfaccia per integrare Google Analytics nel proprio sito!

Giovanni Canella

27/08/2013

6858

Google Analytics, celeberrimo servizio di Google per il monitoraggio delle statistiche di accesso del proprio sito, ha avuto un'esponenziale diffusione, quando nel lontano 2005 è stato lanciato, tanto che oggi è lo strumento nel suo settore più diffuso, grazie alla sua semplicità disarmante di utilizzo.

Infatti basta inserire un codice Javascript, fornitoci durante il momento della registrazione del sito, e il sistema inizierà a tenere traccia del passaggio degli utenti, indicandoci (anche in tempo reale) da che città o paese provengono, che sistema operativo stanno utilizzando, il browser e anche il provider internet.

Insomma ha moltissimi punti a suo favore, ma se volessimo accedere alle statistiche dirrettamente dal nostro sito, invece si passare ogni volta dal pannello di controllo?

Nessun problema, Google ha messo a disposizione gapi (Google Analytics PHP Interface), che, come possiamo intuire dal nome, non è altro che un'interfaccia per l'accesso alle statistiche con PHP!

 

 

Download e attivazione

È possibile scaricarla dal sito ufficiale del progetto. Il pacchetto .zip, del peso di soli circa 2 MB!, contiene alcuni files di esempio su come utilizzarla e il core (attualmente alla versione 3). A noi interessa quest'ultimo che andremo a copiare in una qualunque cartella del nostro sito, nel mio caso in quella per le librerie.

Ora mettiamo da parte files e codice e passiamo all'attivazione dell'API, procedura resa obbligatoria con l'avvento di questa nuova versione, infatti se utilizziamo la vecchia libreria (v. 1) nel momento dell'elaborazione dei risultati ci verrà restituito un bel errore 404:

Errore 404 Gapi

Dato che punta al seguente link: https://www.google.com/analytics/feeds/accounts/default:

Errore 404 https://www.google.com/analytics/feeds/accounts/default

Detto ciò colleghiamoci nella console per le API al seguente indirizzo, inseriamo i nostri dati di accesso, e accettiamo i termini di servizio dell'API che andremo a utilizzare.

Successivamente creiamo un nuovo progetto selezionando dal menù a tendina posizionato a sinistra la voce Create..., e all'apparizione di una finestra di dialogo inseriamo il nome che più desideriamo e per confermare clicchiamo su Create project.

Creazione di un nuovo progetto Analytics API

Apriamo la pagina Services, e della enorme lista di API che Google ci mette a disposizione, abilitiamo quella che a noi interessa: quella di Google Analytics:

Attivazione Analytics API

Una volta abilitata, apriamo Analytics API, cliccandoci su. Ci verrà mostrato un grafico con i dati relativi alle richieste che abbiamo effettuato, ne abbiamo al massimo 50.000/giorno, soglia alquanto difficile da superare. A noi interessa però, un'altra sezione: API Access, dove andremo ad annotare la chiave con cui potremo identificarci quando andremo a ottenere le statistiche.

API Access example

La zona con bordo rosso, è dove è scritta la chiave. Possiamo anche crearne una nuova cliccando su Generate new key..., eliminarla, o crearne una specifica per Android, o iOS, in caso di App che sfruttano questa API.

Come ultimo passo per la registrazione dobbiamo creare un ID OAuth 2.0, che ci consente di accedere a tutte le API che Google ci fornisce. cliccando sul vistoso pulsante color blu Create an OAuth 2.0 Client ID.....

Creazione ID OAuth 2.0

 Nella finestra di dialogo che ci comparirà dobbiamo immettere le informazioni generali del nostro "prodotto", che verranno mostrare quando andremo a loggare per ottenere l'accesso, quali:

  • Nome, 
  • Logo e 
  • Link della home page del sito.

Una volta immesse proseguiamo con Next.

Impostazioni ID OAuth 2.0

Nel nostro caso selezioniamo Web Application. Come hostname, immettiamo il link del nostro sito. Concludiamo la procedura con Create client ID.

Ora se torniamo al pannello riguardo l'accesso delle API nella console compariranno nuove informazioni che dovremmo tutte annotare tutte per essere utilizzate successivamente.

Informazioni ID OAuth 2.0Integrazione

Ora possiamo andare oltre e integrare la libreria nella nostra applicazione! Creiamo un nuovo file e chimiamolo per esempio ottieni_statistiche.php

Come prima cosa includiamo i files principali:

  • Google_Client.php,
  • Google_AnalyticsService.php.
require "librerie/gapi/Google_Client.php";
require "librerie/gapi/contrib/Google_AnalyticsService.php";

Successivamente inizializziamo la sessione, in modo che la libreria possa immagazinare il token di accesso, così da non doverci autenticare ogni volta che viene caricata la pagina:

session_start()

Ora veniamo all'inizializzazione della classe Google_Client(), per l'autenticazione, inserendo i dati annotati prima durante la creazione dell'ID per OAuth 2.0:

$client = new Google_Client();
	
$client->setApplicationName("Ginho");
$client->setClientId("XXXXXXXXXXX.apps.googleusercontent.com");
$client->setClientSecret("XXXXXXXXXXXXXXXXXXXXXXXX");
$client->setRedirectUri("http://www.ginho.it/ottieni_statistiche.php");
$client->setDeveloperKey("XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX");
$client->setScopes(array('https://www.googleapis.com/auth/analytics.readonly'));
	
// Permette che le API restituiscano un oggetto invece che un array multidimensionale.
$client->setUseObjects(true);

N.B come RedirectUri dobbiamo impostare il link a cui verremo reindizzati dopo il login, di default è /oauth2callback, ma se volessimo modificarlo per impostare il file con cui stiamo lavorando (ottieni_statistiche.php), clicchiamo Edit settings..., di fianco al "box" Client ID for web applications, e inseriamo il link che desideriamo:

Reindirizzamenti autorizzati Google API

Analizziamo il codice proposto in precedenza: inizializziamo la classe Google_Client, creando un oggetto $client, successivamente accediamo ai suoi metodi per impostare le informazioni che verrano visualizzate quando eseguiremo il login dell'applicazione, quali:

  • Nome di quest'ultima => setApplicationName(),
  • ID => setClientId(),
  • Codice segreto => setClientSecret(),
  • Url di reindirizzamento (vedere la nota precedente) => setRedirectUri(),
  • Chiave dello sviluppatore => setDeveloperKey(),
  • TIpo di richiesta, per dire a Google quale informazioni vogliamo ottenere dell'utente impostato  => setScopes().

Possiamo inoltre chiamare anche un altro metodo: setUseObjects(), che dice all'API di restituire successivamente degli oggetti al posto di array multidimensionali, in questo modo:

$client->setUseObjects(true);

Ora controlliamo se è impostato il parametro ($_GET["code"] per forza) con il codice di accesso nella querystring, e in caso affermativo procediamo al login e creiamo una sessione che conterrà il token precedentemente estratto. Infine tramite header(), reindirizziamo l'applicazione nella stessa pagina, una sorta di refresh. In questo blocco l'applicazione ci entrerà soltanto quando verrà premuto un pulsante che creeremo in seguito.

if (isset($_GET["code"])) {
	$client->authenticate();
	$_SESSION["token"] = $client->getAccessToken();
	header("Location: " . "http://" . $_SERVER["HTTP_HOST"] . $_SERVER["PHP_SELF"]);
}

Il login è completato ma se proviamo ad aggiornare la pagina, vediamo che perdiamo l'accesso, per ovviare a ciò, controlliamo se la sessione con il token è impostata e reinviamola al client, tramite setAccessToken(). Infatti noi non perdiamo la sessione, ma il login all'applicazione tramite OAuth, questo perchè necessita sempre una chiave d'accesso (per incrementare la sicurezza).

if(isset($_SESSION["token"])) $client->setAccessToken($_SESSION["token"]);

Ora procediamo all'inserimento di un link per avviare il meccanismo di login impostando la querystring code?=, dopo aver verificato che non è ancora impostato il token con getAccessToken(). In caso affermativo creiamo una nuova chiave di accesso tramite createAuthUrl() e mostriamo il pulsante. 

if ($client->getAccessToken() == false) {
	$url = $client->createAuthUrl();
	echo "Apri Google Analytics API!";
}

Quando clicchiamo sul pulsante ci si aprirà un popup simile alla seguente, dicendoci che la nostra applicazione potrà accedere alle nostre statistiche di Google Analytics, noi accettiamo e così ci siamo autenticati con successo!

Login API

if ($client->getAccessToken() == false) {
	$authUrl = $client->createAuthUrl();
	print "Connect Me!";
}

 

Altrimenti se siamo già loggati, procediamo all'estrazione dei dati vera e propria!

$analytics = new Google_AnalyticsService($client);
	
try {
	$risultati = $analytics->data_ga->get(
		"ga:" . $profileId, 
		"2013-08-27", 
		"2013-08-27", 
		"ga:visits"
	);

	if (count($risultato->getRows()) > 0) {
		$rows = $risultati->getRows();
		$visite = $rows[0][0];
	
		echo "Visite 27 Agosto 2013: " . $visite ."";
	} else {
		echo "Nessun risultato";
	}
} catch (apiServiceException $e) {
	echo "Errore API: " . $e->getCode() . " : " . $e->getMessage();
} catch (Exception $e) {
	echo "Errore generale: " . $e->getMessage();
}

Come prima cosa inizializziamo l'oggetto $analytics, istanziando la classe Google_AnalyticsService(), e dentro un blocco try / catch iniziamo la raccolta delle informazioni chiamando il metodo get(), passandogli come parametri:

  1. Il nostro ID del profilo di Google Analytics, sottolineo profilo e non l'ID dell'account, o della proprietà, perchè altrimenti se inseriamo questi ultimi ci verrà mostrato il seguente messaggio di errore, dicendoci che non abbiamo sufficienti permessi per ottenere i dati da noi voluti:

    (403) User does not have sufficient permission for this profile.

    Per trovare l'ID andiamo nella parte amministrativa di Google Analytics, cliccando sul pulsante Amministrazione in alto a destra, e clicchiamo su Visualizza impostazioni nella terza colonna.

    Visualizza profilo Google Analytics

    L
    'ID lo troveremo di fianco a ID Vista:

    ID Profilo Google Analytics
  1. La data iniziale del periodo che vogliamo analizzare,
  2. La data che stabilisce la conclusione del range (in questo caso la data attuale 27 Agosto 2013).
  3. Il tipo di dato da estrarre nel periodo impostato precedentemente, dalla documentazione ufficiale delle API è disponibile una lista completa. In questo esempio imposto ga:visitors, per ottenere le visite uniche del sito.
    Dobbiamo fare una distinzione tra: DIMENSIONS e METRICS per evitare di generare errori indesiderati. Le prime sono elementi quali sistema operativo, browser del visitatore, le seconde sono le opzioni con cui visualizzare le dimensions. Questo ci fa capire quante sono le combinazioni possibili di entrambi i fattori: un esagerazione!. In ogni caso la lista linkata prima differenzia questi due fattori e ci mostra quelle possibili. 

Successivamente dopo aver ottenuto i valori controllo se quest'ultimi sono vuoti, in caso affermativo mostro Nessun risultato!, altrimenti in caso negativo gli memorizzo nella variabile $rows con getRows(). Se stampassimo con print_r() il valore dell'array, otterremo una cosa simile:

Array
(
    [0] => Array
        (
            [0] => 53
        )

)

Così per estrarre il numero delle visualizzazioni facciamo 

$visite = $rows[0][0];

E infine le mostriamo!

 

2° esempio

 

In quest'altro esempio otteniamo le visite uniche browser, utilizzato dai nostri visitatori, molto utile per ottimizzare il sito in relazione ai dati degli utenti, dell'ultima settimana.

 Risultato:

Secondo esempio con browser e visite di una settimana Google Analytics API

Innanzitutto, partendo dall'esempio base precedentemente illustrato, dobbiamo modificare alcuni parametri nel metodo get():

  • La data, che come detto prima imposto per selezionare l'ultima settimana 2013-08-20 <=> 2013-08-27,
  • L'ultimo parametro opzionale, con cui impostiamo la dimensione, in questo caso ga:browser.

Il resto rimane intatto.

$risultati = $analytics->data_ga->get(
	"ga:" . $profileId, 
	"2013-07-20", 
	"2013-08-20", 
	"ga:visits",
	array(
		"dimensions" => "ga:browser"
	)
);

Il risultato di $rows->getRows();, sarà un array simile a quello di seguito mostrato:

Array
(
    [0] => Array
        (
            [0] => Android Browser
            [1] => 12
        )

    [1] => Array
        (
            [0] => Chrome
            [1] => 91
        )

    [2] => Array
        (
            [0] => Firefox
            [1] => 106
        )

    [3] => Array
        (
            [0] => Internet Explorer
            [1] => 12
        )

    [4] => Array
        (
            [0] => Maxthon
            [1] => 1
        )

    [5] => Array
        (
            [0] => Mozilla Compatible Agent
            [1] => 1
        )

    [6] => Array
        (
            [0] => Opera
            [1] => 8
        )

    [7] => Array
        (
            [0] => Safari
            [1] => 16
        )

    [8] => Array
        (
            [0] => SeaMonkey
            [1] => 1
        )

)

Nell'esempio impaginerò questi valori dentro una normale tabella, tramite un ciclo foreach (ideale per array multidimensionali come questo).

echo "
	";
					
	foreach ($rows as $key => $value) {
		echo "
		";
	}
					
	echo "	
Browser Visite
" . $value[0] . " " . $value[1] . "

";

Volessimo ordinare l'array in base alle visite, aggiungiamo l'elemento sort all'ultimo parametro, e assegniamoli come valore una dimension o una metric. Nell'esempio precedente uso ga:visits, per ordinarlo in ordine ascendente, mentre possiamo anteporre il segno meno (-) per ordinarlo in modo decrescente.

array(
	"dimensions" => "ga:city",
	"sort" => "-ga:visits"
)

Risultato:

Ordine decrescente visualizzazioni browser

 

3° Esempio

 

In questo esempio vediamo come ottenere lo stato o la città da dove provengono i nostri visitatori. Basta semplicemente modificare la dimension in ga:country...

$risultati = $analytics->data_ga->get(
	"ga:" . $profileId, 
	"2013-08-20", 
	"2013-08-27", 
	"ga:visits",
	array(
		"dimensions" => "ga:country"
	)
);

3° Esempio che mostra lo stato di provenienza dei visitatori

...o in ga:city per la città. 

Città visitatori Google Analytics API

 

4° Esempio e introduzione ai filtri

 

In questo ultimo esempio vediamo come filtrare i risultati in base una dimension o metric da noi definita, funzione molto utile che ci permette (vedi esempio precedente) di filtrare tutte le città di uno stato specifico, dato che prima venivano mostrate tutte.

La sintassi è la seguente:

ga:nome operatore espressione

Dove al posto di nome va inserita la metrica o la dimensione, a quello di operatore uno di questi se abbiamo impostato quest'ultima:

Operatore Codificato Esempio
== %3D%3D 

Estrae dati solamente per un determinato paese

filters=ga:country%3D%3DItaly

!= !%3D

Estrae dati se la città immessa nel filtro non è Ferrara:

filters=ga:city!%30Ferrara

=@ %3D!

Estrae dati se lo stato inserito contiene la stringa "ia":

filters=ga:country=@la 

!@ !@

Identico a quello precedente a parte il fatto che estrae dati se non contiene la stringa inserita:

filters=ga:country!@la

=~ %3D~

Estrae dati se l'espressione soddisfa l'espressione regolare inserita:

filters=ga:city%3D~%5EFe.* 

 

N.B: %5E corrisponde al carattere ^ codificato che definisce l'inizio dell'espressione

!~ !~

Estrare dati se non viene soddisfatta l'espressione regolare inserita:

filters=ga:city!~%5EFe.* 

altrimenti uno di questi per la metrica.

Operatore Codificato Esempio
== %3D%3D

Estrare dati se le visite sono uguali al numero stabilito:

filters=ga:visits%3D%3D200

!= !%3D

Estrae dati se le visite non corrispondono al numero stabilito:

filters=ga:visits!%3D200

> %3E

Estrae dati solamente se le visite sono maggiori di quelle impostate:

filters=ga:visits%3E200

>= %3E%3D

Estrae dati se le visite sono maggiori/uguali rispetto a quelle inserite:

filters=ga:visits%3E%3D200

< %3C

Estrae dati se le visite sono minori rispetto a quelle inserite:

filters=ga:visits%3C200

<= %3C%3D

Estrae dati se le visite sono minori/uguali rispetto a quelle inserite:

filters=ga:visits%3C%3D200

Questa funzione è estremamente potente, infatti possiamo anche concatenare più filtri, sempre a patto che siano compatibili tra di loro, con gli operatori booleani principali:

  • AND: Definito con un punto e virgola (;), viene dopo OR, e si può utilizzare per combinare dimensioni e metriche insieme: es. 

    ga:browser%3D%3DChrome;ga:operatingSystem%3D%3DWindows
     
  • OR Definito con la virgola (,) ha la precedenza sul primo e non va utilizzato combinando le due opzioni, ma solamente una alla volta: es.

    ga:browser%3D%3DChrome;ga:operatingSystem%3D%3DWindows,ga:operatingSystem%3D%3DMacintosh


?N.B: Se non vogliamo inserire i caratteri codificati manualmente, possiamo inserirli pure decodificati e passarli in pasto alla funzione urlencode() / urldecode(), che farà la stessa cosa. Non ne avremmo bisogno nel caso utilizzassimo questa libreria per JAVA

 

Ecco un esempio pratico dei filtri appena illustrati, selezionando le città Italiane con visite uniche maggiori di 15.

$risultati = $analytics->data_ga->get(
	"ga:" . $profileId, 
	"2013-08-20", 
	"2013-08-27", 
	"ga:visits",
	array(
		"dimensions" => "ga:city",
		"filters" => "ga:country%3D%3DItaly;ga:visits%3E15",
		"sort" => "-ga:visits",
	)
);

4° Esempio con filtri

Conclusioni

In questo articolo vi ho illustrato le funzionalità principali della versione 3 delle API Google Analytics, per integrare facilmente le statistiche direttamente sul nostro sito o pannello amministrativo per esempio. Chi utilizzava le vecchie versioni, si ritroverà più avantaggiato, dato che conoscerà i filtri, dimension e metric, in ogni caso all'inizio sarà un po' astruso imparare tutte le informazioni che ci serviranno, ma il procedimento una volta imparato, essendo puramente una cosa meccanica, è più semplice di quanto può sembrare!

Per qualunche dubbio/consiglio non esitare a scrivere un commento!

Ti potrebbero interessare

I più letti