Go Back

Differences between Custom Variables and Custom Dimensions

June 6, 2018

Custom Variables and Dimensions help you track your user’s behavior. You can expand standard Piwik PRO functionalities by storing additional metadata for visitor sessions and actions. Thanks to them you can store multiple values.

Let’s look deeper into the topic and analyze what they are and what the difference between them is.

Custom Variables Custom Dimensions
Length 200 characters 255 characters
Amount
  • 5 for visit scope
  • 5 for page view scope
  • possibility to expand
  • 5 for visit scope
  • 5 for action scope
  • possibility to expand
  • Type
  • Page view
  • Visit
  • Action
  • Visit
  • Configuration Tracking code + analytics settings Tracking code + analytics settings
    Tracking reports One shared report for all vars Separate tracking report for each dimension
    Visibility in reports
  • Analytics -> Visits ->Custom Variables
  • IN the Visitor Log. Visit variables are displayed in the visit summary, pageview variables on hover
  • Separate reports within Actions and Visits dependent on the dimension type
  • Visible in Visitor Log starting from PPMS version 5.40.1
  • Segmentation Segmentation by a variable index and value Segmentation by Custom Dimension name in the UI
    Remove Can be removed Can’t be removed, but can be deactivated

    Custom Variable

    As you can see in the table above, Custom Variable can be attributed to a visit or a page view action.

    Visit level variable applies every website load during a visit. It can be used to track demographical pieces of information (gender), time of a day (morning, evening), types of users (regular visitor vs customer, logged vs not logged user, content scroller vs content reader).

    Pageview level variable applies to the single page view, during which it is tracked. It can be used to e.g. analyze which sections (and subsections) of the article are the most popular, or what user was doing on the website just before a purchase of the product.

    By default, you can use up to 10 Custom Variable slots per a site (5 for pageview and 5 for visit scope). Extending this limit and creating a new custom variable slot can take a various time depending on the size of your database. It is only possible to do this via a command which needs to be executed on the command line.

    If you have the on-premises solution, you can create a new custom variable on your own.
    To create it, execute the following command within your Piwik PRO installation:

    ./console customvariables:set-max-custom-variables 6

    The clients using the Cloud solution should contact Piwik PRO support team in order to add new variable.

    Configuration of the variable in the tracker

    Visit Scope

    In order to track visit scope variable, you first need to configure the tracker properly.
    You should use setCustomVariable (index, name, value, scope) function and paste it before line containing the following code:

    _paq.push(['trackPageView']);

    Let’s define our custom variable as users who visit your page during the different times of a day (later you can use it to display them customized ads). The tracking code can be as follows:

    _paq.push(['setCustomVariable',
    // Index, the number from 1 to 5 where this custom variable name is stored: 1,
    // Name, the name of the variable: TimeOfDay,
    // Value, for example: "morning", "afternoon"
    // Scope of the custom variable, "visit" ]);
    _paq.push(['trackPageView']);

    For one custom variable name, you can set an unlimited number of values (report showing 500 rows is the only limitation here), so you can divide your users into many different categories.

    Keep in mind that a given custom variable name must be always stored in the same “index”. Otherwise, it can be replaced with the “newer” custom variable name.

    Once set visit scope variable is recorded for the whole visit.

    Pageview Scope

    Similarly to the visit scope variables, the page view scope variables have to be configured in the tracker. Use setCustomVariable (index, name, value, scope = “pageview”) function and paste if before line containing the following code:

    _paq.push(['trackPageView']);

    They can be useful when you want to see which categories of books you sell were the most popular or what your blog readers visit the most often.The tracking code can be as follows:

    _paq.push(['setCustomVariable',
    // Index, the number from 1 to 5 where this custom variable name is stored: 1,
    // Name, the name of the variable: book’s categories,
    // Value, for example: "adventure", "horror"
    // Scope of the custom variable, "pageview" ]);
    _paq.push(['trackPageView']);

    For one Custom Variable name, you can set an unlimited number of values (report showing 500 rows is the only limitation here), so you can divide your users into many different categories.

    Please keep in mind that a given custom variable name must be always stored in the same “index”. Otherwise, it can be replaced with the “newer” custom variable name.

    Adding the variable to the Piwik PRO Tag
    If you are the Piwik PRO Marketing Suite or a Piwik PRO Tag Manager user, instead of manually adding the custom variables codes you can simply pick them in your Tag Manager default tracking code. You have to scroll down and click on “+Track Piwik Custom Variables for this visitor”. While doing this, you need to specify ID, variable name, a variable value (the variable name from the 1st step) and scope (is it a visit or a pageview variable).

    Finally, the changes you’ve made have to be published, so you can start recording new data.

    Diagnostic and reports

    After the variables were configured and tracked, you can check if they have been properly configured in the Analytics settings → Diagnostic → Custom Variables

    Reports on the recorded variables can be found in the analytics → Visitors → Custom Variables. There is one shared report displayed for all the variables.

    Segmentation

    After the variables were properly configured, users can be segmented by variable’s names and values. To create a segment follow the steps: Add new segment → Action → Custom Variable → chosen Variable.

    Custom Dimension

    Custom Dimension feature is a newer and lighter version of Custom Variables. The name, ID and Scope have to be specified during the creation but during the call, you need to pass the value and ID. It simply allows sending additional parameter to Piwik PRO, either set for the particular visit or for the particular action.

    Custom Dimension’s reports are displayed separately for each dimension and they are more informative than the custom variable’s ones. They need less storage and reports can be generated faster.

    By default, you can use up to 10 Custom Dimensions (5 action and 5 visit) per site. Creating a new Custom Dimension can take a long time depending on the size of your database as it requires schema changes in it. Therefore it is only possible to do this via a console command which needs to be executed on the command line.

    Cloud clients should contact Piwik PRO support team with such a request.

    If you’re on-premises client you can do it on your own. In order to create a new Custom Dimension execute the following command within your Piwik installation:

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

    If you want to create multiple new Custom Dimensions at once, simply append the number of dimensions that shall be created. As all database changes will be executed in one statement, it may not take much longer to add multiple Custom Dimensions at once. For example to create 5 new Custom Dimensions in scope action execute the following
    command:

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

    Configuration step by step

    Before using Custom Dimensions you need to define them in your analytics settings.

    Action custom dimension

    In case of the action dimension, you can set it up both in the analytics settings or in the tracking code.

    As for the Analytics Settings, click on your username in the top right corner of the Piwik PRO and choose Analytics Settings, then choose the Custom Dimensions from the left side menu.

  • Navigate to analytics settings → Websites → Custom Dimensions
  • Configure a new dimension (Action)
  • type in Name and Activate your dimension
  • extract the value for the Custom Dimension from a page URL or page title automatically
  • hit the Create button.

  • If you choose the tracking code modification, follow the steps below:

    To track a value in the JavaScript Tracker call:

    _paq.push(['setCustomDimension', 4, 'dimensionValue']);

    To track a value in the PHP Tracker call:

    $tracker->setCustomTrackingParameter('dimension4', 'dimensionValue');

    To track a value via the HTTP Tracker API use the tracking parameter ‘dimension’ followed by the Custom Dimension Id:

    &dimension4=dimensionValue

    Visit custom dimension

    In case of configuration the visit scope custom dimension, tracking code modification is the only possibility.

    During setting up custom dimension, we use 1-10 indexes and then we divide them into action and visit scope dimensions in the analytics settings.

    Adding the Custom Dimension to the Piwik PRO Tag

    Instead of adding the code manually to the tracker, you can use Piwik PRO Tag Manager and add them in the Piwik PRO tracker wizard. You have to scroll down and click on “+Track Piwik Custom Dimension for this visitor”. While doing this, you need to specify ID and a Dimension value (name of your Custom Dimension).

    Finally, the changes you’ve made have to be published, so you can start tracking new data.

    Custom Dimensions reports are added under their name in the Analytics section under Visitors (for Visit scope) and Actions (for Action scope) reports.

    Segmentation

    After the Dimensions are properly configured, the users can be segmented by their names (Add new segment → Visit → Custom Dimension name).