What does Heatmap & Session Recording do?

Heatmap & Session Recording tracks interactions like clicks, mouse movements, scrolls, form interactions and page changes.
These interactions can be afterwards replayed in a video or visualized in a heatmap so you can find out what your visitors are really looking for, where they think something is clickable but it is not, and much more.

Heatmap & Session Recording gives you full control over your data and 100% data ownership.

Where can I get the Heatmap & Session Recording?

Heatmap & Session Recording is a plugin for Piwik and is available for purchase on the Piwik Marketplace as a yearly subscription. While the subscription is active, you will receive all updates for this plugin.

You can also get it as a hosted solution on our Piwik Analytics Cloud.

Where do I get more information about the Heatmap & Session Recording plugin?

It is recommended to visit the Heatmap & Session Recording website as well as the Heatmap & Session Recording plugin page on the Piwik Marketplace for a full list of all benefits and features. Developer documentation can be found on the Developer Zone.
There is also a Heatmap User Guide and a Session Recording User Guide.

Who develops & maintains the Heatmap & Session Recording plugin?

The plugin is developed and maintained by InnoCraft, the company from the makers of Piwik. At InnoCraft, talented and passionate product designers and engineers build and maintain the free and open source project Piwik. This ensures the highest quality and compatibility of all their plugins. As a result, popular Piwik features such as Segmentation work out of the box.

What about the quality of the Heatmap & Session Recording plugin?

This plugin is built and maintained by InnoCraft, the makers of Piwik. This ensures that the plugin is well integrated, kept up to date and automatically tested whenever a change in Piwik core is made. By purchasing this plugin, you also support the developers of Piwik to maintain the free and open source analytics platform itself.

Does Heatmap & Session Recording work as a standalone product?

No, the Heatmap & Session Recording plugin is built on top of Piwik Analytics. To use it, you first need to install Piwik. Piwik requires PHP, a MySQL database and a webserver like Apache or Nginx. Learn more about Piwik.

Alternatively, to take away the hassle of installing and maintaining your own Piwik, signup to our Piwik Cloud service.

Which Piwik version is required for this Heatmap & Session Recording plugin?

Piwik 3.0.4 or newer is required. You can also signup to our Piwik Cloud service.

Which browsers are supported and measured by Heatmap & Session Recording?

The plugin has been tested with several browsers, devices and operating systems.

  • Viewing the generated heatmaps and recorded session videos works in all browsers that Piwik supports as well (eg IE10+, Edge, Chrome, Firefox, Safari, …).
  • Tracking heatmap activities works on pretty much all browser versions, even older versions of Firefox, Chrome, and others. Only Internet Explorer requires at least version 10.
  • Recording sessions works on pretty much all browser versions as well, even older versions of Firefox, Chrome, and others. Only Internet Explorer requires at least version 11.
  • The tracker has been tested even on older browsers like IE6+ and won’t break your website. If a browser is not supported it will simply not record activities and not affect your website in any way.

What does Heatmap & Session Recording look like?

You can find screenshots of the UI in the plugin preview.

There is also a video showing you how a replay of a recorded session looks like:

Is it complicated to set up the tracking of Heatmaps and Session Recordings?

No, in fact everything works out of the box and you don’t even have to change your website or tracking code. Piwik will automatically discover when to record heatmap or session recording activities.

To learn all details about the tracking of heatmaps and session recordings, check out our Heatmap & Session Recording developer guide.

How do I get started tracking my heatmaps & session recordings?

  • To generate a heatmap, log in to your Piwik and click on “Heatmaps => Manage” either in the reporting menu or the administration menu.
  • To record sessions, log in to your Piwik and click on “Session Recordings => Manage” either in the reporting menu or the administration menu.

How do I mask entered keystrokes on individual form fields?

When you configure a session recording, you can choose to optionally record keystrokes, that is text entered by your visitors into text form fields.

If enabled, Piwik will capture these keystrokes and track them so they will be shown when you replay the recorded video. Piwik will automatically mask password form fields and common credit card form fields. If you want to mask additional form fields, simply add a data-piwik-mask attribute to an element. Learn more about masking keystrokes.

