Set up User ID tracking in Matomo

To enable User ID functionality, you need to start sending User IDs to Matomo. First, you will need to identify what data your site holds for each user that can be used as a User ID. Every website system that allows people to log in should have at least one unique identifier that it uses to differentiate between users. This may be a unique number, a username, or simply a user’s email address.

It is recommended you set a user’s email address as a User ID if you can. This is because it will also allow you to track the same user when they complete a contact or subscription form, even while they are logged out.

The next step is to send this unique identifier through to Matomo Analytics. The exact method for doing this will vary depending on how your site was built. You can find step-by-step instructions for the various methods below.

How to Configure User ID Tracking for WordPress

If you are using WordPress, there are two main ways to integrate with Matomo. The first is with the official Matomo for WordPress plugin, which is where Matomo lives entirely inside your WordPress installation. In this case, you can follow the Matomo for WordPress guide below.

Alternatively, if you are using Matomo Cloud or Matomo On-Premise, you will likely be using the WP-Matomo plugin to integrate WordPress. In this case, the steps you need to follow are shown in the second guide listed below.

Note: WordPress users can typically change their email address, but not their username. When selecting a unique identifier in the guides below, select Username if you want the most reliable long-term identifier. However, if you also want to capture a User ID from form submissions of logged out users too, you should use Email Address instead.

Matomo for WordPress: How to Enable User ID Tracking

  1. Log in to your WordPress dashboard with an admin account.
  2. Hover over Matomo Analytics in the menu and click Settings within the sub-menu.
  3. Scroll down to the User ID dropdown and select Email Address or Username.
  4. Click the blue Save Changes button below, and User ID tracking will be enabled.

Connect Matomo (WP-Matomo, WP-Piwik): How to Enable User ID Tracking

  1. Log in to your WordPress dashboard with an admin account.
  2. Hover over Settings in the menu and click on Connect Matomo.
  3. Click on the Enable Tracking tab.
  4. Enable a non-manual tracking method in the Add tracking code setting.
  5. Scroll down to the User ID Tracking setting and select Email Address or Username in the dropdown.
  6. Click the blue Save Changes button, and User IDs will begin tracking immediately.

How to Configure User ID Tracking with Matomo Tag Manager

The method for configuring User ID tracking with Matomo Tag Manager will vary depending on how your website has been built. As there is no standardised way of including User IDs within your website code, you will likely need to set this up yourself or get developer assistance.

  1. Install and configure Matomo Tag Manager for your site.
    Learn more about getting started with Matomo Tag Manager.

  2. Create a variable called UserID that captures each visitor’s unique user identifier.
    If you display usernames on the front-end of your site, you may want to create a variable from a HTML DOM selector whilst a user is logged in. Or, for a more flexible method, you can configure your website to expose a user’s unique identifier, such as an email address, to the data layer with a little custom code. The simplest method for making sure that a user’s email address can be read consistently and tracked to Matomo may be to first build your website so that it has a cookie which contains the value of your visitor’s email address in a first-party cookie. Then, in Matomo, a Matomo Tag Manager variable can be configured to read directly from a First-Party cookie. Or consider this alternative: store the email address as local storage in the browser instead. This would then need to be retrieved using a Custom Javascript Variable that retrieves the value from local storage to be used in the Tag Manager as a variable.

  3. Create or update your Matomo Configuration variable to collect the UserID.
    Assuming you named your User ID variable in the last step UserID, you would scroll down to the User ID text field and input {{UserID}} to pull the values captured by that variable into your Matomo tracking configuration.

  4. Preview and publish your updated Matomo container.
    While previewing, you can visit your website and a Matomo Tag Manager debug screen will show at the bottom half of your screen. You can click the Variables tab within this to ensure the UserID variable is being picked up correctly by Matomo Tag Manager. Once confirmed, publish your container to begin tracking User IDs.
    Matomo Tag Manager Container Preview

How to Send User ID with the JavaScript Client

If you have a completely custom website, you can add a JavaScript snippet of code to your website which sends the User ID to Matomo via the Javascript Tracking API. To do this, you would add the unique identifier for a user to the following snippet of code:

_paq.push(['setUserId', 'USER_ID_HERE']);

The example above, _paq.push([ ]); sends the data to Matomo. 'setUserId' defines what data is being sent, and you should configure the second argument 'USER_ID_HERE', to dynamically contain the unique User ID of the visitor currently viewing the page. This code should be placed within your Matomo tracking code, above the action that you are tracking.

For example, the code above within the standard Matomo pageview tracking code would look a little something like this:

<!-- Matomo -->
<script type="text/javascript">
  var _paq = window._paq = window._paq || [];
  _paq.push(['setUserId', 'USER_ID_HERE']);
  _paq.push(['trackPageView']);
  _paq.push(['enableLinkTracking']);
  (function() {
    var u="//{$MATOMO_URL}/";
    _paq.push(['setTrackerUrl', u+'matomo.php']);
    _paq.push(['setSiteId', {$IDSITE}]);
    var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0];
    g.type='text/javascript'; g.async=true; g.src=u+'matomo.js'; s.parentNode.insertBefore(g,s);
  })();
</script>
<!-- End Matomo Code -->

For more details on this method, consult the developer documentation on User IDs.

How to Send User ID with Matomo SDKs

There are several Matomo Software Development Kits (SDK) available for use in apps. If you are using one of these, for example, the iOS SDK or Android SDK, you typically need to call the API function setUserId() with the User ID as a parameter. Alternatively, you may also be able to make use of the Tracking HTTP API.