Mastering Umami: A Deep Dive into Custom Event Tracking

umami.track('event-name');

umami.track('event-name', { type: 'category', value: 'detail' });

Let's say you have a newsletter signup button on your blog. You want to know how many people are clicking it. First, here’s your HTML:

<button id="newsletter-signup-btn">Subscribe to our Newsletter</button>

Now, you can add a small JavaScript snippet to your page that listens for a click on this button and sends an event to Umami.

const signupButton = document.getElementById('newsletter-signup-btn');

if (signupButton) {
  signupButton.addEventListener('click', () => {
    // This sends the event to your Umami instance
    umami.track('newsletter-signup-click');
  });
}

That's it! Now, every time a user clicks that button, an event named "newsletter-signup-click" will appear in your Umami dashboard. Simple, right?

Example 2: Adding Context with Data

Now for a more advanced scenario. Imagine you have a pricing page with three different plans: Basic, Pro, and Enterprise. You want to track which plan users are most interested in.

Here's the HTML, using data- attributes to store the plan name:

<button class="plan-button" data-plan="basic">Choose Basic</button>
<button class="plan-button" data-plan="pro">Choose Pro</button>
<button class="plan-button" data-plan="enterprise">Choose Enterprise</button>

Now, the JavaScript can be written to handle any of these buttons and send the specific plan data along with the event.

const planButtons = document.querySelectorAll('.plan-button');

planButtons.forEach(button => {
  button.addEventListener('click', () => {
    // Get the plan name from the data-plan attribute
    const plan = button.dataset.plan;

    // Send the event with a data payload
    umami.track('plan-selection', { type: 'plan', value: plan });
  });
});

In your Umami dashboard, you'll now see a single event called "plan-selection". When you click to view its details, you’ll be able to see a breakdown of how many times the `value` was "basic", "pro", or "enterprise". This is a game-changer for understanding user choice.

Best Practices for a Smart Event Strategy

Before you go and track every single click on your site, pause for a moment. A successful event tracking strategy isn't about collecting the most data; it's about collecting the right data. Here are a few tips to keep your analytics clean and useful.

Keep Your Naming Convention Clean

Your future self will thank you for this. Adopt a consistent naming convention from the start. A popular and effective format is object-action.

• cta-click
• form-submit
• video-play
• external-link-click

This makes your event list in Umami instantly scannable and easy to understand.

Start Small and Focus on KPIs

Don't try to boil the ocean. Identify the 1-3 most important actions on your site. These are your Key Performance Indicators (KPIs). Is it a sale? A lead generation? A signup? Start by tracking those. You can always add more events later as new questions arise.

Document Your Events

It might seem like overkill, but a simple spreadsheet or document that lists your events, their names, and what they signify is invaluable. It ensures consistency, especially if multiple people are working on the site, and serves as a quick reference when you're analyzing your data months down the line.

Making Sense of Your Data in Umami

Once you've implemented your events, where do you find them? In your Umami dashboard, you’ll see an "Events" section in the sidebar. This is your new command center. It will list all the event names you're tracking and the total count for each.

Clicking on any event name will drill down into the details, showing you a timeline of when it occurred and, crucially, any data payloads you sent along with it. This is where you’ll see the breakdown of your "plan-selection" event, proving that the Pro plan is, in fact, the most popular choice.

---

Mastering custom event tracking is the single most impactful step you can take to level up your analytics game. It elevates Umami from a simple, privacy-friendly pageview counter to a powerful tool for understanding genuine user engagement and intent. By moving beyond the "where" and focusing on the "what," you can finally start making data-informed decisions that truly improve your website and your business.

So, what's the one user action you wish you could measure right now? Start there. Implement one custom event today and watch the insights roll in.