📍 Article principal de la série : Umami Analytics 2026 : guide pratique.

Snippet Umami = 1 ligne HTML. Mais l’intégration optimale varie selon framework. Ce tutoriel détaille les méthodes propres pour WordPress, Next.js 15 (App Router), Astro 4, Vue, et site HTML statique.

Prérequis

Umami installé (voir tutoriel installation).
Site enregistré, Website ID copié.
Niveau attendu : débutant/intermédiaire.
Temps estimé : 10-30 minutes selon stack.

Snippet de base

<script defer src="https://analytics.votre-entreprise.com/script.js"
  data-website-id="VOTRE_UUID_WEBSITE"></script>

Coller dans <head> ou juste avant </body>.

WordPress

Méthode 1 — Plugin officiel

Extensions → Ajouter → « Umami Analytics ». Installer + Activer. Réglages → Umami :

Tracker URL : https://analytics.votre-entreprise.com/script.js.
Website ID : votre UUID.
Track admin : OFF.

Méthode 2 — Code dans theme

Si pas de plugin, dans functions.php du thème enfant :

add_action('wp_head', function() {
  if (is_admin()) return;
  echo '<script defer src="https://analytics.votre-entreprise.com/script.js" data-website-id="UUID"></script>';
});

Next.js 15 App Router

Dans app/layout.tsx :

import Script from 'next/script';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        {process.env.NODE_ENV === 'production' && (
          <Script defer
            src="https://analytics.votre-entreprise.com/script.js"
            data-website-id={process.env.NEXT_PUBLIC_UMAMI_WEBSITE_ID}
            strategy="afterInteractive"
          />
        )}
      </body>
    </html>
  );
}

Astro 4

Dans src/layouts/Layout.astro :

---
const isProd = import.meta.env.PROD;
---
<html>
<head>
  <slot name="head" />
  {isProd && (
    <script defer
      src="https://analytics.votre-entreprise.com/script.js"
      data-website-id={import.meta.env.UMAMI_WEBSITE_ID}></script>
  )}
</head>
<body>
  <slot />
</body>
</html>

Vue 3

Dans main.ts :

if (import.meta.env.PROD) {
  const script = document.createElement('script');
  script.defer = true;
  script.src = 'https://analytics.votre-entreprise.com/script.js';
  script.setAttribute('data-website-id', import.meta.env.VITE_UMAMI_WEBSITE_ID);
  document.head.appendChild(script);
}

Site HTML statique

Coller dans <head> de chaque page (ou template global) :

<script defer src="https://analytics.votre-entreprise.com/script.js"
  data-website-id="UUID"></script>

Options avancées

Auto-track outbound clicks

data-auto-track="true"
data-track-outbound="true"

Honor Do Not Track

data-do-not-track="true"

Domains specific only

data-domains="boutique.com,blog.boutique.com"

Cache et tag-manager

Pour Google Tag Manager (legacy), créer Custom HTML tag avec snippet. Trigger : All Pages.

Vérification

1. Console browser

F12 → Network → filter « umami ». Visite page = requête POST /api/send avec status 200.

2. Real-time Umami

Dashboard Umami → Real-time. Compteur visiteurs incrément à chaque visite.

3. Custom event de test

Dans console browser : umami.track('test-event'). Voir dans Events Umami.

Erreurs fréquentes

Erreur	Cause	Solution
404 script.js	URL incorrecte	Vérifier sans typo
403 CORS	Domain pas dans whitelist	Settings Umami site → permissions
Adblockers bloquent	Pattern reconnu	Configurer reverse proxy via votre domaine
Stats admin uniquement	Pas IP exclude	Settings Umami exclude IPs admin
Pageviews multipliées	SPA navigation events	Auto-detect activé par défaut
Track sur dev	Pas de production check	Conditionner avec NODE_ENV

Réalités du terrain en Afrique francophone

Trois précisions. Performance mobile : 2 Ko script + defer = aucun impact perçu sur 3G/4G. Reverse proxy domain : analytics.votre-domaine.com = pas de blocage adblocker. Multi-langue : un seul Umami site couvre /fr/ et /ar/, dashboard filtre par path.

