Custom events et goals tracking Umami : tutoriel pratique 2026

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

Sans events configurés, Umami compte juste pages vues. Pour mesurer conversions réelles (signup, purchase, Wave checkout), configurer custom events est essentiel. Ce tutoriel détaille l’implémentation pour e-commerce ouest-africain.

Prérequis

• Umami avec snippet installé (voir tutoriel snippet).
• Site avec actions à tracker.
• Niveau attendu : intermédiaire.
• Temps estimé : 1 heure.

API umami.track()

Event simple

umami.track('Newsletter Signup');

Event avec properties

umami.track('Purchase', {
  amount: 12500,
  currency: 'XOF',
  payment_method: 'wave',
  products_count: 3
});

Event avec custom name + custom data

umami.track(props => ({
  ...props,
  name: 'Custom Event',
  url: '/special-page',
  data: { campaign: 'tabaski-2026' }
}));

Tracking via attributs HTML data

Auto-tracking sans JS via data-umami-event :

<button data-umami-event="Click CTA Hero"
        data-umami-event-cta-position="hero"
        data-umami-event-cta-label="Commencer">
  Commencer
</button>

Au clic, Umami enregistre event « Click CTA Hero » avec props cta-position et cta-label.

Cas pratiques e-commerce ouest-africain

Newsletter signup (Brevo, Mailchimp)

document.querySelector('#newsletter-form').addEventListener('submit', () => {
  umami.track('Newsletter Signup', {
    source: 'footer'
  });
});

Add to cart WooCommerce

jQuery('.add_to_cart_button').on('click', function() {
  const product = jQuery(this).data('product_id');
  const price = jQuery(this).closest('.product').find('.price').text();
  umami.track('Add to Cart', {
    product_id: product,
    price: parseFloat(price)
  });
});

Payment method selection

document.querySelectorAll('input[name="payment_method"]').forEach(input => {
  input.addEventListener('change', e => {
    umami.track('Payment Method Selected', {
      provider: e.target.value  // wave, orange_money, card
    });
  });
});

Purchase confirmation page

// thank-you.php WooCommerce
<?php
$order = wc_get_order(get_query_var('order-received'));
$amount = $order->get_total();
$payment = $order->get_payment_method();
$is_new = $order->get_user_id() ? 'false' : 'true';
?>
<script>
umami.track('Purchase', {
  amount: <?php echo $amount; ?>,
  currency: 'XOF',
  payment_method: '<?php echo $payment; ?>',
  new_customer: <?php echo $is_new; ?>
});
</script>

Click WhatsApp Business contact

<a href="https://wa.me/221700000000"
   data-umami-event="Click WhatsApp"
   data-umami-event-source="header">
  Contacter sur WhatsApp
</a>

Video play tracking

document.querySelector('video').addEventListener('play', () => {
  umami.track('Video Play', { video_id: 'product-demo' });
});

Visualisation côté Umami

Events tab

Dashboard → site → Events tab. Liste tous les events, comptages, sources, dates.

Filtrer par property

Cliquer sur event → propriétés s’affichent. Filtrer par payment_method=wave par exemple.

Real-time events

Dashboard → Real-time → events s’incrémentent en direct.

Goals (revenue tracking)

Pour chaque purchase event, Umami agrège le total revenue par période. Filtrable par source, country, device.

Funnels manuels

Umami n’a pas de funnels natifs. Workaround : créer dashboard custom :

1. Filtrer events « Add to Cart » sur 30 jours = 1 200.
2. « Begin Checkout » = 800 (drop 33%).
3. « Payment Method Selected » = 650 (drop 19%).
4. « Purchase » = 420 (drop 35%).

Conversion globale Add-to-Cart → Purchase = 35%.

Erreurs fréquentes

Erreur	Cause	Solution
Events absents Umami	umami.track avant script chargé	Wrapper avec window.umami check
Properties null	Variables undefined	Toujours fallback default
Currency string vs number	Type mixe	Forcer parseFloat()
Purchase compté 2 fois	Reload page thank-you	localStorage flag déjà tracké
UTM perdus	Pas pré-fillés	Persister via cookie session
Bots déclenchent events	Auto submit forms	Honeypot + bot detection

Ce que change l’environnement ouest-africain

Quatre précisions. Multi-currency : tracker par order la currency exacte. Dashboard filtre par currency permet ROI par marché. Mobile money tracking : Wave et Orange Money critiques. Funnel par provider révèle goulots. WhatsApp clicks : 60% du trafic conversion en Afrique passe par WhatsApp Business. Tracker chaque clic = mesure ROI canal. Tabaski/Ramadan campaigns : UTM source spécifique = comparable vs périodes normales.

Tutoriels frères

• Déployer Umami
• Umami vs Plausible

FAQ

Limite events ? Pas de limite hard. 1M events/mois confortable sur CX23 (anc. CX22, hausse tarifaire avril 2026).

Properties type ? String, number, boolean. Object nested non recommandé.

Filter events par date ? Oui via Dashboard date picker.

Export CSV events ? Oui via API ou Dashboard export.

Plausible compatible ? Non, APIs différentes. Wrapper script possible si nécessaire.

À lire ensuite

• 🔝 Retour au guide général : guide pratique Umami 2026
• Documentation Events : umami.is/docs/track-events

Étape A — Comprendre la différence event vs goal vs conversion

Avant d’instrumenter quoi que ce soit, clarifiez le vocabulaire Umami v2.13+. Un event est un point de mesure brut (un clic, un scroll, une soumission). Un goal est une vue agrégée d’un event (ou groupe d’events) que vous voulez suivre comme conversion business. Un visit est une session utilisateur. Confondre les trois mène à des dashboards illisibles et des décisions produit fausses.

