Implement Event tracking with Matomo

Cloud On-Premise

There are two ways to set up Event tracking within Matomo. The first is with Tag Manager built into Matomo. The second is by adding snippets of JavaScript code to your website itself. This guide describes both tracking methods.

Installing Matomo Tag Manager 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. The example used shows how to create an Event that tracks email link clicks on your site. Learn how to configure Matomo Tag Manager containers and install the container code for tracking.

Add a Matomo Event tracking tag

  1. In Matomo, go to Tag Manager > Tags.
  2. Click Create New Tag and select the Matomo Analytics tag type.
  3. Give your Tag a descriptive name. For example; Matomo Event – Email Link Click
  4. Confirm your Matomo configuration. If you are not sure, use the default configuration.
  5. Select Event as the Tracking Type.

  6. You are now ready to add your event structure in the next few fields. For example:

    Event Category: Contact
    Event Action: Email Link Click
    Event Name: {{ClickDestinationUrl}}
    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 code icon next to the field.
    Matomo Tag Manager - Event Name Variable

  7. Select a Trigger or create a new one. Click the link to Create a new trigger now and choose the All Links Click trigger type in the Click section.

  8. Configure the options as required. 10. For this example, use All Email Links as the trigger Name.

  9. To limit the trigger so that it specifically targets email links, include additional details to the Only trigger when (optional) section. These steps will make sure only email links are counted:

    • Select Click Destination URL in the first field
    • Select starts with for the second field.
    • Type mailto: in the last field which is the prefix used to create email links.
    • Finalise the trigger by clicking the big green button to Create New Trigger.
  10. Now that the Trigger is attached to the Tag settings you can click to Create New Tag.
  11. 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
  12. 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

Note: With event tracking, Matomo Tag Manager can easily trigger tags based on identifiers like IDs or classes. However, if data attributes are missing, you may find it challenging to set up a trigger. To address this, consider modifying your source code to add a unique ID, class, or other HTML attributes to the element you want to track. This change may require assistance from a developer.

For more resources, refer to the Tag Manager workflow and learn more about the data layer in Tag Manager.

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

Because the value is a number, it does not require single quotation marks as the previous text strings do. To learn more about tracking events with JavaScript, visit the Matomo developer guide.