Tutoriels frères

FAQ

SPA single-page applications ? Auto-detect par défaut. Sur Next.js, Vue, React : navigation traquée automatiquement.

WordPress sans plugin ? Possible via mu-plugin custom. Plugin officiel plus simple.

SSR vs SSG ? Pour SSG (Astro), tracking client-side identique. Aucune diff perçue.

iframe tracking ? Non par défaut. Custom code requis.

AMP pages ? AMP analytics protocol différent. Umami pas natif AMP.

Sur un angle proche

🔝 Retour au guide général : guide pratique Umami 2026
Documentation Tracker : umami.is/docs/tracker-configuration

Vous voulez confier la création de votre site web ?

Conception sur mesure : nom de domaine 1 an gratuit, hébergement 1 an gratuit, formation à la gestion du site, support technique 6 mois. Accès et code livrés.

À partir de 350 000 FCFA

📧 E-mail
💬 WhatsApp

Pourquoi Umami plutot que Google Analytics 4 en 2026

Pour un site qui cible Dakar, Abidjan ou Lome, Google Analytics 4 pose deux problemes concrets : la lourdeur du script (90+ Ko gzip qui plombent le LCP sur 4G africaine) et la conformite RGPD qui impose un bandeau cookies anxiogene avant tout tracking. Umami repond aux deux : 2 Ko gzip, pas de cookies, pas de PII collectee, dashboards lisibles. Le tarif self-hosted demarre a zero (binaire Docker sur un VPS Hetzner CX22 a 4,90 EUR / mois, soit ~3 215 FCFA).

L objectif de ce tutoriel : installer Umami v2.x en self-hosted derriere un reverse proxy HTTPS, generer le snippet de tracking, et l integrer sur trois stacks frequentes en 2026 — WordPress (theme custom et page builder), Next.js 15 App Router, Astro 5. A la fin, vos analytics tournent en moins de 30 minutes, sans bandeau cookies, avec un dashboard accessible depuis n importe quel navigateur.

Etape 1 : Provisionner un VPS et une base Postgres

Umami v2 exige Postgres 12+ ou MySQL 8+. Pour rester simple, on lance Postgres en conteneur a cote d Umami. Verifiez d abord que Docker et Docker Compose sont installes sur votre VPS Ubuntu 24.04.

docker --version
docker compose version

Sortie attendue : Docker version 27.x et Docker Compose version v2.29+. Si une commande renvoie command not found, installez Docker via le script officiel curl -fsSL https://get.docker.com | sh. Sans ces deux outils, la suite du tutoriel ne fonctionnera pas.

Etape 2 : Lancer Umami avec docker-compose

Creez un dossier /opt/umami et un fichier docker-compose.yml minimaliste. Umami v2 se compose de deux services : l app Node et la base Postgres. Le mot de passe Postgres doit etre genere aleatoirement (32 caracteres minimum), pas celui de l exemple.

services:
  umami:
    image: ghcr.io/umami-software/umami:postgresql-v2.13.0
    ports:
      - "127.0.0.1:3000:3000"
    environment:
      DATABASE_URL: postgresql://umami:VOTRE_MOT_DE_PASSE@db:5432/umami
      DATABASE_TYPE: postgresql
      APP_SECRET: VOTRE_SECRET_ALEATOIRE
    depends_on:
      - db
    restart: always
  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: umami
      POSTGRES_USER: umami
      POSTGRES_PASSWORD: VOTRE_MOT_DE_PASSE
    volumes:
      - ./pg_data:/var/lib/postgresql/data
    restart: always

Lancez avec docker compose up -d. La sortie attendue affiche Container umami-umami-1 Started et Container umami-db-1 Started. Verifiez avec docker compose ps que les deux services sont en running (healthy).

Etape 3 : Configurer le reverse proxy HTTPS avec Caddy

Umami ecoute sur 127.0.0.1:3000 (acces local uniquement). Caddy expose le service en HTTPS sur votre domaine analytics. Le Caddyfile tient en trois lignes.

