Google Analytics, il noto servizio gratutio di statistiche per siti web cui abbiamo dedicato un'intera guida, ha un completo set di API che permettono di recuperare (quasi) tutti i dati generati dal servizio e integrarli nelle proprie applicazioni. Per chi utilizza PHP ci sono divrsi librerie o pacchetti di script che offrono un'interfaccia semplificata per l'accesso alle API. Due, in particolare, sono quelle più utilizzate: la GAPI - Google Analytics API PHP Interface e la libreria ufficiale creata da Google (la Google APIs Client Library for PHP).
La GAPI, una delle scelte più utilizzate, soprattutto per via del più semplice sistema di autenticazione, non è stata aggiornata per supportare la versione 3 delle API di Google Analytics rilasciate lo scorso dicembre e, anche se compatibile in parte con le API in versione 2.4 che continueranno a funzionare, non permette di sfruttare tutte le novità che verranno introdotte.
È bene dunque, per chi si avvicina solo adesso a questo argomento, cominciare con l'usare da subito la libreria di Google. In questo articolo vedremo come creare un semplice script in PHP che ci permetta di ricavare le visite e le pagine viste del nostro sito e pubblicarle in una tabella. In articoli che seguiranno vedremo invece configurazioni più approfondite.
Il processo si compone sostanzialmente di due passi: la creazione di un service object e l'interrogazione del service object per recuperare i dati. Il service object non è altro che un'interfaccia registrata nella console API di Google che permette l'accesso e l'autenticazione di un utente utilizzando lo standard OAuth 2.0.
Per utilizzare lo script è necessario naturalmente scaricare la libreria e caricarla nel proprio server. Da notare che useremo le cosiddette API Reporting, dedicate all'interrogazione del servizio. Chi volesse invece gestire account e permessi dovrebbe utilizzare le Management API.
Il codice che proponiamo fa ampiamente uso degli esempi creati da Google nella documentazione ufficiale.
Passo 1: creare il service object
La prima cosa da fare è registrare il service object nella console API di Google. Ciò si esegue creando un'applicazione per lo specifico servizio che si vuole utilizzare. Nel nostro esempio partiremo da un nuovo account Google che accede per la prima volta alla console API.
Portatevi all'indirizzo https://code.google.com/apis/console/#access ed entrare con il vostro Google account. Se è la prima volta che accede alla console verrà visualizzata la seguente pagina:
Fate clic sul pulsante Create project... e attivate le API di Google Analytics facendo clic sul pulsante OFF accanto alla voce Analytics API e accettando le regole del servizio che vengono visualizzate. Il servizio si dovrebbe attivare mostrando, al posto della parola OFF, la parola ON.
Per creare l'applicazione vera e propria fate clic sulla voce API Access sulla colonna di sinistra (punto 1 della figura sopra) e poi sul pulsante blu Create an OAuth 2.0 client ID....
Nella finestra che compare sarà necessario fornire il nome dell'applicazione (campo Product Name) e un eventuale indirizzo al logo (campo Product Logo). Impostate queste informazioni, fate clic sul pulsante Next.
Nella finestra che segue, lasciate l'impostazione predefinita per Application Type (deve essere Web Application), modificate la voce Your Site hostname facendola corrispondere al dominio in cui caricherete lo script PHP con cui si avrà l'accesso alle API, fate clic sul link more options e nel campo Authorized Redirect URIs indicate l'indirizzo esatto dello script PHP (che noi abbiamo chiamato gaphp.php). Se non conoscete con esattezza questa ultima opzione, lasciate l'impostazione predefinita: sarà possibile modificarla in seguito. Fate clic sul pulsante Create client ID.
Nella pagina che sarà mostrata troverete due tabelle: in quella chiamata Client ID for web applications ci saranno le informazioni relative all'applicazione appena creata; nella tabella Simple API Access ci saranno invece le informazioni generali relative all'account da utilizzare quando non è necessario recuperare dati di uno specifico utente. Nella configurazione del nostro script avremo bisogno in particolare delle voci: Client ID (1 in figura), Client secret (2) e API key (3), oltre che dell'indirizzo Redirect URIs (4). Facendo clic sui link Reset client secret e Generate new key (5) sarà possibile generare nuovi valori, disabilitando quelli vecchi.
L'applicazione è creata. A questo punto dobbiamo configurare lo script.
Passo 2: creazione dello script
Abbiamo suddiviso lo script che interrogherà il database di Google Analytics in tre parti. Alla fine di questo articolo mostreremo il codice completo. La prima parte è quella con cui si impostano le credenziali per il collegamento e si gestisce la logica dell'autenticazione. Nella seconda parte vedremo come recuperare i dati di cui abbiamo bisogno e nella terza formatteremo questi dati e li mostreremo nella pagina.
Naturalmente sarà necessario, come indicato nella pagina precedente, aver già caricato la libreria delle API di Google nel proprio sito.
Parte 1: autenticazione
Il codice per l'autenticazione è il seguente:
//Includo la libreria delle API di Google
require_once 'google-api-php-client/src/apiClient.php';
require_once 'google-api-php-client/src/contrib/apiAnalyticsService.php';
//Avvio della sessione
session_start();
$client = new apiClient();
$client->setApplicationName('Hello Analytics API Sample');
//ID del profilo da interrogare
$tableId = 'ga:->xxxx';
//Informazioni account
$client->setClientId('-> Client ID');
$client->setClientSecret('-> Client Secret');
$client->setRedirectUri('-> Redirect URIs');
$client->setDeveloperKey('-> API key');
$client->setScopes(array('https://www.googleapis.com/auth/analytics.readonly'));
$client->setUseObjects(true);
//Recupero del token
if (isset($_GET['code'])) {
$client->authenticate();
$_SESSION['token'] = $client->getAccessToken();
$redirect = 'http://' . $_SERVER['HTTP_HOST'] . $_SERVER['PHP_SELF'];
header('Location: ' . filter_var($redirect, FILTER_SANITIZE_URL));
}
if (isset($_SESSION['token'])) {
$client->setAccessToken($_SESSION['token']);
}
if (!$client->getAccessToken()) {
$authUrl = $client->createAuthUrl();
print "<a class='login' href='$authUrl'>Autenticati!</a>";
//esecuzione della funzione
} else {
$analytics = new apiAnalyticsService($client);
$results = queryCoreReportingApi ($analytics, $tableId);
getFormattedResults($results);
}Le righe alla sezione "Informazioni account", devono essere personalizzate indicando le credenziali specificate. Le credenziali si recuperano dalla console API di Google come evidenziato dalla figura 5.
La variabile $tableId = 'ga:62208825' della sezione "ID del profilo da interrogare" dovrà contenere l'ID del profilo che si desidera interrogare. L'id può essere idetificato facilmente a partire dall'URL del rapporto mostrato nell'interfaccia, come mostrato in figura:
Parte 2: interrogazione del servizio
La seconda parte dello script comprende la funzione di interrogazione del servizio Google Analytics.
function queryCoreReportingApi(&$analytics, $tableId) {
$optParams = array(
'dimensions' => 'ga:source,ga:keyword',
'sort' => '-ga:visits,ga:keyword',
'filters' => 'ga:medium==organic',
'max-results' => '25');
return $analytics->data_ga->get(
urldecode($tableId),
'2012-07-15',
'2012-07-30',
'ga:visits',
$optParams);
}La funzione esegue due diverse istruzioni. La prima consiste nel salvare nella variabile $optParams un array in cui sono salvate le dimensioni da interrogare ('dimensions' => 'ga:source,ga:keyword': le sorgenti di traffico e le parole chiave usate per raggiungere il sito), il tipo di ordinamento da utilizzare ('sort' => '-ga:visits,ga:keyword': il numero di visite in ordine decrescente e, in seconda battuta, le parole chiave in senso crescente), i filtri da applicare alle dimensioni ('filters' => 'ga:medium==organic': solo le visite organiche) e il numero massimo di risultati da visualizzare ('max-results' => '25': 25).
La seconda istruzione esegue la vera e propria interrogazione sfruttando la libreria di Google Analytics. Oltre ad includere i parametri inclusi nella variabile $optParams, l'istruzione imposta l'account sul quale eseguire l'interrogazione (urldecode($tableId)), l'intervallo di date da interrogare ('2012-07-15' e '2012-07-30') e la metrica da recuperare ('ga:visits').
Per conoscere le dimensioni e le metriche che si possono interrogare si può fare riferimento alla reference messa a punto da Google.
Parte 3: formattazione dei dati
La funzione queryCoreReportingApi restituisce un'array contenente diverse informazioni: i dati richiesti, il tipo di interrogazione, le tabelle su cui è stata eseguite l'interrogazione e così via. Per renderli intellegibili è necessario formattarli in qualche modo. La funzione indicata qui sotto si preoccupa di formattare i dati recuperati dalla funzione precedente in una tabella in formato HTML.
function getFormattedResults($results) {
$profileName = $results->getProfileInfo()->getProfileName();
$output = '<h3>Results for profile: '
. htmlspecialchars($profileName, ENT_NOQUOTES)
. '</h3>';
if (count($results->getRows()) > 0) {
$table = '<table>';
// Header della tabella
$table .= '<tr>';
foreach ($results->getColumnHeaders() as $header) {
$table .= '<th>' . $header->getName() . '</th>';
}
$table .= '</tr>';
// Righe della tabella
foreach ($results->getRows() as $row) {
$table .= '<tr>';
foreach ($row as $cell) {
$table .= '<td>'
. htmlspecialchars($cell, ENT_NOQUOTES)
. '</td>';
}
$table .= '</tr>';
}
$table .= '</table>';
} else {
$table = '<p>No results found.</p>';
}
echo $output . $table;
}Il codice completo
Ecco il codice completo del nostro script.
<?php
//Includo la libreria delle API di Google
require_once 'google-api-php-client/src/apiClient.php';
require_once 'google-api-php-client/src/contrib/apiAnalyticsService.php';
//Avvio della sessione
session_start();
$client = new apiClient();
$client->setApplicationName('Hello Analytics API Sample');
$tableId = 'ga:xxxx';
//Informazioni account
$client->setClientId('Client ID');
$client->setClientSecret('Client Secret');
$client->setRedirectUri('Redirect URIs');
$client->setDeveloperKey('API key');
$client->setScopes(array('https://www.googleapis.com/auth/analytics.readonly'));
$client->setUseObjects(true);
//Recupero del token
if (isset($_GET['code'])) {
$client->authenticate();
$_SESSION['token'] = $client->getAccessToken();
$redirect = 'http://' . $_SERVER['HTTP_HOST'] . $_SERVER['PHP_SELF'];
header('Location: ' . filter_var($redirect, FILTER_SANITIZE_URL));
}
if (isset($_SESSION['token'])) {
$client->setAccessToken($_SESSION['token']);
}
if (!$client->getAccessToken()) {
$authUrl = $client->createAuthUrl();
print "<a class='login' href='$authUrl'>Autenticati!</a>";
//esecuzione della funzione
} else {
$analytics = new apiAnalyticsService($client);
$results = queryCoreReportingApi ($analytics, $tableId);
getFormattedResults($results);
}
//interrogazione del servizio
function queryCoreReportingApi(&$analytics, $tableId) {
$optParams = array(
'dimensions' => 'ga:source,ga:keyword',
'sort' => '-ga:visits,ga:keyword',
'filters' => 'ga:medium==organic',
'max-results' => '25');
return $analytics->data_ga->get(
urldecode($tableId),
'2012-07-15',
'2012-07-30',
'ga:visits',
$optParams);
}
//formattazione dei risultati
function getFormattedResults($results) {
$profileName = $results->getProfileInfo()->getProfileName();
$output = '<h3>Results for profile: '
. htmlspecialchars($profileName, ENT_NOQUOTES)
. '</h3>';
if (count($results->getRows()) > 0) {
$table = '<table>';
// Header della tabella
$table .= '<tr>';
foreach ($results->getColumnHeaders() as $header) {
$table .= '<th>' . $header->getName() . '</th>';
}
$table .= '</tr>';
// Righe della tabella
foreach ($results->getRows() as $row) {
$table .= '<tr>';
foreach ($row as $cell) {
$table .= '<td>'
. htmlspecialchars($cell, ENT_NOQUOTES)
. '</td>';
}
$table .= '</tr>';
}
$table .= '</table>';
} else {
$table = '<p>No results found.</p>';
}
echo $output . $table;
}
?>