Note that Credit Card fields are automatically masked and not tracked (learn more)

How do I disable the recording of any keystrokes?

See the developer FAQ How do I prevent the capturing of keystrokes when recording a session?

Which Heatmap types are supported?

You can view click, mouse move and scroll heatmaps.

  • The Click Heatmap shows you where your visitors clicked on a web page. This lets you for example detect where your visitors think that something is clickable but it is not.
  • The Mouse movement Heatmap shows you where your users moved the mouse on your web page. This lets you for example detect what users are looking for and where they are going next.
  • The Scroll Heatmap type shows you how far down your visitors scroll on your web page. This lets you for example find out whether your page structure is good, and how often users scroll down.

The heatmap visualization also shows you the “Average above the fold” position letting you see how much of your web page is actually visible without scrolling when they view your web page.

Is the recorded heatmap & session recording data accurate?

Yes, we have put lots of effort to track accurate data by tracking the data in a very particular way. Instead of tracking fixed pixel positions like many competitors do, we track relative positions to elements within your web page. This ensures that session recording videos and generated heatmaps are accurate. As we record relative positions, the shown visualizations and videos are still accurate even if you view them in a different browser or operating system, if the font used is different, if the zoom level is different, and even if the screen resolution is different.

Can I change the resolution when viewing a heatmap?

Yes, you can choose between lots of different widths when you view a heatmap and the recorded data will automatically adjust. You can find the select field at the bottom of the heatmap visualization.

Which activities are replayed in session recording videos?

The following events are tracked and replayed in a video:

  • Clicks
  • Mouse movements
  • Current cursor position
  • Scrolls
  • Window resizes
  • Zoom on mobile devices
  • Form changes such as keystrokes on text fields and changes on radio, checkbox and select fields
  • Page changes. For example if a pop-up appears, or if a page changes in any other way you will see these changes in the video as well

The video timeline indicates when a certain event occurs so you can see at a glance what you can expect to happen when you replay the video, and it is easy to quickly jump to specific activities.

How do I replay a recorded session?

As soon as you have configured a session recording, Piwik will start tracking activities of your visitors so you can replay them in a video. To replay these activities, log in to your Piwik and select “Session Recordings” followed by the name of your configured session recording.

You will see a list of all recorded sessions including the information when it was recorded, how much time they spent on the page, the resolution of the visitors’ viewport, the location, device, operating system and browser. To replay such a video, hover on a session recording row and select the big red play button.

How do I view more information about the visitor of a recorded session?

For each recorded session we show you a bunch of information like the location and device that was being used when the session was recorded. To get even more information about a visitor, hover a row and click on the Visitor Profile icon.

When you replay a video, you can also select the visitor profile icon in the middle/top right area.

Which shortcuts can I use when replaying a session recording video?

  • space or k to pause or play the video
  • left arrow key to jump backwards 5 seconds
  • right arrow key to jump forwards 5 seconds
  • j to jump forwards 10 seconds
  • l to jump forwards 10 seconds
  • 0, space or k to replay the video if it finished
  • n play next page view of this visitor within this session
  • p play previous page view of this visitor within this session
  • a enable / disable auto play of next page view within a visit
  • b enable / disable skip pauses
  • s change replay speed

How do I record only sessions when a visitor spend at least a specific time on my page?

When you configure a session recording, you can define a minimum time a visitor needs to spend on an individual page before the session is actually recorded. This way you don’t end up with too many recordings that might be only a few seconds long.

How do I avoid having recording sessions that contain no activity?

When you configure a session recording, you can choose whether a session should be recorded only if there has been at least a click and a scroll. This is enabled by default so you don’t end up having recordings with no actions.

If you also want to replay recordings with only a click, only a scroll, or no activities, you can disable this setting in Piwik > Session Recordings > Manage.

How do I delete a recorded session?

To delete a recorded session go to the Session Recording report and hover the session you want to delete. Now a “trash” or “bin” icon will appear next to the “play” icon. As soon as you click on it, the recorded session will be deleted.

Is it possible to apply segments and view recorded sessions and heatmaps for a custom segment of my users?

