Piwik: Tracking User Interactions

14 min read

Tracking events with Piwik

Many of you may be familiar with event tracking with Google Analytics; and many of you may not. In Google Analytics, event tracking is pretty structured. When you track an event with Google, you get five parameters:

  • Category: The name for the group of objects you want to track
  • Action: A string that is used to define the user in action for the category of object
  • Label: This is optional and is for additional data
  • Value: This is optional and is used for providing addition numerical data
  • Non-interaction: This is optional and will not add the event hit into bounce rate calculation if set to true

We are going over a few details on event tracking with Google Analytics because the custom variable feature we will be using for event tracking in Piwik is a little less structured. And a little structure will help you drill down the details of your data more effectively from the start. You won’t have to restructure and change your naming conventions later on and lose all of your historical data in the process. We don’t need to look over the code for Google Analytics. Just know that it may help to set up your event tracking with a similar structure.

If you had videos on your site, enough to track, you would most likely make a category of events Videos. You can create as many as you need for the various objects you want to track on your site:

  • Videos
  • Maps
  • Games
  • Ads
  • Blog posts (social media actions)
  • Products

As for the actions that can be performed on those Videos, I can think of a few:

  • Play
  • Pause
  • Stop
  • Tweet
  • Like
  • Download

There are probably more than you can think of, but now that we have these actions we can connect them with elements of the site. As for the label parameter, you would probably want to use that to store the title of the movie the visitor is interacting with or the page it is located on. We will skip the value parameter which is for numeric data because with Piwik, you won’t have a similar value. But non-interaction is interesting; it means that by default an action on a page counts to lower the bounce rate from that page since the user is doing something. Unfortunately, this is not a feature that we have using Piwik currently, although that could change in the future.

Okay, now that we have learned one of the ways to structure our events, let’s look at the way we can track events in Piwik. There is really nothing called event tracking in Piwik, but Piwik does have custom variables which will do the same job. But, since it is not really event tracking in the truest sense of the word, the bounce rate will be unaffected by any of the custom variables collected. In other words, unlike Google Analytics, you don’t get the non-interaction parameter you can set. But let’s see what you can do with Piwik.

Custom variables are name-value pairs that you can set in Piwik. You can assign up to five custom variables for each visitor and/or each page view. The function for setting a custom variable is setCustomVariable . You must call it for each custom variable you set up to the limit of five.

piwikTracker.setCustomVariable (index, name, value, scope);

And here are what you set the parameters to:

  • index: This is a number from 1 to 5 where your custom variables are stored. It should stay the same as the name of custom variable. Changing the index of a name later will reset all old data.
  • name: This is the custom variable name or key.
  • value: This is the value for name.
  • scope: This parameter sets the scope of the custom variable, whether it is being tracked per visit or per page. And what scope we set depends upon what we are tracking and how complex our site is.

So how do these custom variables fit our model of event tracking? Well we have to do things a little bit differently. For most of our event tracking, we will have to set our variable scope per page. There is not enough room to store much data at the visit level. That is good for other custom tracking you may need but for event tracking you will need more space for data.

So with page level custom variables, you get five name-value sets per page. So, we would set up our variables similar to something like this for a video on the page:

  • Index = 1
  • Name = “Video”
  • Value = “Play”,”Pause”,”Stop”,”Tweet”,”Like”, and so on
  • Scope = “page”

And this set of variables in using Piwik’s custom variable function would look like one of the following:

  • piwikTracker.setCustomVariable(1,”Video”,”Play”,”page”);
  • piwikTracker.setCustomVariable(1,”Video”,”Pause”,”page”);
  • piwikTracker.setCustomVariable(1,”Video”,”Tweet”,”page”);

Which one you would use would depend on what action you are tracking. You would use JavaScript in the page to trigger these variables to be set, most likely by using an onClick event on the button. We will go into the details of various event tracking scenarios later in this chapter.

You will notice in the previous snippets of code that the index value of each call is 1. We have set the index of the “Video” name to 1 and must stick to this now on the page or data could be overwritten. This also leaves us the two to five indexes still available for use on the same page.

