Welcome to the first in a series of new type of blog posts we will be bringing your way. The goal of these posts is to focus on features/modifications to Matomo (Piwik) you might not be aware of, as well as topics related to analytics in general. We are open to ideas for future posts as well, so don’t be shy to contact us and use the subject « Matomo Blog Topic Suggestion ».
For the first article, I wanted to tackle the world of Custom Variables.
Why Custom Variables?
The custom variable is what makes the difference between a simple program that collects visits and one that can rightly call themself an analytics package. The best thing about custom variables is the flexibility and the amazingly cool ways in which you can track users to add flavor to your stats. In short, there is no limit to your imagination, just your ability to copy and paste JavaScript into your code and some simple programming. So let’s jump in and see how to use custom variables with Matomo.
Custom Variables: Let’s Get Started
The first step in using a custom variable is setting things up right. Remember you can track up to 5 custom variables per visit and/or up to 5 custom variables per page view. If ever you used Google Analytics the set up is familiar. What you want to do is first consider what make sense to track. Maybe for example you want to track users who are members of your site. Here is how you would do it. Within the standard Matomo code, you would add the following in the standard Matomo code replacing the simple line
piwikTracker.trackPageView();
with the below:
[...]
piwikTracker.setCustomVariable(1, "VisitorType", "Member", "visit");
piwikTracker.trackPageView();
[...]
Custom Variable Basics
Before we move forward let’s take a slight detour to break down custom variables within Matomo a bit more. What does each part of this mean? Obviously the setCustomVariable, tells Matomo this is a custom variable, but what about the other bits?
The first parameter, denotes this is the first of the five custom variables we are using for the visit. It is called the INDEX. You should only use unique index numbers unless you want to overwrite your data. In other words, if you create another custom variable and assign it INDEX 1, then it will start tracking this new variable.
The second parameter in the string is known as NAME. In our example, this slot is taken by « VisitorType ». This is what will be used as the overall categorization of the variable.
The third slot is what is known as « VALUE ». In our example this would be « Member » or « Non Member ».
The last slot is taken by SCOPE. This determines how the information is stored. The « visit » scope means the custom variable will follow over the current session. The other option is « page ». This is useful if you have categories on your site, and you want to track how specific category landing pages perform. For more details on Custom Variables and the components, you can check out the documentation here.
Custom Variable WordPress Example Using Login Status
Now back to our lovely example. In the case of knowing if a user is a member or not, it requires a bit of code. But trust me it’s not that hard. Even with limited PHP skills and depending on the CMS or website you have built– what you need is usually easy to find. For example, in WordPress to determine if a user is logged in you use the function « is_user_logged_in« .
So to get the Matomo to display « Member » vs « Not Member », in the PHP code you would do the following:
[...]
piwikTracker.setCustomVariable(1, "VisitorType", "<?php if ( is_user_logged_in() ) {echo 'Member';} else {echo 'Not Member';} ?>", "visit");
piwikTracker.trackPageView();
[...]
Custom Variable Example Using WordPress Roles
That’s it. Now you can start tracking the behavior of those users who are members and those who are not. If you wanted to, you can even track based on role level. Using WordPress again, let’s say you wanted to know the difference of traffic between Editors vs. Contributor vs. Subscriber. In this case the function in WordPress is « get_current_user« . To do this, you would add to your code something like this
[...]
<?php
$current_user = wp_get_current_user();
if ( !empty($current_user->roles[0]) ) {
echo 'piwikTracker.setCustomVariable(2, "RoleType", "'.$current_user->roles[0].'", "visit");';
}
?>
[...]
All together, your code would look like this:
[...]
piwikTracker.setCustomVariable(1, "VisitorType", "<?php if ( is_user_logged_in() ) {echo 'Member';} else {echo 'Not Member';} ?>", "visit");
<?php
$current_user = wp_get_current_user();
if ( !empty($current_user->roles[0]) ) {
echo 'piwikTracker.setCustomVariable(2, "RoleType", "'.$current_user->roles[0].'", "visit");';
}
?>
piwikTracker.trackPageView();
[...]
Notice how we moved this to INDEX number 2, so as not to overwrite the Member Type in INDEX 1. And there you have it. You can now see the traffic differences between members vs. non-members, as well as how the different role types behave right in your Matomo install. To view the data you will find it in the Visitor tab of your Matomo install, but you can also add the widget to keep track of their behavior on your dashboard. Below is screenshot of the custom variables report:
Now it’s your turn. What are your favorite custom variables to track?
What are some creative things you have tracked with custom variables in the past?
See the next post about Custom Variables: Custom Variable Case Study: Divezone.net