Yes, Heatmap and Session Recording lets you slice and dice your analytics reports exactly how you need to extract valuable insights into your visitors. You can apply over 100 Piwik segments. For example, view sessions for returning visitors or view sessions for visitors who converted a specific goal.

How do I disable the tracking of all heatmaps and session recordings for a specific site?

You can prevent the tracking of any activities by calling _paq.push(['HeatmapSessionRecording::disable']); in your website’s analytics tracking code. This is especially useful when you want to record activities only for some of your websites, but not for all of them.

Does Heatmap & Session Recording work with a single-page websites and web applications?

Yes, they are fully supported out of the box. Read more about this in the Heatmap & Session Recording API Reference, or learn more about tracking single-page application in our FAQ.

Can I track activities only on a portion of my visitors?

Yes, when you configure a heatmap or a session recording, you can define a so called “sample rate”. You can choose a rate between 0.1% and 100%. If you choose for example 10%, only every 10th page view will be recorded.

How do I track only a specific target group?

You can specify a custom trigger method to track for example only logged in users, only users with a certain age, from certain locations, or only track activities during the day using the HeatmapSessionRecording::setTrigger tracking method. Learn more about this feature in the Developer FAQ.

Does Heatmap & Session Recording work with mobile and tablet devices?

Yes, Piwik will automatically detect the device type of your visitors. In case the device type could not be detected automatically, you can define pixel thresholds to indicate when we should assume a device is a mobile or tablet device. To not having to configure these tablet and mobile thresholds every time you configure a heatmap, you can change them globally under “Administration => General Settings”.

You can view the heatmap data for desktop, tablet, and mobile users separately and of course you can apply any Piwik segments to heatmaps and session recordings.

Can I generate several heatmaps and several session recordings at the same time?

Yes, you can. There are no limits to how many pages you target at a time.

How can I target specific pages when configuring a heatmap or session recording?

The plugin lets you define page rules based on “URL”, “URL path”, and “URL parameter”.

To match a specific value, you can select different comparisons like “equals simple”, “equals exactly”, “starts with”, “contains”, “matches a regular expression”, “not equals simple”, and many more.

When you choose “equals simple”, the protocol (http or https), any URL parameter and trailing slashes in a path are ignored letting you more easily match different versions of a page URL. On the contrary, when selecting “equals exactly”, the value has to match exactly.

How do I ensure my configured target pages actually match the URL I want to match?

To make sure your defined target page rules match the page URL you want to match, use the URL validator which is displayed next to your target page rules. By entering the URL into the URL validator, you will see visually whether the entered URL would be matched by your page rules or not.

How do I hide (exclude) certain elements of my web page when viewing a heatmap?

When you configure a heatmap, you can define one or multiple CSS selectors to hide elements within your web page. This is useful if your website shows for example a pop-up when a user lands on your website. If you don’t want to configure the same CSS selectors each time you create a heatmap, you can define custom stylesheets in your CSS.

To find the CSS selector for a certain element on a web page, right click on the part you want to hide on your web page and then select “Inspect element”. This should work in most modern browsers. Now right click on an element you want to hide and select “Copy > Copy selector”.

How do I specify a screenshot URL for a heatmap?

When you configure a heatmap and define on which pages the activities for this heatmap should be recorded, different URLs may match your defined page rules. For example when you configure a page rule like “record all activities when page URL starts with https://piwik.org/blog”, URLs like “https://piwik.org/blog/2016” and “https://piwik.org/blog/2017” may match.

If you want to capture the screenshot only on a specific URL, for example only on “https://piwik.org/blog/2017”, you can configure this URL when configuring your heatmap as a “screenshot URL”.

How do I download a generated heatmap?

We are working on the possibility to directly download the generated heatmap as an image. As a workaround, you may use the “Print to PDF” feature in your browser to keep a copy of a heatmap. There are also various browser extensions that lets you capture screenshots and download it as an image.

How do I stop recording further heatmap or session recording activities?

If you want to stop the recording of any activities before the configured limit is reached, go to “Heatmaps => Manage” or “Session Recordings => Manage” and click on the “stop” icon in the “Actions” column.

