Google Analytics API

Pourquoi utiliser Google Analytics ?

-  il enregistre bien plus d’informations que les statistiques de visites de SPIP, et offre des rapports bien plus détaillés.
-  gratuit
-  cela permet de désactiver le système de visites sur SPIP, qui affecte les performances de votre site, que ce soit lors de l’enregistrement ou de la consultation de rapports complexes.

Google Analytics offre des interfaces très flexibles pour consulter les statistiques. Pourquoi installer une librairie en PHP sur votre site ?

-  Vous pouvez utiliser les analytics dans vos squelettes.
-  Vous pouvez enregistrer certaines informations dans votre base de données, de manière automatisée.

Ainsi, avec ce plugin, vous pourrez accéder à des données Google Analytics dans vos squelettes, que ce soit pour afficher des informations sur votre site public ou créer des rapports personnalisés dans votre espace privé. Vous pourrez même enregistrer des statistiques dans votre base de données de manière automatisée. [1]

Nous allons présenter l’utilisation de ce plugin, ainsi que donner des conseils pour en tirer un plus grand parti.

Pourquoi NE PAS utiliser Google Analytics ?

La gratuité du service pour le webmaster provient du fait que toutes les informations collectées sont utilisées pour cibler les offres publicitaires.

Sachez que d’autres offres sont disponibles si vous souhaitez éviter le grand Google, tel que les stats open source Piwik (pour lesquelles il y a un plugin spip-piwik).

Installation

IMPORTANT : l’utilisateur qui va activer le plugin doit avoir un compte Google avec accès aux analytics du site. Nous considérons que vous êtes familier avec Google Analytics et que votre site est déjà associé à ce système. De plus, il faudra peut-être créer un compte Google Developer, afin de pouvoir créer une application. Je ne sais plus comment on fait car je l’ai fait il y a plusieurs années, mais cela n’est pas compliqué (merci de m’aider à mettre a jour cette documentation).

Il faut tout d’abord créer une application Google qui va permettre la consultation de ces analytics. Ensuite il faudra créer un token d’autorisation, qui sera transformé automatiquement par le plugin en token a durée de vie illimitée (Refresh Token).

Pour créer une application, il faut suivre les étapes de la section 1 de cette documentation. Je récapitule ici les étapes en Français :

1. Si vous ne possédez pas encore de projet Google API, créez un nouveau projet.

2. créez une application de type « web server » ou « web application ». Sélectionnez l’API « Google Analytics Reporting », en utilisant les données de l’utilisateur.

3. Créez des credentials (identifiants), en les nommant, et comme page de redirection (section « restrictions ») : http(s)://votredomaine/ecrire/?exec=oauth2callback.

NOTE : Si vous venez depuis la page de credentials, il faut sélectionner « Oauth Client ID » quand cela vous est demandé :

3. Si cela vous est demandé, la personnalisation de l’écran de connexion a peu d’importance. Mettez juste le minimum nécessaire (product name).

4. générez des codes d’accès à cette application et téléchargez le fichier json qui contient ces codes d’accès

NOTE : si vous souhaitez télécharger le json depuis la page de credentials, cliquez sur le lien a droite :

Il faut ensuite se rendre dans la page de configuration du plugin SPIP dans l’espace privé : /ecrire/ ?exec=configurer_google_analytics_api , et y enregistrer le contenu du fichier json.

L’identifiant de la vue de votre site sur Google Analytics peut être trouvé facilement dans le query explorer de Google Analytics.

Une fois toutes ces informations remplies, il ne reste qu’à générer un Token de connexion, dans la seconde partie de la page de configuration.

Durant la connexion, une page de transition va vous demander quel compte Google vous souhaitez utiliser (choisissez le compte qui a accès aux analytics de votre site). Une seconde étape va vous demander si vous autorisez l’application à avoir un accès en lecture a Google Analytics. Ceci est normal et vous pouvez accepter.

Pour tester si votre application fonctionne, rendez-vous sur cette page, où vous devriez voir les pages les plus consultées sur votre site : /ecrire/?exec=best_pages_skel

Utilisation

Tout d’abord, lorsque vous mettez en place un rapport, il est très pratique d’utiliser le query explorer pour comparer vos résultats.

De plus, la documentation de la fonction batchGet() vous apportera aussi beaucoup d’informations sur les paramètres à passer dans vos requêtes, notamment la syntaxe des filtres, de même que la page d’exploration des dimensions et metrics.

Un rapport d’analytics utilise (pour le moment) les paramètres suivants :

-  une ou plusieurs dimensions (valeurs associées aux pages)
-  une ou plusieurs metrics (quantités de mesure)
-  un ou plusieurs filtres (optionnel, aucun filtre par défaut)
-  une ou plusieurs périodes (optionnel, par défaut 7daysAgo -> yesterday)
-  un ordre de tri (optionnel)

D’autres paramètres existent dans l’API, et seront peut-être implémentés dans ce plugin à l’avenir.

IMPORTANT : A l’heure actuelle, les filtres fonctionnent avec l’opérateur logique « ET ». C’est à dire que le rapport ne contiendra que les résultats qui sont compatibles avec TOUS les filtres. De plus, les filtres ne s’appliquent qu’aux dimensions pour le moment.

