Configuration
-

Statistics analysis
-

Statistics analysis

User ID †

If you are using the Tracker API directly you may set the User ID via the Tracker API parameter &uid=USER_ID.

Also, you can set a User ID in JavaScript:

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

Once you have implemented User ID you may segment your traffic based on the User ID value. See the userId segment in the Segmentation Reference.

Event Tracking †

Requesting Events report data

You may use the Events API to request all data for Events, including any report combining Event Categories, Event names and Event actions (see &secondaryDimension= parameter)

Tracking Events

To track an event, use the Javascript function:

trackEvent(category, action, [name], [value])

If you wanted to track a click on a JavaScript menu, you could write:

<a href="#" onclick="javascript:_paq.push(['trackEvent', 'Menu', 'View Similar Products', 'MenuClick']);">Similar Products</a>

You may also track numeric values for your event:

_paq.push(['trackEvent', 'Documentary', 'Rating', 'Thrive', 9.5]);

Piwik reports for events will include the Total Event value, the Average event value as well as the Minimum and Maximum value, for each Event Category and each Event Name and each Event Action.

Content Tracking †

Tracking Content

Mark each content block with a data-track-content HTML attribute or piwikTrackContent CSS class. Then activate content tracking by calling one of those two methods:

_paq.push(['trackPageView']);

// To track all content blocks within a page.
_paq.push(['trackAllContentImpressions']);
// To track only visible content blocks within a page.
_paq.push(['trackVisibleContentImpressions', boolCheckOnSroll, intTimeIntervalInMs]);
// To track content impressions only for a part of the page
_paq.push(['trackContentImpressionsWithinNode', domNode]);

For a list of all available methods have a look at the JavaScript Tracker reference. Developers should have a look at the in-depth guide on how to track content.

Use Content Tracking from any application or server, with the Tracking API. View the Content Tracking HTTP API here.

Track an interaction semi-automatic

In case you want to trigger an interaction based on a form submit or a double click. To do so call the method trackContentInteractionNode(domNode, contentInteraction).

formElement.addEventListener('submit', function () {
  _paq.push(['trackContentInteractionNode', this, 'submittedForm']);
});

You should disable the automatic interaction tracking of that content block by setting the CSS class piwikContentIgnoreInteraction or the attribute data-content-ignoreinteraction. Otherwise an interaction might be tracked on top of it as soon as a visitor performs a click.

Tracking content impressions and interactions manually

You should use the methods trackContentImpression() and trackContentInteraction() only in conjunction together.

_paq.push(['trackContentImpression', 'Content Name', 'Content Piece', 'http://www.example.com']);

div.addEventListener('click', function () {
  _paq.push(['trackContentInteraction', 'tabActivated', 'Content Name', 'Content Piece', 'http://www.example.com']);
});

Track content this way if you cannot easily change the markup of your site or if you want complete control over all tracked impressions and interactions.

Be aware that each call to those methods will send one request to your Piwik tracker instance. Doing this too many times can cause performance problems.

Declarative content tracking

The following attributes and their corresponding CSS classes are used for tagging HTML blocks:

HTML Attributes (<-recommended) always take precedence over CSS classes. If you set the same attribute or the same class on multiple elements within one block, the first element found will always win. Nested content blocks are currently not supported.

<a href="http://ad.example.com" data-track-content>
  <img src="http://www.example.com/path/xyz.jpg" data-content-piece />
</a>
// content name   = /path/xyz.jpg
// content piece  = http://www.example.com/path/xyz.jpg
// content target = http://ad.example.com

Track Goals and Measure Conversions †

A goal can only be converted once per visit maximum. Piwik considers that the same Goal triggered twice or more is mostly likely because of spam or double clicks behaviors.

A same visit can, however, convert several Goals (eg. “Buy a product” and “Contact support”). A visit that converts one or more goals is reported as a “Visit with conversion”.

Report Analysis: What are the Top Converting Segments?

Piwik Goal reports will help you answer some of these questions (and more!).

1. You are buying advertisement on Google, Yahoo and Facebook. How can you measure the quality of the traffic sent by these ads, which campaigns and which keywords work best to convert visitors? Out of all of the websites bringing you traffic, which websites send you visitors that convert most? Can you develop stronger links with these websites, or find similar partners?
2. If you use Piwik Campaign tracking, you can track the performance of your Newsletters, PPC Campaigns and keywords to see how each contribute to your Goal conversions and overall revenue. You can see exactly the revenue and conversion rates for each campaign and keyword. If you have affiliates linking to your pages, you can see exactly which affiliates bring you visitors with the most conversions and/or which have the highest revenue per visit.
3. What time of day sees the lowest activity? By checking Goal conversions by hour, you can decide what time is best for migrations and system updates.

An example of custom revenue tracking:

• Create a goal “Package ordered”.
• Set “Allow multiple conversions per Visit” to “Allow goal to be triggered more than once per Visit”. This will ensure that if a user makes several orders per visit, Piwik will track one goal conversion for each order.
• Look at the goal id, which can be found in the first column of the “Edit goals” table. Users will then purchase a package on your website. To register a Goal conversion when someone buys a package that costs $39, you can call the JS function to register a Goal in Piwik. In the footer of your checkout page, inside the Piwik JS code you already have, you would simply write: _paq.push(['trackGoal', 7, priceOfMyObject]);
  The variable priceOfMyObject can be dynamically set by your website software.

Custom Variables Analytics †

Tracking a Custom Variable

Custom variables are assigned in JavaScript by calling setCustomVariable(index, name, value, scope) to set a new custom variable to a visitor (scope="visit") or to the current page view (scope="page"). You can also fetch a custom variable by calling getCustomVariable(index, scope).

