« Peut-on faire du Matomo server-side ? » C’est une question que j’entends sur presque tous les projets Matomo. La réponse courte : oui. La réponse utile : tout dépend de ce que vous appelez server-side, car il existe au moins cinq montages différents derrière ce mot, et ils ne résolvent pas le même problème. Certains suppriment totalement le JavaScript du navigateur, d’autres le gardent et changent seulement la destination des hits.
Mal choisi, le montage donne les symptômes classiques : hits géolocalisés dans votre datacenter, « visiteurs uniques » qui sont une seule machine, achats suivis comme des événements, consentement oublié. Ce guide compare les options, puis détaille la Tracking HTTP API.
Les cinq façons de faire du Matomo server-side
Toutes aboutissent au même endroit : une requête HTTP vers votre point de collecte Matomo (matomo.php). Ce qui change, c’est qui envoie la requête et ce qui tourne encore dans le navigateur.
| Montage | Qui envoie le hit | JS navigateur encore nécessaire ? | Ce que ça résout | Ce que ça ne résout pas |
|---|---|---|---|---|
| Tracking HTTP API, en direct | Votre backend (tout langage, un simple GET ou POST) | Non pour les événements backend. Oui si vous voulez aussi la navigation | Les événements qui n’existent que côté serveur : paiements confirmés, remboursements, CRON, webhooks | Résolution d’écran, titres de page, interactions client, sauf si vous les passez vous-même. Le consentement |
| GTM server-side + client Matomo | Le navigateur envoie à votre conteneur sGTM, qui relaie vers Matomo | Oui, le code de suivi Matomo pointé vers le domaine du conteneur | Un point de collecte sur votre domaine, plus de contrôle sur ce qui est transmis | Supprimer le script navigateur. Vous exploitez en plus un serveur : le conteneur |
| Tracker proxy | Le navigateur envoie à un proxy matomo.php sur votre site, qui relaie vers Matomo | Oui | Cache l’URL de votre serveur Matomo aux sites suivis | Supprimer le script navigateur |
| Log Analytics | Un script Python qui importe les logs d’accès de votre serveur web | Non | Analyse de trafic sans aucun tag, import d’historique | Pas de cookies de suivi ni de résolution d’écran |
Matomo Tag Manager n’est pas une option server-side : c’est un conteneur côté client. La FAQ de Matomo indique que le server-side tagging via Matomo Tag Manager « n’est pas supporté actuellement ». Matomo documente exactement deux méthodes server-side : la Tracking API depuis votre serveur, et son tag dans un conteneur sGTM (template « Matomo Server-side Client », puis remplacement du domaine Matomo par l’URL du conteneur). En pratique, la plupart de mes montages sont hybrides : le tracker JavaScript pour la navigation, l’API HTTP pour les conversions qui comptent, rattachés au même visiteur.
Pas à pas : envoyer un hit server-side avec la Tracking HTTP API
1. Créer un utilisateur et un token dédiés
Certains paramètres exigent un token_auth : forcer l’IP du visiteur (cip), envoyer une date de plus de 24 heures (cdt), forcer le pays ou la ville. Matomo recommande de créer un utilisateur spécifique à la Tracking API, avec le droit d’écriture sur les seuls sites concernés. Gardez le token côté serveur : il ne doit jamais apparaître dans le code source de la page ni dans une requête du navigateur.
2. Décider comment le hit serveur rejoint la visite navigateur
C’est l’étape que la plupart des implémentations sautent, et c’est pourquoi les hits serveur « flottent » sans source, sans campagne et sans parcours. Vous avez deux clés :
- Visitor ID (
cid) : exactement 16 caractères hexadécimaux. Côté navigateur, le tracker JavaScript le fournit avecgetVisitorId(). Stockez-le avec la commande ou la session dans votre backend. Quand vous renseignezcid, Matomo ne rapproche que les visites avec ce visitor ID exact. - User ID (
uid) : votre propre identifiant d’utilisateur connecté. Si une visite avec ce User ID existe dans les 30 dernières minutes, l’action y est ajoutée. Sinon une nouvelle visite est créée.
var _paq = window._paq = window._paq || [];
_paq.push([function () {
var visitorId = this.getVisitorId(); // 16 hex characters
// send it to your backend with the checkout form or an API call
}]);Les User ID sont des données personnelles selon Matomo : n’utilisez uid que si votre consentement le couvre.
3. Construire la requête
Voici une commande e-commerce envoyée depuis le backend après confirmation du prestataire de paiement. C’est un POST vers matomo.php, chaque valeur étant encodée par curl :
curl -s -o /dev/null -w "%{http_code}\n" -X POST "https://matomo.example.com/matomo.php" \
--data-urlencode "idsite=1" --data-urlencode "rec=1" --data-urlencode "send_image=0" \
--data-urlencode "url=https://shop.example.com/checkout/confirmed" \
--data-urlencode "cid=5b1d8c3f0a9e7d21" --data-urlencode "uid=customer-48213" \
--data-urlencode "ua=Mozilla/5.0 (Macintosh; ...) Safari/605.1.15" \
--data-urlencode "cip=203.0.113.42" --data-urlencode "token_auth=YOUR_TRACKING_USER_TOKEN" \
--data-urlencode "idgoal=0" --data-urlencode "ec_id=ORD-2026-10457" \
--data-urlencode 'ec_items=[["SKU-118","Running shoes","Shoes",89.90,1]]' \
--data-urlencode "revenue=109.70"idsiteetrec=1sont les seuls paramètres obligatoires ;send_image=0fait répondre un HTTP 204.cidetuidrattachent ce hit au visiteur navigateur et au client (étape 2).uaetcipremplacent le User-Agent et l’IP, sinon Matomo voit ceux de votre serveur.cipexigetoken_auth.idgoal=0est obligatoire pour une commande ;ec_idetrevenuesont requis ;ec_itemsest un tableau JSON [SKU, nom, catégorie, prix, quantité].
Pour les traitements par lots, la Tracking API accepte aussi un POST JSON avec un tableau requests (bulk tracking), dans l’ordre chronologique.
Comment vérifier que ça marche
- Le statut HTTP. Avec
send_image=0, une requête réussie répond 204 ; sinon 200 et un GIF 1×1. Un 4xx, un 5xx ou un timeout pointe vers l’amont : mauvaise URL, pare-feu, serveur en panne. - Le journal des visites du jour. Retrouvez la visite par User ID ou visitor ID : vous devez voir les pages navigateur d’abord, puis la commande, dans la même visite, avec le bon pays et le bon navigateur. Si la commande est seule dans une visite venant de la ville de votre hébergeur,
cipouuamanque. - Les rapports E-commerce, pas le rapport Événements. Une commande envoyée avec
idgoal=0atterrit dans l’E-commerce. Si vous la trouvez dans Événements, elle a été envoyée comme événement.
Les pièges que je retrouve sans cesse
- Toutes les visites viennent de votre serveur. Sans
uaetcip, Matomo utilise le User-Agent et l’IP du serveur. La géolocalisation pointe vers votre datacenter. Pire, sans visitor ID, Matomo rapproche les visiteurs par une heuristique basée sur l’IP et d’autres attributs d’appareil : des clients sans lien peuvent fusionner en un seul visiteur. Transmettez toujours le vrai User-Agent et la vraie IP, et renseignezcidouuid. - Des achats suivis comme des événements. Un événement avec
e_v=79.99n’est pas du chiffre d’affaires : il n’apparaîtra ni dans l’E-commerce ni dans l’attribution des objectifs. Utilisezidgoal=0avecec_idetrevenuepour les commandes, etidgoal=<id>avecrevenuepour une conversion d’objectif classique. - « Server-side veut dire pas de consentement ». Faux. La FAQ de Matomo est explicite : cela ne vous rend pas conforme automatiquement. Je n’ai trouvé aucun paramètre de consentement dans la référence de la Tracking HTTP API : côté serveur, le contrôle est l’affaire de votre code. Stockez le choix du visiteur avec la session, et n’envoyez pas le hit (ou pas les identifiants) quand il dit non.
- « Le server-side bat les bloqueurs de pub ». En partie : un hit envoyé depuis le backend ne passe pas par le navigateur, mais les montages sGTM et proxy chargent encore un script dans la page.
Conclusion
Le Matomo server-side n’est pas une fonctionnalité unique, c’est un choix de qui envoie le hit. Pour les événements les plus importants, ceux que votre backend connaît avec certitude, envoyez-les depuis le serveur avec la Tracking HTTP API ou un SDK officiel. Passez la vraie IP et le vrai User-Agent, rattachez le hit au visiteur navigateur avec cid ou uid, envoyez les commandes comme des commandes, et vérifiez le journal des visites avant de conclure. Gardez le tracker JavaScript pour la navigation, et le consentement là où il doit être : avant le hit, des deux côtés.
Sources
- Matomo Developer : Tracking HTTP API reference
- Matomo Developer : PHP Tracking Client reference
- Matomo Developer : Tracking and cookie consent
- Matomo FAQ : Does Matomo Tag Manager support server-side tagging?
- Matomo FAQ : How to integrate Matomo tracking in server-side Google Tag Manager
- Matomo FAQ : How does Matomo detect unique and returning visitors?
Pour aller plus loin, lisez la version complète de l’article (en anglais) : Matomo Server-Side Tracking: How to Set It Up (5 Options Compared).
Besoin d’aide sur ce sujet ? Commanders Act et server-side.