What is Event Tracking?

Event Tracking adds context to the time people spend on the pages of your website or app. Whereas page view data tells you how many people are exposed to pages on your website. With a little configuration, Events can go further and tell you what users do while they are there.

For example, 100 people may visit your homepage for 20 minutes, but you won’t necessarily know what they were doing at that time. Did they simply walk away from the screen and grab a coffee? Or did they spend time watching a promotional video, which led to them starting to add their details to a newsletter subscription form which they couldn’t complete due to an error?

Every website is unique, so the specific events that you want to track and the method will often vary. However, there are common website elements that make sense to track with events. You can find a selection of the most popular use cases, and the types of questions they can answer below.

Common Event Tracking Use Cases

  • Compliance Interactions – How many people opt out of advanced marketing cookies?
  • Page Interactions – Are people clicking on your fancy tabbed content? Or that image lightbox?
  • Document Downloads – How many people download your PDF brochures?
  • Ecommerce Interactions – Do people add your products to their cart and never complete their purchase?
  • Form Events – Are there any problems with your forms? Do people start completing them but never actually submit? Although you may want to consider Form Analytics too.
  • Lead Generation – On which pages, are people completing your newsletter opt-in form?
  • Non-Page Links – How many people actually click email and phone links on your site?
  • Screen Interactions – Are people scrolling far enough to see your website footer?
  • Social Media buttons Interactions – How many people find your social media profiles from your site? Are they sharing content from those buttons on your blog posts?

As well as providing a high-level overview of how people interact with your website, Events are also perfect candidates for the configuration of Goal Conversions. For example, if you want visitors to complete a newsletter subscription form on your website:

  • Events can help you track how many people start and submit each form on your site.
  • Goals will report on how many visitors are converting to leads through your newsletter subscription form. They can also be used with the Funnels feature to track the full conversion path.

Together these provide all of the information you need to make informed, data-driven decisions to improve your website and digital user experience.

Where to View Event Tracking in Matomo

Now you know how to benefit from event tracking, let’s look at how you can get started. You can find the Events section within the Behaviour section of your Matomo dashboard once logged in.

When you first visit the Events section of your analytics it is likely you will not find any data. This is because, unlike page views, you need to manually implement the tracking of events, as the types of event and triggers will be different for every site.

Matomo Events

The Anatomy of an Event

Events consist of four primary components which need to be configured, only two of which are required:

  • Category (Required) – This describes the type of events you want to track. For example, Link Clicks, Videos, Outbound Links, and Form Events.
  • Action (Required) – This is the specific action that is taken. For example, with the Video category, you might have a Play, Pause and Complete action.
  • Name (Optional – Recommended) – This is usually the title of the element that is being interacted with, to aid with analysis. For example, it could be the name of a Video that was played or the specific form that is being submitted.
  • Value (Optional) – This is a numeric value and is often added dynamically. It could be the cost of a product that is added to a cart, or the completion percentage of a video.

The specific values for each of these components are completely customisable. The only requirements are that every Event must contain a Category and an Action, and if you include a Value then it must be a number.

Example Event Configurations

Tracking Brochure Downloads

  • Event Category: Downloads
  • Event Action: PDF Brochure Download
  • Event Name: Matomo Event Tracking Brochure
  • Event Value: blank

Tracking User Reviews

  • Event Category: Reviews
  • Event Action: Published Matomo Review
  • Event Name: blank
  • Event Value: 10

Best Practices For Setting Event Tracking Names

When creating Events in your analytics it is important to consider the names you use carefully, as they will remain there forever. You should use descriptive names so it is easy to understand your reports, even when you can only see the Event Category or Event Action, for example.

Letter case is important when defining Event Tracking values. Video, video, VIDEO, and ViDeO would all count as different events. Using consistent and descriptive names ensures that you will be able to understand and analyse the measured event data.

Implementing Event Tracking with Matomo

There are two main ways to set up event tracking within Matomo. The first is with the Tag Manager plugin built into Matomo. The second is by adding snippets of JavaScript code to your website itself. You can find more details on how to set up both methods below.