Is there a maximum page height for heatmaps?

No, while many other solutions have problems showing heatmaps for pages that are larger than 8.000px or 32.000px, Piwik will render it nicely for any page length.

Will the generated heatmaps and recorded sessions still work even if I remove the page on my website?

Yes, the heatmap and recorded sessions will still work when you remove the page from your website.

How do I correct a heatmap when a page header is shown over the full heatmap?

If you use “Parallax Scrolling”, or when a part of your page is set to 100% of the browser height, the heatmap might not be shown correctly. Typically, the header would be shown stretched over the whole heatmap and other parts of the web page would not be visible. To solve this problem, set a max height to this element using CSS or JavaScript. For example:

.welcome { max-height: 1000px; }

If you want to set this style only for Heatmaps, you can prefix your selector with “html.piwikHeatmap”:

html.piwikHeatmap .welcome { max-height: 1000px; }

The chosen 1000px is only an example, you can set it to any height. Learn more about custom stylesheets.

How do I apply custom stylesheets when a heatmap is generated or a session recording replayed?

To apply custom CSS stylesheets to your Heatmaps and Session Recordings, prefix your CSS with “html.piwikHsr”.

To apply custom stylesheets only for Heatmaps, prefix your CSS with “html.piwikHeatmap”.

To apply custom stylesheets to Session Recordings, prefix your CSS with “html.piwikSessionRecording”.

Custom stylesheets can be useful to prevent any possibly sensitive data from being shown in a heatmap or a session recording. It can be also useful when your website shows a pop-up when a user lands on your website. Under circumstances such a pop-up could be visible in a heatmap. You can also exclude or hide elements when you configure a heatmap, but by defining it in your stylesheets you don’t have to configure it each time you create a new heatmap.

Will the generated heatmap still work if I change a web page while heatmap data is collected?

Yes, editing your web page should not affect the results and the heatmap data will be still correct and show you where your users really engage.

What can I do if the heatmap or session recording is not styled and CSS seems missing?

When Piwik records activities for heatmaps and session recordings, the HTML of your website is being recorded and shown when you view a heatmap or a recorded session. However, the CSS and images that your web page embeds will still be loaded from your website.

  • If you have removed CSS or image files from your website that are embedded within the recorded HTML, then the styles might not be shown anymore in the Heatmap or Session recording. However, any generated heatmap data or recorded session will be still correctly displayed, because we track activities in a special way with maximum accuracy.

  • If you have not removed CSS files but your heatmap or session recording is still not styled, your website might not support HTTPS. In this case, try to access your Piwik via “http://” instead of “https://”. We recommend that you keep using Piwik via “https://” and create a HTTPS certificate for your website in order to make sure the stylesheets are applied.

  • If the heatmap or session recording is still not styled, please contact us and we will investigate.

Can I record my than 5000 sessions at once?

Yes. By default, the UI allows you to record only up to 5000 sessions for a single recording (you can create unlimited recordings). In case you wanted to record more than 5000 sessions, you can change your config/config.ini.php file by changing the session_recording_sample_limits value. If you cannot find this setting in your config file, please add the following two lines and adjust the values to your liking:

[HeatmapSessionRecording]
session_recording_sample_limits = "50,100,250,500,1000,2000,5000"

Setting a higher limit is usually not needed as it takes about 28 hours to watch 5000 sessions with an average length of 20 seconds. However, this can be useful if you want to record many, if not all sessions on your website and then apply segments afterwards to drill down the sessions you are interested in.

Why does the Heatmap screenshot not show the fully rendered page (pictures or content missing)?

The screenshot for a Heatmap is taken when the page is officially loaded according to the browser. In some cases, the browser may consider the page fully loaded and rendered before all components are actually loaded. For example, when you lazy load certain images or other resources for a faster page load time. This means the load event triggered by the browser is not reliable and you need to manually tell Piwik when the site is considered loaded to see a fully rendered screenshot in the Heatmap. To do this, follow these steps:

1) Disable Heatmap & Session Recording in your tracking code (as early as possible eg when calling “setSiteId” etc):