1. Squelette SPIP

Afin d’afficher le résultat d’un rapport Google Analytics dans un squelette, il suffit de créer un tableau avec tous les paramètres du rapport, et y appliquer le filtre « get_analytics ». Vous pouvez jeter un oeil a un squelette exemple dans le répertoire du plugin : /prive/exec/best_pages_skel.html

Voici l’URL pour voir le resultat : /ecrire/?exec=best_pages_skel

Nous voyons ici deux rapports légèrement différents. Le premier est le filtre get_analytics appelé avec le paramètre true, qui indique qu’on veut le résultat dans un tableau HTML simple.

[(#GET{conf}|get_analytics{true})]

Dans le cas où vous voulez vous-même manipuler le rapport, vous pouvez faire comme le second appel, sans le paramètre true.

[(#GET{conf}|get_analytics)]

Ainsi le plugin retourne le rapport sous forme d’un tableau PHP, consultable dans le squelette avec la boucle DATA. Souvenez-vous bien que chaque ligne va contenir les dimensions en premier, puis les metrics, et dans l’ordre dans lequel les paramètres ont été déclarés.

2. Code PHP

Vous pouvez aussi créer un rapport directement en PHP, par exemple si vous voulez interagir avec des données non-accessibles depuis les squelettes, ou pour générer des rapports en tâche de fond via le job_queue de SPIP. Le principe est similaire à la version « squelette » : il suffit de créer un tableau avec les paramètres nécessaires, et passer ce tableau en paramètre à la fonction get_analytics().

$report = get_analytics($conf);

Un exemple d’utilisation (qui produit les mêmes rapports que l’exemple de type « squelette ») peut être trouvé dans le répertoire du plugin :

/exec/test_php_call.php

Voici l’URL pour voir le résultat :

/ecrire/?exec=test_php_call

Utilisation étendue

Afin de tirer le meilleur parti de ce plugin, il est fortement recommandé d’utiliser des variables personalisées dans vos pages pour Google Analytics.

Il est en effet intéressant d’indiquer à Google Analytics quelques informations supplémentaires, telles l’auteur d’un article, ou l’identifiant SPIP de l’objet de la page (article, rubrique, etc.).

Il est très facile de récupérer la liste des URLs les plus performants du site en terme de visites. Il n’est toutefois pas si simple de faire l’association entre ces URLs et les objets de votre site.

En revanche, si vous associez un identifiant à vos pages, grâce à une variable personnalisée, alors vous pourrez utiliser cet identifiant dans une boucle SPIP et exploiter cette information pour créer un bloc dans vos pages.

Voici une façon simple d’ajouter la variable id_article dans votre squelette d’article (dans la balise HTML « head », si possible) :

<script>
var ga_id_objet = "#ID_ARTICLE";
var ga_objet = "article";
</script>

Ensuite il vous suffira d’ajouter ces variables JS en tant que variables personnalisées dans la page de configuration de votre google analytics :

Et aussi, rajouter ces variables dans le code d’initialisation google analytics de vos squelettes.

ga('set', 'dimension1', ga_id_objet);
ga('set', 'dimension2', ga_objet);

Notre utilisation de ce plugin est très simple et intéressante a la fois : un bloc « Article les plus populaires », ou « trending articles », qui affiche les 10 articles du site les plus visités ces dernières 24-48h :

[(#SET{dimensions,[(#ARRAY{0,"ga:dimension1"})]})]
[(#SET{metrics,[(#ARRAY{0,[(#ARRAY{"expression","ga:pageviews","alias","Page Views"})]})]})]
[(#SET{dateRanges,[(#ARRAY{0,[(#ARRAY{"startDate","yesterday","endDate","today"})]})]})]
[(#SET{orderBys,[(#ARRAY{"FieldName","ga:pageviews","OrderType","VALUE","SortOrder","DESCENDING"})]})]
[(#SET{pageSize,10})]
[(#SET{filters,[(#ARRAY{0,[(#ARRAY{"dimensionName","ga:dimension2","operator","EXACT","expression","article"})]})]})]
[(#SET{conf,[(#ARRAY{"dimensions",[(#GET{dimensions})],"metrics",[(#GET{metrics})],"dateRanges",[(#GET{dateRanges})],"orderBys",[(#GET{orderBys})],"pageSize",[(#GET{pageSize})],"filters",[(#GET{filters})]})]})]

[(#SET{report,[(#GET{conf}|get_analytics)]})]

<BOUCLE_browse_report(DATA){source table, #GET{report}}>
	[(#SET{id_article,[(#VALEUR|table_valeur{0})]})]
        [(#SET{n_visites,[(#VALEUR|table_valeur{1})]})]
	<INCLURE{fond=bloc_article}{id_article=#GET{id_article}}>	
</BOUCLE_browse_report>

Ce code nous permet de récupérer la liste des 10 articles les plus visités, en demandant comme dimension la « dimension1 » (id_objet), comme mesure (metrics) les pageviews, et en nous assurant de filtrer les pages avec « dimension2 » (objet) = « article ». Le rapport va retourner un ensemble de lignes, dont la première valeur est la dimension (id_objet) et la seconde est le metrics (pageviews). Nous utilisons enfin cet id_article dans une boucle SPIP pour générer un bloc.