That means if we have banner ads on the page, we could use one of the spare indexes to track the ads.


You will notice that Google event tracking has the label variable. As we are using page leveling custom variables with Piwik and the variables will be attached to the page itself, there is no need to have this extra variable in most cases. If we do need to add extra data other than an action value, we will have to concatenate our data to the action and use the combined value in Piwik’s custom tracking’s value variable. Most likely, if we have one banner on our video page, we will have more and to track those click events per banner, we may have to get a little creative using the following:

  • piwikTracker.setCustomVariable(2,”SidebarBanner”, “AddSlot1Click”,”page”);
  • piwikTracker.setCustomVariable(2,”SidebarBanner”, “AddSlot2Click”,”page”);
  • piwikTracker.setCustomVariable(2,”SidebarBanner”, “AddSlot3Click”,”page”);

Of course, it is up to you whether you join your data together by using CamelCase, which means joining each piece of data together after capitalizing each. This is what I did previously. You can also use spaces or underscores as long as it is understandable to you and you stick to it. Since the name and value are in quotation marks, you can use any suitable string.

And again, since these are custom variables, if you come up with a better system of setting up your event tracking that works better with your website and business model, then by all means try it. Whatever works best for you and your site is better in the long run.

So now that we have a general idea of how we will be tracking events with Piwik, let’s look at some specific examples and more in depth at what events are, compared to goals or page views.

Tracking social engagement

You know that you have a Facebook “Like” button on your page, a Twitter “tweet” button, and possibly lots more buttons that do various things at other sites that you yourself have no control over and can add no tracking code to. But you can track clicks on the button itself.

You use event tracking for what you could call micro-conversions. But there is really nothing micro about them. That Facebook “Like” could end up in many more sales or conversions than a standard conversion. They could be the route on the way to one or multiple conversions. There may be a blurry line between engagement goals and micro-conversions.

And really, it is up to you what weight you give to visitor actions on your site, but use events for something smaller than you would consider a goal. If your goal is sales on your website, that Facebook “Like” should cause a spike in your sales and you will be able to correlate that to your event tracking, but the “Like” is not the end of the road, or the goal. It is a stop on the way.

If your website is a blog and your goal is to promote advertising or your services with your content, then tracking social engagement can tell you which topics have the highest social interest so that you can create similar content in the future.

So what are some other events we can track? Of course, you would want to track anything having to do with liking, tweeting, bookmarking, or somehow spreading your site on a social network. That includes Facebook , Twitter , Digg , StumbleUpon , Pinterest , and any other social network whose button you put on your site. If you spent enough time to put the buttons on your pages, you can at least track these events. And if you don’t have buttons, you have to remember that each generation is using the Internet more often; smartphones make it available everywhere, and everyone is on a social network. Get with it.

And don’t forget to add event tracking to any sort of Follow Me or Subscribe button. That too is an event worth tracking.

We will also look at blog comments since we can consider them to be in the social realm of our tracking.

Tracking content sharing

So let’s look at a set of social sharing buttons on our website. We aren’t going to blow things out of proportion by using buttons for every social network out there, just two: Twitter and Facebook. Your site may have less and should have more, but the same methods we will explore next can be used for any amount of content sharing buttons.

We are event tracking, so let’s begin by defining what our custom variable data will be. We need to figure out how we are going to set up our categories of events and the actions. In this example, we will be using buttons on our Holy Hand Grenade site:

You will see our Twitter button and our Facebook button right underneath the image of our Holy Hand Grenade.

We are going to act as if our site has many more pages and events to track on it and use a naming convention that will leave room for growth. So we are going to use the category of product shares. That way we have room for video shares when we finally get that cinematographer and film our Holy Hand Grenade in action.

Now we need to define our actions. We will be adding more buttons later after we test the effectiveness of our Facebook and Twitter buttons. This means we need a separate action to distinguish each social channel.

  • Share on Facebook
  • Share on Twitter

And then we add more buttons:

  • Share on Google+
  • Share on Digg
  • Share on Reddit
  • Share on StumbleUpon

So let’s look at the buttons in the source of the page for a minute to see what we are working with:

<li class="span1">
<script type="text/javascript" src="http://platform.twitter.
<a href="https://twitter.com/intent/

<li class="span1"></li>

<li class="span1">
<script src="http://connect.facebook.net/en_US/all.
<fb:like href="http://dir23.com/" show_faces="false"
width="50" font=""></fb:like>


<p><a class="btn btn-primary btn-large">Buy Now >></a></p>

You see that the buttons are not really buttons yet, they are only HTML anchors in the code and JavaScript includes. Before we start looking at the code to track clicks on these buttons, we need to go over some details about the way Piwik’s JavaScript works. Setting a custom variable in Piwik using an onclick event is a very tricky procedure. To start with, you must call more than just setCustomVariable because that will not work after the Piwik tracking JavaScript has loaded and trackPageView has been called. But there is a way around this. First, you call setCustomVariable and then, in that same onclick event , you call trackLink , as in the next example:

<p><a href="buynow.html" class="btn btn-primary btn-large" onclick="
javascript:piwikTracker.setCustomVariable(2,'Product Pricing','View
Product Price','page');piwikTracker.trackLink();">Buy Now >></a></p>

If you forget to add the piwikTracker.trackLink() call, nothing will happen and no custom variables will be set.

Now with the sharing buttons, we have another issue when it comes to tracking clicks. Most of these buttons, including Facebook, Twitter, and Google+ use JavaScript to create an iframe that has the button. This is a problem, because the iframe is on another domain and there is not an easy way to track clicks.

For this reason, I suggest using your social network’s API functionality to create the button so that you can create a callback that will fire when someone likes or tweets your page. Another advantage to this method is that you will be sure that each tracked tweet or like will be logged accurately. Using an on_click event will cause a custom variable to be created with every click. If the person is not logged in to their social account at the time, the actual tweet or like will not happen until after they log in, even if they decide to do so. Facebook, Twitter, and Google+ all have APIs with this functionality.

But if you decide to try to track the click on the iframe, you can take a look at the code at http://www.bennadel.com/blog/1752-Tracking-Google-AdSense- Clicks-With-jQuery-And-ColdFusion.htm to see how complicated it can get. The click is not really tracked. The blur on the page is tracked, because blur usually happens if a link in the iframe is clicked and a new page is about to load.

We already have our standard Piwik tracking code on the page. This does not have to be modified in any way for event tracking. Instead we will be latching into Twitters and Facebook’s APIs which we loaded in the page by including their JavaScript.

twttr.events.bind('tweet', function(event) {
piwikTracker.setCustomVariable(1,'Product Shares','Share on

<script type="text/javascript">
FB.Event.subscribe('edge.create', function(response) {
piwikTracker.setCustomVariable(1,'Product Shares','Share on

We add these two simple scripts to the bottom of the page. I put them right before the Piwik tracking code. The first script binds to the tweet event in Twitter’s API and once that event fires, our Piwik code executes and sets our custom variable. Notice that here too we have to call trackLink right afterwards. The second script does the same thing when someone likes the page on Facebook.

It is beyond the scope of this book to go into more details about social APIs, but this code will get you started and you can do more research on your chosen social network’s API on your own to see what type of event tracking will be possible. For example, with the Twitter API you can bind a function to each one of these actions: click, tweet, retweet, favorite, or follow. There are definitely more possibilities with this than there is with a simple onclick event.

Using event tracking on your social sharing buttons will let you know where people share your line of Holy Hand Grenades. This will help you figure out just which social networks you should have a presence on. If people on Twitter like the grenades, then you should make sure to keep your Twitter account active, and if you don’t have a Twitter account and your product is going viral there, you need to get one quick and participate in the conversation about your product.

Or you may want to invest in the development of a Facebook app and you are not quite sure that it is worth the investment. Well, a little bit of event tracking will tell you if you have enough people interested in your website or products to fork over the money for an app.

Or maybe a person goes down deep into the pages of your site, digs out a gem, and it gets passed around StumbleUpon like crazy. This might indicate a page that you should feature on the home page of your website. And if it’s a product page that’s been hidden from light for years, maybe throw some advertising its way too.


Please enter your comment!
Please enter your name here