Matomo/Fonctionnement

Cette partie plus technique a pour but de fournir une présentation du fonctionnement de l'application Piwik. Cette partie sera utile aux curieux et aux personnes désireuses de modifier Piwik selon leur besoin, pour par exemple ajouter de nouvelles fonctionnalités. Il est conseillé de contacter l'auteur avant d'essayer de programmer quelconque nouveauté, afin de discuter avec l'équipe de développement (qui a une très bonne connaissance de l'ensemble de l'application) de la meilleure solution technique à utiliser.

Matomo

Version imprimable

[ Modifier le sommaire ]

Fonctionnalités

Traductions

Arborescence et fichiers

Vous trouverez ci-dessous une rapide description des fichiers et répertoires de Piwik. Cela permettra aux personnes désirant personnaliser Piwik d’avoir une vision globale de l’architecture de l’application.

index.php : fichier principal de Piwik où est géré l'affichage des différentes rubriques de statistiques
Piwik.js : code javascript principal, appelé par le court code javascript situé sur les pages du site
Piwik.php : fichier appelé par le code Javascript qui permet l'enregistrement dans la base de données des logs des visiteurs
login.php : fichier permettant la connexion via les sessions php
config.php : fichier crée dynamiquement qui contient les informations sur la configuration générale de l'application : nombre de sites installés, login/mot de passe, adresse du Piwik sur le serveur, type de protection (statistiques ou seulement administration), affichage des graphiques, et affichage ou non du logo
configX.php : fichier crée dynamiquement qui contient toutes les informations sur l'accès à la base de données (identifiants, serveur, noms des tables). Contient aussi les paramètres GET à ne pas prendre en compte
langdispos.php : fichier crée dynamiquement qui contient les noms et fichiers des langues disponibles, ainsi que les noms et contacts des traducteurs
nomsites.php : fichier crée dynamiquement qui contient les noms et adresses des sites Internet configurés dans Piwik
styles.php : contient les styles CSS de Piwik (conformes à la norme CSS2)
version.php : contient le numéro de version
docs/
- changelog : fichier journal des changements mineurs & majeurs entre les différentes versions depuis la création de Piwik
- licence et licence_fr : licence GNU/GPL français (licence_fr) et anglais (license)
- readme : rapides explications et redirection vers cette présente documentation
- documentation.htm : cette présente documentation au format HTML (format PDF disponible sur le site officiel de Piwik)
graphs/
- graph_*.php : fichiers générant les graphiques automatiquement (sélection base de données, formatage des résultats, routines JPGraph pour construction des images)
- jpgraph_*.php : fichiers contenant toutes les fonctions et classes pour la génération dynamique des images. JPGraph est une puissante librairie distribuée sous license QPL 1.0 (cf description JPGraph).
- tri_graph.php : fichier de traitement des tableaux issus de la sélection de la base de données afin de correctement les formater et les trier
- config_graph.inc.php : variables utilisées dans la génération des graphiques (dimensions, couleurs, polices, tailles, etc.)
- graphs/fonts/ (répertoire contenant les polices utilisées dans la génération des graphs)
- graphs/maps/ (répertoire contenant les cartes utilisées pour la génération des mappemondes dynamiques, ainsi que la barre indiquant les couleurs en fonction des pourcentages)
images/
logos/ : logos de Piwik sélectionnables pour l'affichage sur les sites internet audités. Les contributions des utilisateurs sont régulièrement ajoutées à ce répertoire et automatiquement pris en compte dans la pop-up de sélection des logos
browsers/ : logos des navigateurs
os/ : logos des systèmes d'exploitation
flags/ : logos des pays (images des drapeaux de tous les pays)
include/
- adminconfig.php : fichier qui gère la rubrique administration et configuration
- archiver_jour.php : fonction d’archivage d’un jour donné
- archiver_periode.php : fonctions d’archivage d’une période donnée ; fonctions d’archivage automatique d’une semaine et d’un mois
- calc_affluents.php : calcule les tableaux de données pour les affluents
- connect.php : connexion et sélection MySQL
- coord_pays.php : coordonnées des labels des noms de pays pour l'écriture sur la mappemonde
- footer.php : fichier qui contient le bas de page html des pages générées
- functions.php : fonctions php nécessaires à l’affichage et la configuration/installation
- functions_disp.php : fonctions utilisées dans l'affichage de données à l'écran
- functions_phpmv.php : fonctions utilisées pour l'enregistrement des logs des visiteurs
- header.php : contient les meta-tags, balises d’ouverture de page, etc.
- install.php : fichier qui gère l'installation
- list_logos.php : pop-up dynamique qui liste les logos de Piwik disponibles
- mappemonde.php : calculs, pointage des pays, affichage de la mappemonde et des continents
- menu.js : menu horizontal déroulant compatible XHTML
- microtime.php : fonction permettant de connaître le temps d’exécution du script
- moteurs.php : tableau des moteurs de recherches
- navigateur.class.php : fichiers qui permet la détection du navigateur et du système d'exploitation
- os.php : tableaux des systèmes d’exploitation
- set_lang.php : fichier qui définit la langue utilisée pour la consultation de Piwik
- test_db_cfg.php : tests de connexion/sélection à la base MySQL lors de l’installation
- vars.php : contient de nombreuses définitions de variables et de traitement de la période sélectionnée
- include/display/
  - calendrier.php : fichier d’affichage du calendrier en fonction de la date sélectionnée ; colore la période sélectionnée ; prend en compte la date de début des statistiques
  - period_selection.php : affiche le menu de sélection de la période à analyser
  - sites_selection.php : affiche le menu déroulant permettant la sélection des sites
  - topmenu.php : affiche le menu principal de sélection des rubriques
/langs
- compare.php : fichier en cours de test qui permet la comparaison du fichier de langue original et d'un fichier traduit.
- encode2utf8.php : fichier qui convertit un fichier spécifié dans le jeu de caractères UTF-8 (voir la partie Traductions pour plus d'informations)
- update_lg_files.php' : fichier qui permet l'ajout automatique des phrases anglaises dans toutes les traductions qui ne sont pas à jour. Cela permet de toujours avoir tous les fichiers de langues à jour (certains seront donc un mélange de la langue et d'anglais). Les traducteurs n'ont alors qu'à traduire les phrases en anglais pour maintenir à jour les traductions.
- xx-utf-8.php : fichier des textes de la langue xx
- show.php : affiche le code colorié d'un fichier donné

Architecture des tables de la base de données

Lors de l’installation ou de l’ajout d’un nouveau site, 6 tables sont créées dans la base Mysql configurée

phpmv
phpmv_pv
phpmv_suivi
phpmv_ajours
phpmv_asemaines
phpmv_amois
phpmv_bdd_vars

Table phpmv

Champ	Description	Type
Id	auto_increment	Mediumint(7)
IdVisiteur	Id du cookie du visiteur	varchar(32)
nv	Nv=1 si c'est la première visite, 0 sinon	tinyint(1)
date	Date du serveur lors de la première page vue	date
time	Heure locale du visiteur	time
stime	Heure du serveur	time
ttime	Temps total de visite du visiteur	mediumint(5)
referrer	Page referrer	varchar(255)
pv_debut	Page d’arrivée sur le site	varchar(255)
pv_fin	Page de sortie (dernière page vue)	varchar(255)
nb_pv	Nombre de pages vues par le visiteur	smallint(4)
host	HOST du visiteur	varchar(100)
ip	IP du visiteur	varchar(20)
os	Système d’exploitation	char(3)
navig	Navigateur	varchar(6)
resol	Résolution (largeur x hauteur)	varchar(9)
coul	Profondeur de l’écran (en bits)	tinyint(2)
pays	Pays (après traitement de host et lang navig)	char(2)
lang_navig	Langue du navigateur (utile pour debug)	varchar(10)
agent	Agent (utile pour debug). Infos navigateur et os	varchar(150)
flash	Acceptation du plugin	tinyint(3)
director	idem	tinyint(3)
quicktime	idem	tinyint(3)
real	idem	tinyint(3)
windowsmedia	idem	tinyint(3)
pdf	idem	tinyint(3)
java	idem	tinyint(3)

Dans cette table sont stockées toutes les informations sur le visiteur (voir tableau ci-dessus pour détails) qui seront ensuite retraitées lors de l’archivage. Chaque nouvelle visite est accompagnée d’un nouvel enregistrement dans cette table. Si le visiteur est connu, on update ’ttime’, ’pv_fin’ et ’nb_pv’.

Chaque champ est optimisé au maximum; les enregistrements et sélections dans cette table doivent être le plus rapide possible, car plusieurs requêtes sont effectuées pour chaque page vue (par le fichier Piwik.php).

Table phpmv_pv

Champ	Description	Type
Id	auto_increment	smallint(5)
page	URL de la page	varchar(255)
nb	Nombre de hit sur cette page à la date date	Smallint(5)
date	Date correspondante	Date

Lorsqu’une page est visitée pour la première fois pour un jour donné, un nouvel enregistrement a lieu dans la table phpmv pv. Si la page a déjà été visitée pour la date donnée, on update nb.

Table phpmv_suivi

Champ	Description	Type
id	auto_increment	mediumint(8)
page1	Page vue précédant la page vue notée page2	varchar(255)
page2	Page vue sélectionnée, précédée de la page1	varchar(255)
nb	Nombre de visiteur ayant réalisé le trajet page1 - page2	smallint(5)
date	Date correspondante	date

À chaque page vue, si le suivi page1 - page2 est enregistré dans la table pour la date donnée, on update nb. Si le suivi n’a pas encore été fait par un visiteur, on l’insère dans la table avec nb valant 1.

Tables archives (phpmv_a*)

Champ	Description	Type
id	auto_increment	smallint(5)
done	1 : ok ; 2 : temporaire ; vide : problème	tinyint(1)
date	Date de la période archivée (ou du début de la période)	date
visiteurs	Nombre de visiteurs uniques	mediumint(8)
vis	Nombre de visites	mediumint(8)
vis_hs	Visites par heure serveur	text
vis_hl	Visites par heure locale (ainsi que proportion domicile/travail)	text
pv	Nombre de pages vues total	mediumint(8)
pv_hs	Pages vues par heures serveur	text
pv_hl	Pages vues par heure locale	text
pv_diff	Nombre de pages accédées différentes	smallint(5)
pv_max	Nombre de pages vues max pour une visite	smallint(5)
vis1pv	Nombre de visite à une page vue	smallint(5)
hit_pv	Nombre de visites par page vues pour chaque page	longtext
hit_nbpv	Nombre de visiteurs par nombre de pages vues	text
hit_time	Nombre de visites par temps par chaque période d’une minute	text
sum_time	Somme des temps de visite en secondes	mediumint(8)
pv_debut	Nombre de visites par page d’entrée	longtext
pv_fin	Nombre de visites par page de sortie	longtext
suivi	Nombre de visites pour chaque ensemble page1 - page2	longtext
pays	Nombre de visites par pays pour chaque pays	text
fai	Nombre de visites par provider pour chaque provider	mediumtext
os	Nombre de visites par OS pour chaque OS	text
navig	Nombre de visites par navigateur pour chaque navigateur	text
resol	Nombre de visites par résolution pour chaque résolution	text
coul	Nombre de visites par profondeur d’écran (en bits)	varchar(255)
plugins	Taux d'acceptation des plugins	varchar(255)
moteurs	Nombre de visites par moteur pour chaque moteur	mediumtext
mots	Nombre de visites par mot clé pour chaque mot clé	mediumtext
sitesrefs	Nombre de visites par site referrer pour chaque site referrer	mediumtext
nb_moteurs	Nombre de visites provenant d’un moteur de recherche	smallint(5)
nb_sites	Nombre de visites provenant de liens sur d’autres sites	smallint(5)
nb_direct	Nombre de visites directes	smallint(5)

La table des archives des mois et semaines présentent un champ supplémentaire : ’date_fin’ qui indique la date de fin de la période archivée ; cela permet de savoir s'il est utile de recalculer les archivages pour les périodes temporaires.

Dans les tables d’archivage sont stockées toutes les statistiques pré-calculées. Chaque champ est ensuite sélectionné puis affiché dans les pages de consultation des statistiques. Les champs de type ’text’, ’mediumtext’ et ’longtext’ sont des tableaux php sérialisés. Les autres champs sont des valeurs numériques.

En version 1.1, les champs ’pv debut’, ’pv fin’, ’hit pv’ et ’suivi’ sont passés au type LONGTEXT. La mise à jour est automatique lors de l’installation.

Valide XHTML 1.1 CSS

L’évolution du HTML vers le XHTML est la conséquence de nouvelles attentes, les aspects d'accessibilité, la multiplication des supports de lecture et les habitudes de programmation de plus en plus basées sur des pages construites dynamiquement. Le HTML pose de problèmes pour ces pratiques, car la structure est très rigide, le contenu et la mise en forme étant mélangés. Avec le XHTML, les données sont séparées de la mise en forme qui sera assurée en fonction du support par des feuilles de style CSS. Le XHTML est basé sur le XML qui est un langage de description des données, toutes les balises de présentation du HTML sont donc devenus obsolètes. Un autre gros avantage du formatage des données est d’avoir des pages beaucoup plus légères et un traitement amélioré par les navigateurs et au final une navigation plus confortable pour les internautes et une maintenance facilitée pour les programmeurs.

Pour Piwik l’avantage est de pouvoir personnaliser facilement la présentation en ne modifiant que les feuille de styles. Tous les navigateurs récents sont maintenant supportés (IE >= 5, Mozilla et ses dérivés, Opera 7, Konqueror 3), mais le rendu avec les anciens navigateurs comme Netscape 4.X est très sommaire. Si vous disposez d'un de ces navigateurs avec lesquels la consultation des statistiques de Piwik ne vous est pas possible, nous vous recommandons vivement l'utilisation du splendide navigateur Firefox, qui est très stable, rapide, puissant et complet. C'est le nouveau-né de la famille Mozilla, qui se compare aisément en termes de fonctionnalités avec Internet Explorer (il le surpasse même dans la quasi totalité des domaines). Pour le télécharger, visitez le site http://www.mozilla.org/products/firefox/ : bon surf !

Librairie graphique

Les graphiques de Piwik sont générés grâce à la puissante librairie JPGraph (http://www.aditus.nu/jpgraph/) distribuée sous license QPL. Il faut bien noter la différence de licences, ce qui explique que JPGraph ne soit pas directement inclue à l’application, il est nécessaire de laisser les fichiers distincts avec la notice de la license QPL en haut de chaque fichier jpgraph*.php.

Les graphiques disponibles dans Piwik sont de plusieurs types :

graphiques à barres verticales détaillant le nombre de visites/pages vues par heure serveur et heure locale, le nombre de visites par temps de visite ou encore le nombre de visiteurs par nombre de pages vues.
graphiques de type camembert 3D pour tous les résumés des statistiques concernant les pays d’origine des visiteurs, les configurations matérielles (OS, navigateurs, résolutions, profondeur de couleur).
graphique de type camembert 2D pour le résumé des referrants (sites, moteurs de recherche ou entrée directes).

Les graphiques ne sont pas stockés sur le serveur mais recalculés à chaque consultation. Dans une prochaine version, les possibilités de cache permises par JPGraph seront certainement utilisées, ce qui limitera les ressources serveur utilisées lors de la génération des graphiques.

Sécurité générale

La sécurité dans Piwik est un domaine sur lequel l'équipe de développement travaille constamment. Piwik utilise le procédé des sessions php pour la connexion, procédé inviolable et entièrement sécurisé. Le mot de passe pour accéder à l'administration est codé dans le fichier de configuration. De nombreux tests sont réalisés afin d'empêcher toute tentative de hacking via Piwik (SQL Injection ou Cross Site Scripting).

Néanmoins il convient de respecter les règles suivantes afin de minimiser les problèmes :

ne pas permettre l'affichage de phpinfo(); sur aucune page visible de votre site
mettre « register_globals » à « off » dans votre configuration php
mettre « display_errors » à « off », et « log_errors » à « on ». C'est très important car les messages d'erreur sont une mine d'informations énorme pour un pirate. Même si en temps normal aucune erreur ne s'affiche sur votre site, le pirate fait en sorte d'afficher les erreurs lui-même, et il en tire de nombreuses informations.
faire des sauvegardes régulières de sa base de données (donc des données des tables de Piwik), cela évite de tout perdre en cas d'attaque
penser à créer un mot de passe complexe avec lettres et chiffres et au moins 6 caractères de longueur (il est très facile de créer un script pour attaquer un site web par dictionnaire, il y a même des logiciels qui font cela, et qui fonctionnent très bien quand le mot de passe est simple)
le mot de passe admin NE DOIT PAS être le même que le ftp et/ou le mysql (ce que l'on voit trop souvent).

Il est évident de plus qu'il ne faut pas éditer les fichiers de Piwik sans être sûr de soi, afin de ne pas créer d'éventuelles failles de sécurité ou autre.

En respectant ces quelques règles, vous n'aurez presque aucune possibilité de vous faire pirater votre serveur, nous vous conseillons donc de les suivre précisément (si vous en avez les possibilités).

Ajouter un moteur de recherche

Vous pourrez rencontrer, dans les statistiques de la rubrique « Affluents », des arrivées par des sites Internet qui n'en sont pas réellement : certains peuvent en effet être des moteurs de recherche qui ne sont pas reconnus comme tel par Piwik. Pour corriger ce problème, il vous suffit d'ajouter ce moteur dans la liste des moteurs gérés par Piwik, en éditant le fichier /core/datas/searchEngines.php et en créant une nouvelle ligne contenant le nom, l'adresse Internet du moteur, et la variable qui contient les mots clés lorsque vous effectuez une recherche. Pour connaitre cette variable, effectuez vous-même une recherche sur le moteur que vous souhaitez ajouter à la liste, et observez l'URL de la page où sont affichés les résultats. Par ex pour Google, en cherchant « Piwik », la page sera de la forme http://www.google.fr/search?q=Piwik. Il peut y avoir de nombreuses autres variables mais relevez seulement celle contenant le mot clé recherché. La ligne du fichier moteurs.php sera de la forme :

 "www.google.fr" => array("Google", "q"),

Si vous ajoutez ainsi des moteurs de recherche, merci de prévenir l'équipe de développement afin qu'ils soient directement intégrés à la prochaine version.

Calendrier interactif

Le calendrier interactif permet de sélectionner une date d’étude pour les statistiques rapidement et intuitivement. Une liste déroulante propose le choix entre tous les mois depuis l’installation de Piwik. Lors d’un changement de mois, le type de période d’analyse (jour, semaine ou mois) est conservé. Les jours de la période d’analyse sont de couleur orange. Les autres jours analysables sont de couleur bleu. Les jours non analysables sont grisés. Le jour considéré comme premier jour d'installation de Piwik est la date contenu dans le premier champ de la table « phpmv » (avec id=1) ; ce champ n'est jamais supprimé car il permet d'avoir connaissance du premier jour d'installation de Piwik sur le serveur. Si vous l'avez supprimé par mégarde, éditez le premier champ de votre table « phpmv » et remplacez la valeur du id par 0 et la valeur de la date par la date du premier jour de votre installation (respectez bien la norme MySQL : aaaa-mm-dd).

Gestion de plusieurs sites

La gestion de plusieurs sites dans Piwik est gérée de manière très simple. À la création d’un nouveau site à auditer, des nouvelles tables sont créées (avec le numéro du site suivant le préfixe) sur le serveur configuré, dans la base MySQL configurée. Ensuite, seul le nom des tables change dans les requêtes MySQL d’affichage, d’archivage, etc. Le reste de l'application reste inchangé.

Échelle de couleur pour la mappemonde

L'échelle de couleur pour la mappemonde n'est à notre sens pas encore optimale, dans le sens où nous pensons qu'elle pourrait être plus précise (plus de nuances de couleurs ? Des couleurs plus distinctes ? Ou au contraire une teinte plus unie mais progressive ?).

Quoi qu'il en soit, il vous suffit d'éditer l'image de la barre de couleurs, et les nouvelles couleurs seront automatiquement prises en compte sur la mappemonde. Il est par contre nécessaire de garder les mêmes dimensions pour l'image de la barre.

Si vous arrivez à un résultat concluant, n'hésitez pas à nous faire part de l'image !

Logos Piwik

Tous les logos disponibles à l'affichage sur les pages des sites audités sont des logos soumis par les utilisateurs de Piwik ! L'idéal serait de toujours enrichir cette base de données de logos afin que chacun trouve le logo qui sied parfaitement à l'esprit graphique de son site Internet.

N'hésitez donc pas à soumettre vos créations de logos à l'équipe de développement ! (Sur les forums officiels par exemple)