_paq.push(['HeatmapSessionRecording::disable']);

2) Enable Heatmap & Session Recording as soon as the page is considered fully rendered within your code:

_paq.push(['HeatmapSessionRecording::enable']); 

Please note that when you manually disable the Heatmap & Session Recording, then Piwik will only start recording the session when you have re-enabled it (once the page was fully loaded). As a result, any interaction that occurred before the page was fully loaded will not be recorded. In general, we recommend to try and make your pages load faster so that your visitors have a better user experience and you do not experience this issue as much.

Can anonymous users view session recordings?

Piwik allows you to make reports public and viewable by anyone. If you do make the data for a specific website or mobile app public, your reports are accessible without having to log in. As Session Recordings may contain sensitive data, it won’t be possible to replay session recordings and neither see which sessions were recorded for privacy reasons: for example the recorded sessions may contain keystrokes typed by users and more.

Does Heatmap & Session Recording set any cookies?

When you record sessions, a first party cookie will be set for the duration of the visit named _pk_hsr. This cookie is needed to ensure that all page views within a users’ session will be recorded. The cookie will be only set as soon as a user has reached a configured entry page. If you disable cookies via the tracking code, the plugin will respect this setting and not set a cookie. As a result, not all page views within a session may be recorded if you set a sample rate of lower than 100% or configure an entry page. A possibly configured cookie domain or cookie path will be respected. Learn more about Piwik JavaScript Tracker cookies.

Can I fetch Heatmap and Session Recording reports via the Piwik HTTP Reporting API?

Yes, all recorded activities can be fetched in different formats such as JSON, XML, CSV, HTML and more, so you can integrate this data anywhere and perform custom analysis on it. You can also configure the recording of new heatmaps or session recordings via the API, stop the recording, delete recordings, and more. Read more about the Piwik HTTP Reporting API and view the Heatmap & Session Recording Reporting API Reference.

Piwik is not recording any Heatmaps or Sessions, what can I do?

First, we recommend to open your Heatmap or Session Recording configuration in the Piwik UI to make sure you have configured a correct target page or entry page. There is a URL validator just next to the page configuration that lets you check if a heatmap or session would be recorded on a certain page URL. This way you can find typos and other configurations problems.

If your configuration is correct, likely the request to $yourPiwikDomain/plugins/HeatmapSessionRecording/configs.php fails because of restrictions in your web server configuration.

Please log in to your Piwik as a Super User and go to Administration => System Check. There is a system check for Heatmap & Session Recording that checks whether the file is accessible from the internet / intranet or not. If not, you will see an error message explaining the problem.

If the system check says everything is ok but it still doesn’t work, you can also check manually if the file “configs.php” file is accessible. Open your website, right click and select “Inspect”. Now go to the network tab and reload your website. You should see an entry for “configs.php” with a status of “200 OK”. If there is a status like “403”, then you need to modify your web server to allow access to this file.

If you are using Cloudflare or something similar, you may need to invalidate your cache for the Heatmap tracking code to appear in your “piwik.js” tracking file. You might also want to edit your “config/config.ini.php” file and add or modify the following two lines:

[HeatmapSessionRecording]
add_tracking_code_only_when_needed = 0

Still not working? Please get in touch with us, we are happy to help.

Do I get access to the raw data that was tracked, such as clicks and mouse moves?

Yes, you get access to all data that is stored in your MySQL database: the data is stored in the piwik_log_hsr* tables.

Under what license is the Heatmap & Session Recording tracker released?

Heatmap & Session Recording and Heatmap & Session Recording tracker are released under the InnoCraft EULA.

Is there any data limit to how heatmaps can be generated or how many sessions can be recorded?

No, there is no data limit with the Heatmap & Session Recording product. You can generate as many heatmaps and record as many sessions as you wish. Learn more about No data limit.

How do I exclude employees or partners views and interactions from the heatmap & session recording reports?

See our FAQ: Excluding traffic from Piwik using IP Addresses, Cookies, and more.

Any questions?

Many answers and more information about Piwik You can find here:

We are social

Follow us: