Google Analytics API Class

Cette classe vous permet de vous connecter à votre compte Google Analytics et de récupérer les données d'un profil particulier selon de multiples critères.

Note: Vous devez posséder un compte Google Analytics et avoir au moins un site disponible afin de pouvoir utiliser cette librairie.
Pour plus d'informations, http://www.google.com/intl/fr/analytics/index.html

Configuration requise

• PHP 5
• Extension PHP cURL

Initialiser la Classe

Comme la plupart des classes dans CodeIgniter, cette classe est initialisée depuis votre contrôleur en utilisant la fonction $this->load->library:

$this->load->library('ga_api');

L'objet pour accéder aux fonctions de la classe est $this->ga_api.
Vous devrez néanmoins ajouter certains paramètres de configuration, sans quoi la classe sera inutilisable (voir ci-dessous)

Configuration de la librairie

Avant de pouvoir effectuer une requête via l'API de Google Analytics, vous devez renseigner vos informations de compte. La méthode de chargement de la configuration est la même que pour les autres librairies de CodeIgniter. Vous pouvez donc soit passer les préférences directement depuis le contrôleur, soit depuis un fichier de configuration. Exemple d'informations pour vous connecter:

$this->load->library('ga_api');

$config['id'] = 'ga:00000000';
$config['email'] = 'google@email.com';
$config['password'] = 'google_password'

$this->ga_api->initialize($config);

$this->ga_api->login();

Le code ci-dessus permet de charger la class avec la configuration du compte. login() effectue une simple connexion à l'API avec votre compte.

Préférences

Le tableau ci-dessous revient sur les préférences disponible pour la configuration de vos requêtes

Il est possible de stocker ces préférences dans un fichier de configuration. Vous devrez alors créer un fichier nommé ga_api.php dans le répertoire config/ de votre application, puis y placer votre Array $config Dans ce cas, vous n'aurez pas besoin de d'utiliser la fonction $this->ga_api->initialize, le ficher sera lu automatiquement lors du chargement de la librairie.