If you have Matomo Tag Manager installed, it is the easiest way to implement event tracking on your site. You can simply create a Tag for each type of event you want to track. Below you will find an example step-by-step guide for creating an Event that tracks email link clicks on your site.

  1. Set up and configure Matomo Tag Manager (create a container and install the container code)
  2. Click on Tag Manager in Matomo and visit the Tags page.
  3. Click the big green button to Create New Tag.
  4. Select the Matomo Analytics tag type.
  5. Give your Tag a descriptive name. For example; Matomo Event – Email Link Click
  6. Confirm your Matomo configuration. If you are not sure, use the default configuration.
  7. Select Event as the Tracking Type.
  8. You are now ready to add your event structure in the next few fields. Following our example, this would be:

    1. Event Category: Contact
    2. Event Action: Email Link Click
    3. Event Name: {{ClickDestinationUrl}}
    4. Event Value:
      Note: In the example above the Event Name is dynamically populated from a tag manager Variable which pulls the data from the website itself. You can browse these from the square code icon next to the field.
      Matomo Tag Manager - Event Name Variable
  9. The next step is to select your Trigger. Click the link to Create a new trigger now which will pop up several options. For this example, you would select All Links Click in the Click section which will bring up options to customise which links to track as events.

  10. For this example you can use All Email Links as the trigger Name.
  11. To limit the trigger so that it specifically targets email links, you’ll need to add a few details to the Only trigger when (optional) section. These steps will make sure only email links are counted:
    1. Select Click Destination URL in the first field
    2. Select starts with for the second field.
    3. Type mailto: in the last field which is the prefix used to create email links.
    4. Finalise the trigger by clicking the big green button to Create New Trigger.
  12. Now that the Trigger is attached to the Tag settings you can click to Create New Tag.
  13. Finally you will need to publish your container. You can do this from the success message that appears when you create a new tag or by selecting Publish in the menu.
    Matomo Tag Created Successfully
  14. Once your new event tracking tag is live, you should test that it is working. To do this, visit your site and click on an Email link. Then log in to Matomo, go to the Visitors section and click to view the Visits Log. This allows you to review visits in real-time and you should be able to see your visit with the event shown on the right-hand side.
    Event Tracking Visit Log

If you would like a more visual step-by-step with an alternative example, check out the Matomo tag manager event tracking guide on the blog.

How To Set Up Matomo Event Tracking With JavaScript

The second method of setting up event tracking requires a little more technical confidence. You will need to integrate a JavaScript snippet directly into your website’s code. Links are one of the most common elements for integrating with event tracking.

JavaScript offers a function called onClick that you can add to your links. A standard HTML link looks a little something like this:

<a href="mailto:name@example.com" title="Email Us">Email Us</a>

Links in HTML contain the base tag a and several attributes including the link set under href. You can extend HTML links with the JavaScript onClick function so they look a little something like this:

<a href="mailto:name@example.com" title="Email Us" onclick="_paq.push(['trackEvent', 'Contact', 'Email Link Click', 'name@example.com']);">Email Us</a>

As you can see above, the code largely follows the same format as the first link above, but with an additional onclick attribute. The actual JavaScript function that triggers the event is contained within the quotation marks. From the example above that would be:

_paq.push(['trackEvent', 'Contact', 'Email Link Click', 'name@example.com']);

The above code example tracks the following event data:

  • Event Category: Contact
  • Event Action: Email Link Click
  • Event Name: name@example.com

It works by telling Matomo that you want to push data into the platform _paq.push([ ]); and trackEvent defines the type of data being sent. Matomo then recognises the next two to four attributes as the Event’s; Category, Action, Name, Value.

You might also have noticed that the above code only shows three values after trackEvent. This is because the Event Value attribute is optional. If a Name or Value is not required, you can simply leave out the final parameters, rather than adding blank ones. For an example of an event where you may want to track a value, please see the sample below:

_paq.push(['trackEvent', 'eCommerce', 'Add to Wishlist', 'Smartphone', 1000]);

The above code example tracks when an item is added to a wishlist, with the value set to the item’s cost:

  • Event Category: Ecommerce
  • Event Action: Add to Wishlist
  • Event Name: Smartphone
  • Event Value: 1000

You may notice that as the value is a number, it does not require single quotation marks as the previous text strings do. If you’d like to learn more about tracking events with JavaScript, visit the Matomo developer guide.

How to get insights and improve your site based on Event Tracking Reports

Once you’ve collected some Events on your site it is time to start the analysis. There are a few different ways you can do this. The first is taking a detailed look at each individual user’s path through your website using the Segmented Visit Log.

The Segmented Visit Log

This feature is useful for getting really granular detail about Event completions. For example, if you want people to leave a review about your site and you’ve set that up as an event. You can dig into individual users and see what they were doing before they left a review so you can place more focus on that.

To review the Segmented Visit Log head to the Events section of the Matomo interface and find the specific Event you are looking for. Hover over the event title and two icons should appear; the first is the Segmented Visit Log icon Segmented Visit Log Icon, which will allow you to view a Visit Log for every person that has completed the event in question.

Event Tracking Segment Visit Log Link

Clicking this icon will open a popup that shows summary session logs for every person that has completed the event, as well as how many actions they took, and how long the visit was.

This kind of data can help you build a picture of what inspires conversions and can provide a base for pushing people through the process sooner. If you want to dig even deeper into a particular user you can click View visitor profile. Depending on your website configuration and data captured, this can even provide you with detail on the user’s previous sessions on the site.

Matomo Visitor Profile

Segmented event logs are especially valuable for analysing important events with low numbers of completions. You can really dig into each case to see how they got there and if there are any opportunities to improve the process. You can learn more about the User Profile here.

Row Evolution

The Row Evolution view is an alternative method of reviewing event data which is useful for analysing aggregated trends. This is a powerful feature when you do not want to dig into specific instances, and instead want a general feel for how a metric is evolving over time.

To get started with this feature, go to the main Events section in your dashboard. Within the Events table, hover your mouse over the row of the event you are interested in. You should now see the Row Evolution icon Line Chart Icon.

Event Tracking Row Evolution Link

Click on the Row Evolution icon Line Chart Icon to load an evolution graph showing the number of event completions over time, broken down by the time period that is currently set in the Matomo dashboard.

Event Tracking Row Evolution Graph

A great example of when you might want to use this view is if you make a substantial change to the page where the event occurs. For example, a review submission – where you want to see whether your change on a certain date has led to more people submitting reviews in the following month.

You can also use this feature retrospectively when you notice a dip in event completions to see when the trend began, and attempt to deduce what might have caused it. If you use the Matomo Annotations feature in your analytics, which we recommend, they are shown in the comment bubbles below the graph and can often offer a clue for significant changes.

Matomo Event Annotations

Alternative Event Visualisations

While it is important to understand the absolute number of times an event has occurred, it can be equally as important to understand the context around those visits. To do this, you can change the visualisation of event data within the Events section by looking for the second green icon (table icon Table Icon by default) underneath the Events Table. By clicking it you will see all of the different visualisation options available, including one to Display a table with Visitor engagement metrics.

Event Tracking Visualisation Menu

Display a table with Visitor engagement metrics

Selecting this option will add new columns for visit metrics in your events table. This can give you a quick understanding of how the number of event completions fits into the bigger picture. By default, you will see the number of visits leading to event completions. If you hover over this data you will also see this number as a percentage of total visits to your website.

Event Tracking Visitor Engagement

This view also provides an Event Value column. The Event Value is the sum of all Event Values of each event type. Alongside this, you will also see an average, minimum and maximum Event Value column for more context.


Insights is another visualisation of event data that can be helpful for understanding trends on your site. Insights provides a quick and simple list of what’s changed in relation to how many people are completing events on your site month over month or year over year. Within the Insights visualisation, a table is shown summarising the percentage increase or decrease of all events on your site.

Event Tracking Insights

You can access the Insights visualisation by clicking the Insights icon (shown below).

Insights Link

Graph Displays

There are also several novel graphs that you can use to display event data which you may find useful. These are; Vertical bar graph and Piecharts which can be useful for analysing the event distribution, or Tag cloud to see your most popular events at a glance by the size of the text. In each of these views, if you hover over the titles, they will show you the number of event completions.

Event Tracking Piechart Visualisation

Events Tracking API

Matomo also features a Tracking HTTP API and a PHP Reporting API which can interact with Event Tracking data. These are more advanced developer features that are beyond the scope of this document. You can find more information in our Developer API Reference.

Event Tracking Alternatives in Matomo

If you want accurate tracking of Media Interactions, such as video or audio plays etc., then you will probably be better served by the popular Matomo Media Analytics extension.

If you sell things through your website, then you should also make use of Matomo’s Ecommerce analytics, which go beyond standard event tracking.

If you want to track impressions and interactions with content, such as ads, you may also want to investigate the content tracking features in Matomo.

If you want to track clicks on links to external websites, then you should explore the outlink analytics feature within Matomo.

If you want to track file downloads, check out the downloads report available in Matomo.

If you want to track interactions with forms, the form analytics feature is very powerful.