Custom Event Tracking: How to Set Up Events in Any Analytics Tool

Pageviews tell you how many people showed up. Custom event tracking tells you what they actually did. Every button click, form submission, video play, and file download that matters to your business needs to be tracked as an event — otherwise, you’re guessing which parts of your site drive results.

In this guide, I’ll show you how to set up custom event tracking across different analytics platforms — not just one tool, but a universal approach that works whether you’re using a privacy-first solution or a full-featured analytics suite. If you’re still building your tracking foundation, start with my complete conversion tracking guide first.

What Are Custom Events and Why Do They Matter?

An event in web analytics is any user interaction that goes beyond loading a page. Clicks, scrolls, form submissions, downloads, video plays — these are all events. Most analytics tools automatically track some basic events like pageviews. Custom events are the ones you define based on what matters to your specific business.

Here’s why this matters: without custom events, your analytics shows you a flat picture. You know someone visited your pricing page, but you don’t know if they clicked “Start Free Trial” or scrolled past it. You know 500 people landed on your blog post, but you don’t know if they downloaded the PDF resource at the bottom.

Custom events fill these gaps. They connect user behavior to business outcomes, giving you data you can actually act on.

Common Events Worth Tracking

Not every interaction needs an event. Focus on actions that signal intent or directly impact revenue:

• Button clicks — CTA buttons, “Add to Cart,” pricing toggles, demo requests
• Form submissions — contact forms, newsletter signups, lead generation forms
• File downloads — PDFs, whitepapers, case studies, media files
• Video engagement — play, pause, and percentage watched milestones (25%, 50%, 75%, 100%)
• Scroll depth — how far down the page visitors actually read
• Outbound link clicks — which external links your visitors follow
• Error events — 404 pages, failed form validations, broken checkout steps

My rule of thumb: if the event answers a business question, track it. If it’s just “nice to know,” skip it. Every unnecessary event adds noise to your reports.

The Anatomy of a Custom Event

Regardless of which analytics tool you use, most events share the same basic structure. Understanding this structure helps you design a consistent tracking plan.

Every event typically includes:

• Event name — what happened (e.g., form_submit, button_click, file_download)
• Event properties — additional context (e.g., which form, which button, which file)
• Event value — optional numeric value (e.g., purchase amount, subscription tier)

For example, tracking a newsletter signup might look like this:

Event name: form_submit
Properties: { form_name: "newsletter", page: "/blog/analytics-guide" }
Value: none

A clean naming convention is critical. I use snake_case for event names and keep them descriptive but short. cta_click is better than click (too vague) or user_clicked_the_main_call_to_action_button (too long).

Building an Event Tracking Plan

Before writing any code, create a simple spreadsheet with four columns:

This plan becomes your single source of truth. Share it with developers, marketers, and stakeholders so everyone knows what’s tracked and why.

How to Implement Custom Events: The Universal Approach

The implementation method varies by tool, but the underlying pattern is always the same: detect the interaction, then send the event data. Let me walk you through the two main approaches.

Approach 1: JavaScript Event Listeners

This is the most flexible method and works with any analytics tool. You attach a listener to the HTML element and fire the event when the interaction happens.

Here’s a basic example for tracking a button click:

// Track CTA button clicks
document.querySelector('.cta-button').addEventListener('click', function() {
  // Replace with your analytics tool's tracking call
  trackEvent('cta_click', {
    button_text: this.textContent,
    page_url: window.location.pathname
  });
});

The trackEvent function looks different depending on your platform. In Matomo, it’s _paq.push(['trackEvent', category, action, name]). In Plausible, it’s plausible('event_name', {props: {...}}). The concept is identical — only the syntax changes.

Approach 2: Data Attributes (No Custom JavaScript)

Many modern analytics tools support data attributes directly on HTML elements. This approach requires zero JavaScript knowledge and is easier to maintain.

<!-- Plausible example -->
<button class="cta-button" data-analytics='"cta_click"'>Start Free Trial</button>

<!-- Matomo Tag Manager example -->
<a href="/guide.pdf" data-track-content data-content-name="Analytics Guide PDF">Download</a>

Data attributes are great for teams where marketers manage the HTML but don’t write JavaScript. The analytics tool reads these attributes automatically and creates events without additional code.

Tracking the Most Common Events

Let me walk through the specific implementation for the events most teams need.

Button Clicks

Button click tracking is the foundation of event analytics. The key is being specific about which button was clicked:

// Track all buttons with a data-track attribute
document.querySelectorAll('[data-track]').forEach(function(button) {
  button.addEventListener('click', function() {
    trackEvent('button_click', {
      button_id: this.dataset.track,
      button_text: this.textContent.trim(),
      page: window.location.pathname
    });
  });
});

Then in your HTML, just add the attribute to any button you want to track:

<button data-track="hero-cta">Get Started</button>
<button data-track="pricing-annual">Choose Annual Plan</button>

This approach scales easily. When you want to track a new button, you add one HTML attribute instead of writing new JavaScript.

Form Submissions

Track form submissions on the submit event, not the button click. This ensures you only capture successful submissions, not clicks on disabled buttons or validation-blocked attempts:

document.querySelectorAll('form[data-track]').forEach(function(form) {
  form.addEventListener('submit', function() {
    trackEvent('form_submit', {
      form_name: this.dataset.track,
      page: window.location.pathname
    });
  });
});

Important: never track the actual form field values (email, name, phone). That violates GDPR principles and defeats the purpose of privacy-first analytics. Track that a form was submitted, not what was submitted.

File Downloads

Most privacy-first tools like Plausible track file downloads automatically. For other tools, intercept clicks on download links:

// Auto-track downloads for common file types
document.querySelectorAll('a[href$=".pdf"], a[href$=".zip"], a[href$=".xlsx"]')
  .forEach(function(link) {
    link.addEventListener('click', function() {
      var fileName = this.href.split('/').pop();
      trackEvent('file_download', {
        file_name: fileName,
        page: window.location.pathname
      });
    });
  });

Scroll Depth

Scroll depth tells you whether visitors actually read your content or just bounce after the first paragraph. I track one threshold — 75% — because it indicates genuine engagement without flooding your data with noise:

var scrollTracked = false;
window.addEventListener('scroll', function() {
  if (scrollTracked) return;
  var scrollPercent = (window.scrollY + window.innerHeight) / document.body.scrollHeight * 100;
  if (scrollPercent >= 75) {
    scrollTracked = true;
    trackEvent('scroll_depth', {
      depth: '75%',
      page: window.location.pathname
    });
  }
});

Event Tracking Across Different Platforms

The JavaScript patterns above are universal, but each analytics platform has its own API for sending events. Here’s a quick reference.

Notice the pattern: every tool takes an event name and optional properties. If you build your tracking plan around this universal structure, switching tools later is a matter of changing one function — not rewriting your entire tracking setup.

Testing and Debugging Your Events

Implementing events is only half the job. You need to verify they’re firing correctly before trusting the data.

Use Your Browser’s Developer Console

Open DevTools (F12), go to the Network tab, and filter by your analytics domain. Every event you trigger should appear as a network request. Click on it to inspect the payload — make sure the event name and properties match your tracking plan.

Check Real-Time Reports

Most analytics tools offer a real-time view. After triggering an event on your site, switch to the real-time dashboard and confirm it appears. If it doesn’t show up within 30 seconds, something is wrong — usually a JavaScript error or a Content Security Policy blocking the request.

Common Debugging Checklist

• Event not firing? — Check for JavaScript errors in the console. Often a typo in the selector
• Event fires multiple times? — You’re probably attaching the listener inside a loop or SPA navigation callback
• Properties missing? — Verify the element has the expected data attributes or text content
• Events in dev but not production? — Check if your analytics script is loaded. Ad blockers in development browsers might block it

Common Mistakes That Ruin Your Event Data

I’ve seen these wreck tracking setups more times than I can count. Avoid them from the start.

Tracking everything. More events doesn’t mean more insight. If you track 50 events but only check 5 of them, you’ve created noise. Start with 5–10 essential events tied to actual business questions. Add more only when you have a specific reason.

Inconsistent naming. When one developer uses formSubmit, another uses form_submitted, and a third uses submit_form, your reports are a mess. Define your naming convention in the tracking plan and enforce it. I recommend snake_case with the format object_action — like form_submit, button_click, video_play.

Not testing in production. Your staging environment and production site can behave differently. Always verify events on the live site — especially after deployments that change page structure or JavaScript bundles.

Ignoring event volumes. An event that fires 10,000 times a day on a site with 1,000 daily visitors is broken. Set up alerts for unusual spikes. A sudden 10x increase in form_submit events usually means a bot, not a marketing breakthrough.

Tracking personal data in event properties. Never send email addresses, names, phone numbers, or user IDs as event properties. This is a data protection violation waiting to happen. Track the action, not the person.

From Events to Insights: What to Do With the Data

Collecting events is step one. The real value comes from analyzing patterns and making changes.

Build conversion funnels. Chain events together to see where users drop off. My funnel analysis guide covers this in detail. For example: page_view → cta_click → form_submit → thank_you_page. If 1,000 people view the page but only 50 click the CTA, your headline or button placement needs work — not your form.

Compare event rates across segments. Do mobile visitors click the CTA at the same rate as desktop? Do visitors from organic search submit forms more than those from paid ads? These breakdowns often reveal actionable differences.

Set up alerts. Most analytics tools let you create alerts when an event rate drops below a threshold. A sudden decrease in form_submit events could mean a broken form — and every hour it stays broken is lost revenue.

If you’re looking to take this further, building out full analytics infrastructure with the right tools makes event analysis significantly more powerful.

What’s Next

Custom event tracking transforms your analytics from a traffic counter into a decision-making tool. Start with 5–10 events tied to real business questions, use a consistent naming convention, and test everything before trusting the data.

The tracking plan spreadsheet I described above is your most important deliverable. Get that right, and implementation becomes straightforward regardless of which analytics platform you choose.

In upcoming guides, I’ll cover server-side event tracking for capturing data that client-side scripts miss, and e-commerce conversion tracking for mapping the full purchase journey.