# Matomo/Fonctionnement

* Présentation
* Installation
* Configuration
* Fonctionnalités
* Fonctionnement
* Traductions
* Soutien
* À propos
* CodingStandard
* Réflexion Version 2
* SearchEnginesDetection
* Réflexions version2 test
* interfaces club
* Présentation
* Installation
* Configuration
* Fonctionnalités
* Fonctionnement
* Traductions
* Soutien
* À propos
* CodingStandard
* Réflexion Version 2
* SearchEnginesDetection
* Réflexions version2 test
* interfaces club
[ Modifier le sommaire ]
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.

## 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 :
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)