analytics.example.com {
  reverse_proxy 127.0.0.1:3000
}

Rechargez Caddy avec sudo systemctl reload caddy. Visitez https://analytics.example.com dans votre navigateur : la page de login Umami doit s afficher avec le cadenas vert. Le compte par defaut est admin / umami. Changez immediatement ce mot de passe : c est le compte super-admin.

Etape 4 : Creer un site et recuperer le snippet

Dans l admin Umami, cliquez Settings > Websites > Add website. Renseignez le nom et le domaine (sans https://, juste monsite.com). Validez : Umami genere un Website ID au format UUID et un snippet HTML pret a copier.

<script defer src="https://analytics.example.com/script.js" data-website-id="VOTRE_UUID"></script>

Notez bien ce snippet : c est ce qu on integre sur les trois stacks ci-dessous. L attribut defer garantit que le script ne bloque pas le rendu initial de la page, critique pour les visiteurs en 4G a Dakar ou Bamako.

Etape 5 : Integrer Umami sur WordPress

Trois methodes selon votre setup. Methode 1 (theme custom) : ajoutez le snippet dans functions.php via un hook wp_head. C est la maniere la plus propre, le script est inline dans le head HTML.

add_action('wp_head', function() {
  echo '<script defer src="https://analytics.example.com/script.js" data-website-id="VOTRE_UUID"></script>';
});

La sortie attendue : ouvrez votre site, View Source, cherchez analytics.example.com. La balise doit apparaitre dans le <head>. Methode 2 (Elementor / page builder) : Settings > Custom Code > Add new > Location <head>. Collez le snippet, publiez. Methode 3 (plugin dedie) : « Integrate Umami » sur le repository WordPress, configuration GUI. Plus simple mais ajoute une dependance plugin.

Etape 6 : Integrer Umami sur Next.js 15 App Router

Sur Next.js 15 avec l App Router, on utilise le composant Script de next/script avec la strategie afterInteractive. C est l equivalent du defer en Vanilla JS, mais geree proprement par le bundler.

// app/layout.tsx
import Script from 'next/script';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <Script defer src="https://analytics.example.com/script.js" data-website-id="VOTRE_UUID" />
      </body>
    </html>
  );
}

Apres deploiement, ouvrez le DevTools onglet Network, filtrez sur script.js : la requete doit retourner 200 OK avec un payload de ~2 Ko. Si elle renvoie 404, verifiez le sous-domaine analytics dans l URL.

Etape 7 : Integrer Umami sur Astro 5

Astro est devenu un choix frequent pour les sites de contenu en 2026 — blog itskillscenter, vitrines d agence Dakar, docs techniques. L integration tient en deux lignes dans le composant Layout principal.

---
// src/layouts/BaseLayout.astro
---
<html>
  <head>
    <script is:inline defer src="https://analytics.example.com/script.js" data-website-id="VOTRE_UUID"></script>
  </head>
  <body><slot /></body>
</html>

Le directive is:inline indique a Astro de ne pas bundler ce script (il est deja minifie cote Umami). Apres npm run build puis npm run preview, ouvrez la page : le snippet doit etre present dans le HTML statique genere.

Etape 8 : Verifier le tracking et debugger

Visitez votre site dans un navigateur en navigation privee (sans bloqueurs). Retournez sur Umami, dashboard du site : le compteur Visiteurs en ligne doit passer a 1 dans les 30 secondes. Si rien ne s affiche apres 1 minute, trois causes courantes.

Cause 1 : adblocker. uBlock Origin bloque par defaut tout chemin contenant /script.js hebergiseur tiers. Solution : whitelistez le domaine analytics ou renommez le script via la variable d env TRACKER_SCRIPT_NAME. Cause 2 : domaine non declare dans Umami. Le script verifie le document.referrer face au domaine declare. Cause 3 : CSP qui bloque l origin analytics.example.com. Verifiez la console DevTools pour le message d erreur explicite.

À lire ensuite sur l auto-hebergement de services analytics et tracking, consultez notre tutoriel Forgejo Actions CI/CD pour automatiser les deploiements de votre instance Umami, et le guide Docker / Podman avance 2026 pour durcir le runtime.