_paq.push(['setCustomVariable',
  1, // Index, the number where this custom variable name is stored
  "Gender", // Name, the name of the variable, for example: Gender, VisitorType
  "Male", // Value, for example: "Male", "Female" or "new", "engaged", "customer"
  "visit" // Scope of the custom variable, "visit" means the custom variable applies to the current visit
]);
_paq.push(['trackPageView']);

// Track 2 custom variables with the same name, but in different slots.
// You will then access the statistics about your articles' categories in the 'Visitors > custom variables' report
_paq.push(['setCustomVariable', 1, 'Category', 'Sports', 'page']);
// Track the same name but in a different Index
_paq.push(['setCustomVariable', 2, 'Category', 'Europe', 'page']);
// Here you could track other custom variables with scope "page" in Index 3, 4 or 5
// The order is important: first setCustomVariable is called and then trackPageView records the request
_paq.push(['trackPageView']);

If you measure Goals or use Ecommerce Analytics, note that when the conversion occurs Piwik will copy any custom variables of scope “visit” in the Conversion. You can then view Conversion rates by Goal (and Ecommerce conversion rate) for each of your “visit” scope custom variables.

Adding more Custom Variable slots

By default Piwik provides 5 custom variables. You may configure Piwik to track more custom variables. New custom variable slots will be created in both the ‘visit’ scope and ‘page’ scope.

$ cd /path/to/piwik
$ ./console customvariables:info

****************************************************
  Your Piwik is configured for 5 custom variables.
****************************************************

$ ./console customvariables:set-max-custom-variables 10

Deleting a Custom Variable

// deleteCustomVariable(index, scope)
_paq.push(['deleteCustomVariable', 1, "visit"]); // Delete the variable in index 1 stored for the current visit
_paq.push(['trackPageView']);

Retrieving a Custom Variable

// getCustomVariable(index, scope)
_paq.push([ function() {
  var customVariable = this.getCustomVariable(1, "visit");
  // Returns the custom variable: ["gender", "male"]
  // do something with customVariable...
}]);
_paq.push(['trackPageView']);

By default, it will only work for custom variables that were set during the same page load. But it is possible to configure Piwik so that getCustomVariable will also return the name and value of a custom variable of scope “visit”, even when it was set in a previous pageview in the same visit. To enable this behavior, call the Javascript function storeCustomVariablesInCookie before the call to trackPageView. This will enable the storage of Custom Variables of scope “visit” in a first party cookie. The custom variables cookie will be valid for the duration of the visit (30 minutes after the last action). You can then retrieve the custom variable names and values using getCustomVariable. If there is no custom variable in the requested index, it will return false.

Custom Dimensions †

The Custom Dimensions plugin is available on the Piwik Marketplace for free.

comparison of Custom Dimensions and Custom Variables

Creating Custom Dimensions

To get to the “Manage Custom Dimensions” screen click on the user icon in the top right. There will be a new menu item “Custom Dimensions” in the left menu.

Before creating a new Custom Dimension you have to choose whether you need a new dimension in scope "Visit" or "Action".

Custom Dimensions in scope “Visit” can be sent along any tracking request and are stored in the visit of a specific visitor. If you set different values for a given dimension during the lifetime of a visit, the last value set will be used. A typical example could be any device information or the version of the app the visitor is using.

Adding more Custom Variable slots

./console customdimensions:add-custom-dimension --scope=action
./console customdimensions:add-custom-dimension --scope=visit

Be aware that this can take a long time depending on the size of your database as it requires MySQL schema changes. You can directly create multiple Custom Dimension slots. To do this add the option –count=X. Usually it doesn’t take much longer to create directly multiple new slots.

Deleting a Custom Dimension and all of its data

In the UI it is only possible to deactivate a dimension. However, on the command line you can remove a Custom Dimension and report it’s log data by executing the following console command:

./console customdimensions:remove-custom-dimension --scope=$scope --index=$index

Make sure to replace $scope and $index with the correct values. To get a list of all available indexes execute:

./console customdimensions:info

Tracking a Custom Dimension

Tracking a Custom Dimension across tracking requests

_paq.push(['setCustomDimension', customDimensionId = 1, customDimensionValue = 'Member']);

Please note once a Custom Dimension is set, the value will be used for all following tracking requests and may lead to inaccurate results if this is not wanted. For example if you track a page view, the Custom Dimension value will be as well tracked for each following event, outlink, download, etc. within the same page load. To delete a Custom Dimension value after a tracking request call _paq.push(['deleteCustomDimension', customDimensionId]);

Tracking a Custom Dimension for one specific action only

It is possible to set a Custom Dimension for one specific action only. The advantage is that the set dimension value will be only used for this particular action and you do not have to delete the value after a tracking request.

To define a dimension value pass an object defining one or multiple properties as the last parameter.

_paq.push(['trackEvent', category, action, name, value, {dimension1: 'DimensionValue'}]);
_paq.push(['trackSiteSearch', keyword, category, resultsCount, {dimension1: 'DimensionValue'}]);
_paq.push(['trackLink', url, linkType, {dimension1: 'DimensionValue'}]);
_paq.push(['trackGoal', idGoal, customRevenue, {dimension1: 'DimensionValue'}]);
_paq.push(['trackPageView', pageTitle, {dimension1: 'DimensionValue', dimension4: 'Test', dimension7: 'Value'}]);

Retrieving a Custom Dimension value

getCustomDimension(customDimensionId)

This function can be used to get the value of a Custom Dimension. It will only work if a Custom Dimension was set during the same page load.