Règle pratique : nommez vos events comme des actions verbales en kebab-case (signup-newsletter, add-to-cart, click-whatsapp) et vos goals comme des KPI métier (Acquisition Newsletter, Achat WooCommerce). Cette discipline rend les rapports lisibles pour un product manager qui ne connaît pas le code.

Étape B — Initialiser umami.js avec data-website-id

Avant tout tracking custom, vérifiez que le snippet de base est bien chargé. Dans le <head> de votre layout, collez :

<script defer src="https://umami.votre-domaine.io/script.js"
  data-website-id="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  data-do-not-track="true"
  data-cache="true"></script>

L’attribut data-do-not-track="true" respecte le header DNT du navigateur — utile pour rester en conformité avec le RGPD européen et la loi 2008-12 sénégalaise sans bandeau cookie. Sortie attendue : ouvrez la DevTools Network tab, vous voyez une requête POST vers /api/send avec un type:"event" et un payload qui contient l’ID du site et l’URL courante.

Étape C — Tracker un signup newsletter Brevo ou Mailchimp

Sur le formulaire newsletter, attachez un listener au submit. Voici un exemple sur un formulaire HTML natif :

document.querySelector('#newsletter-form').addEventListener('submit', (e) => {
  const email = e.target.email.value;
  const source = window.location.pathname;
  umami.track('signup-newsletter', { source, has_at: email.includes('@') });
});

Sortie attendue : ouvrez Umami → votre site → Events tab, vous voyez signup-newsletter qui apparaît avec les properties source (page d’origine) et has_at (validation email basique). Vous pouvez ensuite filtrer par source pour identifier quelle page convertit le mieux.

Étape D — Tracker l’add-to-cart WooCommerce

WooCommerce déclenche un événement jQuery added_to_cart à chaque ajout panier. Hookez Umami dessus :

jQuery(document.body).on('added_to_cart', (event, fragments, cart_hash, button) => {
  const product_id = button.data('product_id');
  const product_name = button.closest('.product').find('.woocommerce-loop-product__title').text();
  umami.track('add-to-cart', { product_id, product_name });
});

Si vous utilisez WooCommerce Blocks (Cart Block React), interceptez plutôt l’action Redux wc/store/cart/itemIsPendingQuantity. Documentez le choix dans votre fichier tracking.js pour qu’un dev qui reprend le projet dans 18 mois comprenne pourquoi vous écoutez l’un ou l’autre.

Étape E — Tracker un paiement Wave, Orange Money, Mixx by Yas

Sur la page de confirmation de paiement, déclenchez un event avec le moyen de paiement et le montant en FCFA :

// Page /merci?order=12345
const params = new URLSearchParams(window.location.search);
const order_id = params.get('order');
fetch(`/api/order/${order_id}`).then(r => r.json()).then(order => {
  umami.track('purchase', {
    order_id: order.id,
    amount_fcfa: order.total,
    payment_method: order.payment, // wave | orange-money | mixx-by-yas | card
    products_count: order.items.length
  });
});

Avec ces props, vous générez des rapports comme « Conversion par moyen de paiement » qui révèlent que Wave performe mieux à Dakar tandis que Mixx by Yas (ex Free Money) cartonne à Thiès. Ces insights orientent vos campagnes marketing par zone.

Étape F — Créer un goal côté Umami pour suivre la conversion

Dans Umami → Settings → Websites → votre site → Reports → Goals → New goal. Choisissez Event goal → sélectionnez purchase → définissez la valeur en CFA si vous voulez calculer le revenue. Sortie attendue : sur le dashboard, le widget Goals affiche le taux de conversion (purchases / visites) et le revenue total agrégé sur la période.

Astuce : créez un goal « Funnel Newsletter → Achat » via Umami v2.13 Funnels (Reports → Funnels → New) avec étapes signup-newsletter → add-to-cart → purchase. Vous identifierez immédiatement à quelle étape vos prospects décrochent.

Étape G — Tracker click WhatsApp Business contact

Sur les sites ouest-africains, le bouton WhatsApp est souvent le premier CTA. Pour le mesurer :

document.querySelectorAll('a[href^="https://wa.me/"], a[href^="https://api.whatsapp.com/"]').forEach(a => {
  a.addEventListener('click', () => {
    umami.track('click-whatsapp', {
      number: a.href.match(/(\d{8,})/)?.[1],
      page: location.pathname
    });
  });
});

Sortie attendue : chaque clic sur un lien wa.me/221XXXXXXXX envoie un event click-whatsapp avec le numéro et la page d’origine. Vous repérez vite quelle page produit (catalogue, fiche détail, footer) déclenche le plus de prises de contact — souvent ce n’est pas celle qu’on croit.

Étape H — Bonnes pratiques de naming et limite des properties

Umami limite à 50 properties par event et 50 caractères par nom de property. Au-delà, les valeurs sont silencieusement tronquées. Évitez aussi de stocker des PII (email, numéro de téléphone, adresse) dans les properties — vous violeriez la loi 2008-12 et le RGPD. Hash MD5 ou SHA-256 si vous avez vraiment besoin d’un identifiant utilisateur côté analytics.

Convention recommandée : préfixez vos events par leur domaine fonctionnel (checkout-add-to-cart, checkout-purchase, auth-signup, auth-login). Vous pourrez ensuite filtrer en bulk avec un wildcard checkout-* dans la barre de recherche. Sur le même thème sur la stack analytics self-hosted, voir notre tutoriel déployer Plausible sur Hetzner avec Coolify et le guide Astro sur Cloudflare Pages ou Coolify.