Annexe : evenements custom et conversions

Au-dela du pageview, Umami capte des evenements nommes (clic CTA, soumission formulaire, scroll depth). L API JS s appelle umami.track('nom_event', { propriete: 'valeur' }). Exemple sur un bouton WhatsApp Business critique pour les sites senegalais.

document.querySelector('.btn-whatsapp').addEventListener('click', () => {
  umami.track('whatsapp_click', { source: 'pricing_page' });
});

L evenement remonte instantanement dans Umami > Events. Filtrez par propriete pour voir quelle page convertit le mieux. Aucune donnee personnelle n est envoyee : seul le nom de l evenement et les proprietes que vous declarez.

Annexe : sauvegarde Postgres et migration

Umami stocke tout dans Postgres. La sauvegarde quotidienne tient en une commande cron qui dump la base et l envoie sur Scaleway Object Storage Paris (le plus proche de l Afrique de l Ouest, latence acceptable depuis Dakar).

0 4 * * * docker exec umami-db-1 pg_dump -U umami umami | gzip > /tmp/umami_$(date +\%Y\%m\%d).sql.gz

Pour la migration vers un nouveau VPS, restaurez le dump avec gunzip -c umami_xxx.sql.gz | docker exec -i umami-db-1 psql -U umami umami apres avoir relance le compose. Tous les dashboards, sites declares et evenements sont preserves.

FAQ Umami self-hosted

Combien de visiteurs supporte Umami sur un VPS 1 vCPU ? Largement 100 000 pageviews / mois sans accroc. Postgres consomme l essentiel des ressources : optez pour 2 Go RAM minimum si vous franchissez 500 000 pageviews mensuels.

Umami capte-t-il les visiteurs en mode incognito ? Oui, contrairement a GA4 qui depend des cookies. Umami genere un hash anonyme base sur user-agent + IP + sel du jour : un meme visiteur en navigation privee est compte une fois par jour.

Peut-on exporter les donnees brutes ? Oui, Umami expose une API REST documentee et permet l export CSV depuis chaque dashboard. Pratique pour brancher Metabase ou Grafana en aval.

Compatible avec un site multi-domaines ? Oui, declarez chaque domaine comme un site separe dans Umami. Vous obtenez un Website ID par domaine et des dashboards isoles. Pour un suivi cross-domain, utilisez la propriete data-domains sur le snippet.

Le tracker est-il bloque par les bloqueurs de pub ? uBlock Origin et certaines listes EasyPrivacy bloquent les chemins /script.js connus. La parade : variable d env TRACKER_SCRIPT_NAME=stats.js et COLLECT_API_ENDPOINT=/api/send. Le tracker s appelle alors stats.js et echappe aux listes generiques.

Faut-il afficher un bandeau cookies ? Non, Umami ne pose aucun cookie et ne stocke aucune PII. La CNIL francaise et la Commission de Protection des Donnees du Senegal acceptent ce mode « analytics anonymes » sans consentement prealable, comme le precise la CNIL pour les outils equivalents (Matomo configure sans cookies).

Bonus : Umami derriere Cloudflare et tunnel zero-trust

Si votre infra passe par Cloudflare, Umami fonctionne sans modification. Activez Full (strict) en mode SSL, et autorisez les requetes POST sur /api/send dans les Page Rules. Pour les utilisateurs ultra-sensibles a la latence depuis Bamako ou Conakry, activez Cloudflare Argo : la latence chute de 200 ms a 80 ms en moyenne sur les chemins Afrique de l Ouest vers Paris. Cout reel : 5 USD / mois plus le bandwidth.

Pour exposer une instance Umami hebergee sur un poste local sans IP publique (cas des laboratoires de formation Dakar), Cloudflare Tunnel fait le travail : cloudflared tunnel create umami, cloudflared tunnel route dns umami analytics.example.com, et cloudflared tunnel run umami. Aucun port a ouvrir cote firewall, certificat TLS gere par Cloudflare.