Préférence	Valeur par défaut	Options	Description	Obligatoire
profile_id		ga:(string)	(string) représente votre identifiant de profil Google Analytics. Cette préférence est obligatoire afin de pouvoir indiquer à l'API depuis quel profil. Vous le trouverez dans les "Paramètres de profil" de votre site	Oui
email		(Email valide)	L'email de votre compte Google	Oui
password			Votre mot de passe de compte Google	Oui
source_name		(nom de votre site)	Affiche le nom de votre site dans le header de la requête lors de la connexion à votre compte Google	Non
login_home	https://www.google.com/ accounts/ClientLogin		l'URL de connexion au compte Google	Oui
accounts_home	https://www.google.com/ analytics/feeds/accounts /default		l'URL de récupération des données de profils associés à votre compte	Oui
data_home	https://www.google.com /analytics/feeds/data?		l'URL de récupération des données de type 'data'	Oui
debug	FALSE	TRUE/FALSE (boolean)	Cette option effectue un 'echo' de l'url construite par la librairie pour la récupération des 'data'. Ceci permet de contrôler les options envoyées à l'API	Non
summary	TRUE	TRUE/FALSE (boolean)	Ajoute des données globales aux requêtes de type 'data' dans l'Array ou l'Objet. Ces données sont accessibles depuis l'index $data['summary']. Voir "Afficher le résumé des requêtes" pour plus de détails	Non
prettyprint	FALSE	TRUE/FALSE (boolean)	Cette option permet de choisir si les données XML doivent être lisibles (mise en page) ou non	Non
max_results	100	INT	Spécifier le nombre de résultat par requête	Non
start_index	1	INT	Spécifier ou l'index de départ des résultats	Non
start	1 month ago	timestamp ou strtotime	Spécifier la date de départ	Non
end	yesterday	timestamp ou strtotime	Spécifier la date de fin	Non
cache_data	FALSE	TRUE/FALSE (boolean)	Défini si l'on souhaite faire une copie locale du fichier 'data' demandé. La copie est le fichier xml brut, dont le nom (encodé md5) est basé sur les paramètres de l'url de la requête (visible via l'option "debug"). Si une requête identique au fichier du cache est effectuée, la librairie prendra les informations contenu dans le fichier local à la place d'effectuer une nouvelle requête à l'API. Ceci permet de gagner beaucoup de temps sur le chargement de vos pages	Non
cache_folder		(chemin vers le dossier de cache)	Spécifier le chemin 'système' dans lequel vos fichiers cache seront stockés. Le dossier doit posséder les droits en écriture	Si "cache_data" est TRUE
cache_ext	xml		Spécifier l'extension sous laquelle les fichiers de cache seront sauvegardés et lus	Non
clear_cache	None	[date ou size], [imestamp/strtotime ou taille en octets]	Cette préférence doit être spécifier sous forme d'Array (non associatif). Permet de nettoyer les fichiers de cache soit antérieurs à une date spécifique, soit lorsque la taille du cache est supérieure à la taille indiqué. Voir "Nettoyer le cache"	Non

Définir l'expiration du cache

Il est possible d'indiquer à la classe comment effacer les fichiers stockés dans le cache_folder. Si cache_data est défini sur TRUE, la classe vérifiera le cache à chaque initialisation:

$config['clear_cache'] = array('key', 'value');

Par date

Vous pouvez spécifier une date à partir de laquelle tous les fichiers antérieurs à cette date seront supprimés:

$config['clear_cache'] = array('date', '1 day ago');

La valeur peut être soit un string compatible avec la fonction strtotime, soit un timestamp unix.

Par Taille

Spécifier un taille maximale du cache aura pour conséquence de supprimer tous les fichiers une fois que leurs tailles additionnées sera supérieure à la valeure indiquée (exprimée en octets):

$config['clear_cache'] = array('size', '20971520');

L'exemple indique que la taille maximale du cache ne doit pas excéder les 20 Mo.

Fonctions associées aux paramètres de classe

$this->ga_api->initialize()

Initialisation de la classe via un array associatif de configuration.

$this->ga_api->initialize($config);

Si vous n'utilisez pas de fichier de configuration, il est également possible de passer la configuration faite dans le contrôleur au moment de la lecture de la librairie:

$this->load->library('ga_api', $config);

$this->ga_api->clear()

Permet à tout moment de réinitialiser tous ou certains objets de la classe.

1. Réinitialisation complète de tous les paramètres (configuration et ceux générés par les fonctions associées aux données):

$this->ga_api->clear();

2. Réinitialisation de certains objets générés par les fonctions associées aux données. Utile si vous faites plusieurs requêtes dans une même fonction du contrôleur :

$this->ga_api->clear('limit');

// Réinitialise l'objet limit à sa valeur par défaut, à savoir 100 Paramètres acceptés:

• Tous les "Fonctions de production de requêtes" exceptées les $this->ga_api->get*
• login

$this->ga_api->clear_cache()

Permet à tout moment de nettoyer le cache si celui-ci a été activé. Si aucun paramètre n'est passé, l'ensemble du cache sera supprimé. La fonction accepte un array avec les paramètres que vous pouvez trouver à la section "Définir l'expiration du cache:"

$params = array ('date','1 week ago');

$this->ga_api->clear-cache($params);

// Supprime les fichiers plus vieux d'une semaine

Fonctions associées aux connexions

$this->ga_api->login()

Au travers de cette fonction, la classe s'identifie au serveur Google via les paramètres de connexion que vous aurez lu via l'initialisation de la classe.

Note: Vous n'avez pas besoin d'appeler cette fonction dans vos requêtes mis à part pour la fonction $this->ga_api->load_accounts()

Retourne FALSE en cas d'échec.

$this->ga_api->clear_login_data()

Lors de la première initialisation, la classe stocke les paramètres de connexion en session (via la librairie dédiée de CodeIgniter), ceci afin de profiter d'un gain non négligeable sur le temps d'affichage en évitant de s'authentifier à chaque requête. Si vous devez changer de profil, invoquez cette fonction afin supprimer ces informations de la session.

La fonction $this->ga_api->clear('login') est un équivalent.

$this->ga_api->get_accounts()

Cette fonction récupères les comptes Analytics de votre compte Google. Vous devrez être dans un premier temps authentifié avant d'utiliser cette fonction.

Exemple de lecture d'un compte:

$accounts = $this->ga_api->login()->get_accounts();

En cas d'échec de récupération des comptes, accounts sera égal à FALSE, sinon:

Array
(
	[segments] => stdClass Object
	    (
	        [gaid::-1] => All Visits
	        [gaid::-2] => New Visitors
	        [gaid::-3] => Returning Visitors
	    	(...etc)
	    )
	[monsite.com] => stdClass Object
	    (
	        [title] => monsite.com
	        [tableId] => ga:00000000
	        [accountId] => 1111111
	        [accountName] => Mon site
	        [profileId] => 00000000
	        [webPropertyId] => UA-1111111-1
	    )
)

Si vous passez le paramètre FALSE à la fonction, celle-ci retournera un Array.

Fonctions de configuration de requêtes

$this->ga_api->dimension()

Spécifier la ou les dimensions (3 au maximum) de la requête. Voir La documentation de référence pour les critères disponibles. Il n'est pas nécessaire de spécifier le préfix 'ga:', la fonction s'occupera de l'ajouter elle-même.

1. Multiples dimensions avec un String comme argument:

$this->ga_api->dimension('source, medium');

// produit: &dimensions=ga:source,ga:medium

2. Multiples dimensions avec un Array comme argument:

$dimensions = array('source', 'medium');

$this->ga_api->dimension($dimensions);

// produit &dimensions=ga:source,ga:medium

$this->ga_api->metric()

Spécifier le ou les metrics de la requête. Voir La documentation de référence pour les critères disponibles. Il n'est pas nécessaire de spécifier le préfix 'ga:', la fonction s'occupera de l'ajouter elle-même.

1. Multiples metrics avec un String comme argument:

$this->ga_api->metric('entrances, bounces');

// produit: &metrics=ga:entrances,ga:medium

2. Multiples dimensions avec un Array comme argument:

$metrics = aray('entrances', 'bounces');

$this->ga_api->metric($dimensions);

// produit &metrics=ga:entrances,ga:medium

$this->ga_api->when()

Correspond aux dates de début et de fin pour créer un interval à partir duquel les données vont être produites. Si cette fonction n'est pas invoquée, les données seront sélectionnées dans un interval d'un mois, à partir du jour précédent la requête:

$this->ga_api->when('start_date', 'end_date);

La fonction accepte 1 ou 2 paramètres. si le second (end_date) n'est pas indiqué, alors celui-ci correspondra au jour précédent la requête.

1. Exemple avec des string compatibles strtotime:

$this->ga_api->when('01 May 2009', '05 June 2010');

// produit: &start-date=2009-05-01&end-date=2010-06-05

2. Exemple avec des timestamp:

$this->ga_api->when(1275688800, 1241128800);

// produit: &start-date=2009-05-01&end-date=2010-06-05

$this->ga_api->filter()

Permet d'assigner un filtre pour une dimension ou un metric.

Note: Les opérateurs ne sont pas identiques pour filtrer une dimension ou un metric, voir la documentation de référence

1. Exemple d'exclusion des données relative à Google pour la dimension 'source':

$this->ga_api->filter('bounces', '>', '200');

// produit: ga:bounces%3E200

$this->ga_api->and_filter()

Identique à la fonction $this->ga_api->filter(), permet d'additionner des filtres supplémentaires

$this->ga_api->and_filter('source', '!=', 'google');

// produit: ;&filters=ga:source%21%3Dgoogle

$this->ga_api->or_filter()

Identique à la fonction $this->ga_api->filter(), permet de choisir des filtres supplémentaires

$this->ga_api->or_filter('medium', '==', 'organic');

// produit: ,ga:medium%3D%3Dreferral

Il est possible de chainer ces fonctions (vous n'êtes pas limité par le nombre de and et de or):

$this->ga_api->filter('bounces', '>', '200')
	     ->and_filter('source', '!=', 'google')
	     ->and_filter('source', '!=', 'yahoo')
	     ->or_filter('medium', '==', 'organic');

// produit: &filters=ga:bounces%3E200;ga:source%21%3Dgoogle;ga:source%21%3Dyahoo,ga:medium%3D%3Dorganic

$this->ga_api->segment(int)

Spécifier un segment prédéfini. Par défaut, chaque compte possède une suite de segments allant de -1 à -12. A partir de l'interface web de Google Analytics, il est possible d'appliquer des segments personnalisés. L'utilisation des segments avec cette librairie et très pratique dans la mesure ou il est possible de modifier le comportement des segments sans modifier le code de votre application. Voir la documentation de référence

Combinaison d'un segment avec une dimension et un metric:

$this->ga_api->segment(-12)->dimension('source')->metric('visits, pageviews');

// produit:&dimensions=ga:source&metrics=ga:visits,ga:pageviews&segment=gaid::-12

$this->ga_api->dsegment()

Permet de créer des segments "à la volée" au lieu d'utiliser des segments prédéfinis. Fonctionnant sur le même principe que les filtre, une vidéo de présentation des segments dynamiques est proposée sur la documentation de référence

$this->ga_api->dsegment('medium', '==', 'referral');

// produit: &segment=dynamic::ga:medium%3D%3Dreferral

$this->ga_api->and_dsegment()

Fonctionne sur le même principe que pour les filtre, avec la même syntaxe.

$this->ga_api->dsegment('source', '==', 'google')->and_dsegment('country', '!=', 'France');

// produit: &segment=dynamic::ga:source%3D%3Dgoogle;ga:country%21%3DFrance

$this->ga_api->or_dsegment()

Fonctionne sur le même principe que pour les filtre, avec la même syntaxe.

$this->ga_api->dsegment('source', '==', 'bing')->or_dsegment('source', '==', 'yahoo');

// produit: &segment=dynamic::ga:source%3D%3Dbing,ga:source%3D%3Dyahoo

$this->ga_api->sort_by()

Controle l'ordre d'apparition des données. Si cette fonction n'est pas utilisé, les résultats sont triés en ordre descendant des valeurs metrics. Si un second paramètre est passé, la fonction tri en ordre ascendant

1. Exemple de tri en ordre descendant

$this->ga_api->sort_by('source');

// produit: &sort=ga:source

1. Exemple de tri en ordre ascendant

$this->ga_api->sort_by('source', true);

// produit: &sort=-ga:source

$this->ga_api->limit()

Limite le nombre de résultats à récupérer. Si cette fonction n'est pas utilisée dans votre requête, la limite est automatiquement définie à 100 résultats.

Note: A l'heure actuelle, google limit le nombre à 1000 résultats simultanés par requêtes

$this->ga_api->limit(25);

// produit: &max-results=25

$this->ga_api->offset()

Définir le début de l'index des résultats. Associé à limite, cette fonction est utile pour la pagination. Si la fonction n'est pas utilisée, la valeur par défaut est 1.

Note: Les index ne débutent pas à 0, mais 1. pensez à en tenir compte si vous utiliser la pagination dans CodeIgniter

$this->ga_api->offset(10);

// produit: &start_index=10

Fonctions de production de requêtes

les fonctions suivantes acceptent toutes comme paramètre un chemin vers un fichier XML valide. Dans ce cas, vous pouvez directement convertir le fichier XML sans passer par les autres fonctions:

$file = '/home/www/files/report.xml';

$this->ga_api->get_object($file);

$this->ga_api->get()

Retourne les données XML brutes.

$this->ga_api->get_array()

Retourne les données sous forme d'array associatifs

Exemple pour récupérer les 2 pays qui génèrent le plus de visites sur le mois passé:

$this->ga_api->dimension('country')
		->metric('visits, pageviews')
		->filter('country', '!=', '(not set)')
		->limit(2);

$array = $this->ga_api->get_array();

// array retourne:

[France] => Array
    (
        [visits] => 15757
        [pageviews] => 51728
    )

[United States] => Array
    (
        [visits] => 917
        [pageviews] => 1819
    )

$this->ga_api->get_object()

Retourne les données sous forme d'objets
Exemple pour récupérer les 2 pays qui génèrent le plus de visites sur le mois passé:

$this->ga_api->dimension('country')
		->metric('visits, pageviews')
		->filter('country', '!=', '(not set)')
		->limit(2);

$object = $this->ga_api->get_object();

// object retourné:
    
[France] => stdClass Object
    (
        [visits] => 15757
        [pageviews] => 51728
    )

[United States] => stdClass Object
    (
        [visits] => 917
        [pageviews] => 1819
    )

Afficher le résumé des requêtes

Si le paramètre summary est défini comme TRUE, chaque requête possèdera un Array ou Objet (en fonction des methodes ci-dessus) supplémentaire accessible en dehors des boucles.

L'index d'accès est nomé 'summary'. Si par exemple vous faite la même requête $this->ga_api->get_object() ci-dessus:

// object retourné:

[summary] => stdClass Object
   (
       [startDate] => 2010-05-29
       [endDate] => 2010-06-28
       [totalResults] => 117
       [startIndex] => 1
       [itemsPerPage] => 2
       [metrics] => stdClass Object
           (
               [visits] => 23146
               [pageviews] => 70949
           )
    )

[France] => stdClass Object
    (
        [visits] => 15757
        [pageviews] => 51728
    )

[United States] => stdClass Object
    (
        [visits] => 917
        [pageviews] => 1819
    )