Clickstreams or clickpaths represent the sequences of actions performed (clicks, etc.) and webpages visited by a website user.
You can also create advanced click, move, and scroll Heatmaps as well as record sessions using the Heatmap & Session Recording premium feature. Session Recordings let you replay exactly what your visitors did on your website in a video so you can improve for example the usability.
By default, Matomo (Piwik) reports are in real time (learn more in the user documentation) when you are viewing reports for “today” or any date range that includes today. Matomo will look at all your logs for today in the database and process the reports every time that you request them.
By default, reports for today are processed every 10 seconds. The Matomo Super User can change this value in the “General Settings” admin panel. For high traffic websites, we recommend processing the reports once every hour (3600 seconds), which is a “near real time” approach.
Please read the Setup auto archiving page for more information.
Matomo also provides a real time view of your visits on your site… right now! You can see all new page views, actions and new visits coming to your site, refreshing automatically. This feature is enabled by the Live! plugin which is enabled by default in the Matomo dashboard (check out the demo).
The number of unduplicated visitors coming to your website. Every user is only counted once, even if he visits the website multiple times a day.
Unique visitors are determined using first party cookies stored in your visitor browser. When a same person visits your website on two different devices (for example their laptop and on their mobile phone) then Matomo (Piwik) will detect two unique visitors.
If the visitor’s browser does not accept the Matomo cookie (if they have disabled, blocked or deleted cookies), a simple rule of thumb is used to try to match the visitor to a previous visitor with the same features (IP, resolution, browser, plugins, OS, etc). Read about all details in this other FAQ.
Note that by default, unique visitors are available for days, weeks and months periods, but unique visits are not processed for the “year” period nor for a “date range” period (for performance reasons). Learn how to enable unique visitors for all date ranges.
See also our glossary of analytics terms.
If a visitor comes to your website for the first time, or if he visits a page (or downloads a file) more than 30 minutes after his last page view, this will be recorded as a new visit. A Unique Visitor can make multiple Visits per day.
In the first visit, the visitor is a New Visitor. From the second visit (the same day or later), a Unique Visitor is a Returning Visitor.
You can change the 30 minutes value (session timeout) by overriding
[Tracker] visit_standard_length = 1800
in your config/config.ini.php file.
See also our glossary of analytics terms.
Entry page is the first page of a visit.
For each Entry Page URL, Matomo (Piwik) reports the number of Entrances (Visits that started on this page), Bounces (Visits that started on this page but left the website straight away) and Bounce rate.
See also our glossary of analytics terms.
The Exit Page is the last page accessed during a visit.
Matomo (Piwik) reports the top Exit Pages URLs, the number of Exits, Unique Pageviews and Exit Rate. Exit rate (sometimes called “Page Exit Ratio”) is the number of Exits from a page divided by total number of Page views of that page.
See also our glossary of analytics terms.
Super Users are the only users that can perform all administrative tasks such as adding new websites to monitor, adding users, changing user permissions, activating and deactivating plugins and even installing new plugins from the Marketplace.
By default in Matomo (Piwik) there is one super user which was created during the installation process. As of Matomo 2.1, you may give Super User permission to other users.
The Super User has superpower!
Super users can create new users and assign them the ‘admin’ permission on a given set of websites. Users with the ‘admin’ permission can edit the website settings (Name, URLs, Timezone, etc.). They can also create, manage and delete entities for the website(s) such as Goals, Funnels, Forms, A/B Tests, Heatmaps, Session Recordings, Delete visits using the GDPR privacy tools, Invalidate reports, etc.
Users with ‘admin’ permission can also create new users and grant the new users the ‘view’ or ‘write’ or ‘admin’ permission on the website(s) the user has ‘admin’ permission.
Users with ‘admin’ permission cannot add other websites and they cannot manage plugins or other global settings.
Super Users and users with ‘admin’ permission can create users and assign them the ‘write’ permission on a given set of websites.
Users with the ‘write’ permission can view all reports in Matomo for the website(s) the user is set to ‘write’, and they can also create, update and delete website entities such as Goals, Funnels, Forms, A/B Tests, Heatmaps, Session Recordings, etc.
A user with ‘write’ permission is similar to a user with ‘admin’ permission but a ‘write’ user cannot edit or delete the website, and they cannot add new users and give them permission to view the website(s).
Also the user cannot add other users, websites, and they cannot manage plugins (only Super Users can).
Super Users and ‘Admin’ users can create users and assign them the ‘view’ permission on a given set of websites.
Users with the ‘view’ permission can view all reports in Matomo (Piwik) for the website(s) the user is set to ‘view’.
The user cannot add other users, websites, and they cannot manage plugins. They also cannot create, update or delete any website entities such as Goals, Funnels, Forms, A/B Tests, Heatmaps, Session Recordings. However they can view all these reports.
token_auth acts as your password and is used to authenticate in API requests. You can find the
token_auth by logging in Matomo (Piwik), then click on Administration in the top menu, then click the link “API” in the left menu.
token_auth is secret and should be handled very carefully: do not share it with anyone. Each Matomo user has a different
token_auth value can be re-generated on request by any user under Administration > Personal Settings.
Matomo (Piwik) lets you measure several websites within one Matomo server. Each website added into Matomo has its very own
ID Site (or
Website ID). To find out the
idSite value for a given website, log into your Matomo, then click on “Administration” icon in the top right of the screen, and go to the
Websites page. In this page you will find the list of all websites. The website ID is on the left of this table listing all websites (below the website name).
You can track as many websites as you like that are hosted on the same server as Matomo (Piwik), or hosted on several external servers. Only the server that hosts Matomo needs to run PHP and MySQL.
- You have a website built in Java hosted on server1
- You have a website built in Python hosted on server2
- You can install Matomo on server3, and track visits from the two other websites
Note about https: Matomo automatically detect if the page being tracked is https (SSL) and would include the piwik.js in secure mode from your Matomo server.
How long does the Matomo archiving process take for high traffic websites – or hundreds of websites?
Every night, if you setup auto-archiving, Matomo (Piwik) will run through the logs and compile all your reports for each day, week, month and year. How long the process will take depends on your traffic, number of visits and pages, on the number of websites you have setup in Matomo… and of course on your server performance.
For example, using version 1.3 on a single core duo2 server with 3GB of ram, Matomo archiving process takes about 2 hours for 400,000 pages per day (and more than 6,000 websites). We are constantly improving Matomo performance: making Matomo faster is a top priority. Stay tuned… or come and help us if you know how to design software to make it faster.
Also, if you have a medium or high traffic website, we would be interested to hear your experience with Matomo archiving. How long does archiving take for your traffic, how many visitors/pages, how many websites, what type of server; Please post your numbers in the High traffic Matomo servers forum post, and let us know by email.
For practical information about managing Matomo for high traffic websites, see this FAQ: Matomo web analytics for high traffic websites check list.
To find out the total number of registered users on your Matomo (Piwik), first log in to your Matomo as a Super User.
In Matomo 3
When you are logged in, click on the “Administration” icon in the top right corner to load the admin area.
The number of users is shown in the widget “System Summary” in the top left of the administration home page.
In Matomo 2
When you are logged in, click on the “Administration” icon in the top right corner to load the admin area.
Click on “Users” in the left menu of the administration area, then scroll down to the “Users Management” section. It will show you the total number of users registered on your Matomo in the first paragraph of that section.
An ‘Action’ in Matomo (Piwik) is counted whenever a visitor visits a Page, clicks on a Download or on an external link, whenever an event is tracked, or when a visitor searches on your website search engine.
To find the number of actions tracked per month, go to Matomo, and open the “All Websites” dashboard. In the calendar, select “Month”, then click on the previous month, and click “Apply”. The number of actions per month is displayed at the top next to the “All Websites dashboard” title.
Why are there sometimes 0 visits, but some conversions recorded, for example for a Keyword, a Website or a Custom Variable?
Imagine the following use case:
1) User comes to your website via the campaign “Emailing November”, via a click on a link in an email tagged with Matomo (Piwik) (or Google Analytics) campaign parameters
2) He browses around and exits after 3 pages
3) He comes back the next day (on 2011-01-01), via a direct entry, and buys a product on your site (which you track as a Goal Conversion)
In this case, if you select the date 2011-01-01 in Matomo, it will show that the Campaign “Emailing November” did not have any visit on this day (because the user entered the website directly), but the conversion is attributed to the Last known referrer that the visitor used (which is stored in the first party cookie). On 2010-12-31, there will be one visit from the campaign “Emailing November” but no conversion on this day.
Matomo attributes conversions to the last seen referrer by default. How do I credit conversions to the first referrer instead?
When visitors convert a Goal, Matomo (Piwik) tries to attribute the conversion to the referrer that brought the visit to the site. Matomo will credit each Goal conversion to the last non empty referrer used by the visitor (ie. the last time the visitor came to the website with a referrer that was not a direct entry). In some cases several referrers can lead a same visitor to your website (eg. Search engines, Newsletter link).
Matomo default attribution model lets you choose whether to credit the conversion to the first referrer used or the last referrer used. If you need better visibility of all your channels touched during the customer journey, you can use the premium feature for multi channels attribution reporting.
Attribute conversions to the first referrer instead
Multi Channel Attribution
Want to know the true value of all your marketing channels including all individual referrers?
Matomo lets you apply attribution models using the Multi Channel Conversion Attribution premium feature. Looking at only the first or the last referrer usually doesn’t let you know which channel is actually the most successful. Why? When a user visits your website several times, you only look at either the first or the last channel. However, you don’t give any credit to all other referrers the same user has used to visit your website. With the multi attribution feature, you can for example choose to give each referrer the same weight or to give all credit to the last non-direct referrer.
To add a new search engine in your Matomo (Piwik) server, you can use the ReferrerManager plugin which lets you manage Search Engines and Social networks.
The lists of Search engines and Social networks detected by Matomo are maintained in our searchengine-and-social-list project on github.
Since Matomo 2.16.0 definitions are automatically updated in Matomo installations using a scheduled task. This guarantees your Matomo uses the latest definitions.
You can read more about how to add/edit a search engine or social network definition in the README file of the repository.
(Matomo uses an icon for each search engine and social network, placed in the directory plugins/Referrers/images/)
Matomo (Piwik) provides two reports for your page views: Page Titles and Page URLs. A page title is the content of the HTML <title> tag. If your pages do not define this <title> Matomo will instead report “page title not defined” for the visits on those pages.
Matomo (Piwik) provides two reports for your page views: Page Titles and Page URLs. In some rare cases, a visitor’s browser will not let the Matomo Tag request the current URL (generally for privacy reasons). If Matomo could not request the page URL from the browser, Matomo will instead report “page url not defined” for the visits on those pages.
If all your pages report “Page url not defined” then there is a data tracking problem. Here are common reasons for this issue:
- 2) if you manually track file downloads using
_paq.push(['trackLink', 'https://mydomain.com/download.pdf', 'download'])for example, note that you must use a full valid URL.
- 3) if you are using Self-hosted Matomo (this issue does not occur on the Matomo Cloud): check that there is no automatic HTTP redirection on the piwik.js and piwik.php requests (for example via an .htaccess). 301 Redirection from
- 4) If your pages are correctly tracked but you still don’t see any URL being tracked, please investigate/debug the issue with Firebug or ask in the forums posting your site URL so we can help you.
Matomo (Piwik) uses a special php function (gethostbyaddr) to request the hostname associated to a given IP. For example, the function would return “br76.comcast.net” and Matomo would categorize the visitor as using the provider “Comcast”. Sometimes however, for specific IPs or when the function times out, Matomo doesn’t know which provider the visitor is using and will simply report “Unknown”.
Some search engines may not specify the keyword used to reach your website (for example Google, DuckDuckGo, Firefox latest version now also removes keywords, etc.). Matomo will by default report the search keyword as “Keyword not defined”. It means that Matomo has detected that the visitor came from a search engine, but the keyword was not provided in the Referrer URL. But in 2017 we have developed a new solution which makes it possible to see all your keywords that users used to find you:
Learn more about how to import your Google, Bing and Yahoo Search keywords into your Matomo Analytics (formerly Piwik Analytics) reports in our Search Keywords Performance user guide.
Of course you can! We love having people help us make sure Matomo (Piwik) is available to as many people as possible in a language they understand. Please see Matomo Translations for more information.
Yes, Matomo (Piwik) works well with any IPv6 addresses. Here is further information:
Tracking API will track users with an IPv6 address.
Visitor Log and other detailed user reports will display IPv6 addresses.
IP Anonymisation privacy feature will anonymise IPv6 addresses.
Geolocating IPv6 does not work very well: most IPv6 will not be accurately geo located. A few Ipv6 addresses may be geo-located when using the PHP or Apache geo location driver. IPv6 geo location does not work with the Maxmind PECL driver (issue). Geo locating Ipv6 addresses may improve in the future as Maxmind (our Geo database provider) improves the accuracy of their IPv6 databases.
Logs containing IPv6 addresses can be imported in Matomo without any issue and they will be correctly parsed, anonymised (when applicable), stored and processed.
Here is an example of an Ipv6 address:
To track your https pages correctly, your server hosting Matomo (Piwik) should work when called from https. You will need to buy a SSL certificate for your Matomo server.
Many Matomo users successfully use Matomo to report analytics of Ecommerce and SSL secure shops.
The Matomo tag detects the protocol of the page being tracked, and then automatically calls the normal http or secure https Matomo server.
To check whether your Matomo server works over HTTPS, go to:
https://url/to/piwik/piwik.php?rec=1&idsite=1 – if it returns a blank page it is working. If
https://url/to/piwik/piwik.php?rec=1&idsite=1 returns an error, please contact your sysadmin to ask her to enable SSL on the Matomo server.
On a related note, you can also force the Matomo login form to use secure SSL connections.
To ensure that your visitors and all their actions on SSL HTTPS pages will be correctly tracked in your Matomo, you need to check that your SSL Matomo Server is correctly configured.
Does Matomo support Google Analytics campaign parameters (utm_campaign, utm_medium, utm_source, utm_term)?
Matomo (Piwik) detects URLs tagged with Google Analytics campaign parameters. By default, Matomo offers two dimensions for Campaign tracking: name, and keyword. The parameters
utm_source are used as the Campaign name. The parameter
utm_term is used as the Campaign keyword. You can learn more about Tracking Campaigns in Matomo or head over to the URL Builder.
If you need to track more than two campaign dimensions in Matomo, for example if you want to enjoy the same campaign reporting as in Google Analytics, you can install the MarketingCampaignsReporting plugin available here on the Marketplace. The Marketing Campaigns Reporting plugin lets you track up to fix Campaigns parameters (name, source, medium, keyword, content and campaign ID) and automatically detects the utm parameters:
* you may choose to customise campaign parameters detected by Matomo.
* you can use campaign parameters in the query string
landing?utm_campaign=PaidSearch, and Matomo also detects campaign and keyword in the hash tag string
SKU stands for Stock-keeping unit. A Product SKU is a string representing the Product unique identifier in your Ecommerce shop: for example SKU for books might be the ISBN identifier for this book such as
8120725247. A given Product might change its name overtime, but the product’s SKU should always be the same. With Ecommerce Analytics, you can track Product SKUs, Product Names and Product categories and get interesting reports about their performance in our online shop.
- Each dimension has its own menu item under either “Visitors” or “Actions” making them first class citizen reports
- A single Custom Dimension report can be widgetized whereas it is only possible to widgetize all Custom Variables reports combined
- More metrics are available for Custom Dimensions in scope “Action” (Unique actions, Exit rate, Bounce rate, Average time on dimension, Average generation time) and the row actions Segmented Visitor Log, Overlay and Transitions can be used
- Custom Dimensions are easier to segment as the segment name will be the name of your Custom Dimension in the UI
- Custom Dimensions are more efficient as they need less storage and reports can be generated faster
- Custom Dimensions are easier to track as only the Custom Dimension ID and Value need to be set in the tracker whereas for Custom variables the Name, Scope, Index and Value need to be set during tracking.
- Custom Dimension values in scope Action can be tracked automatically by extracting the value from the tracked URL or Page Title
- The name of a Custom Dimension can be changed at any time
- Values of Custom Dimensions are limited to 255 characters whereas Custom Variables are limited to 200
However, there is also a limitation. Unlike Custom Variables you cannot use the same slot/index for many different names or use cases. While for both Custom Variables and Custom Dimensions 5 slots in scope Action and 5 slots in scope Visit are available, you cannot use a specific slot of a Custom Dimension for something else. Once you have created a new Custom Dimension you can only deactivate it. Deleting a dimension and creating a new one is not possible. However, if you ever run out of available Custom Dimension slots you can make more available at any time. This just might take a while as it requires schema changes in the database.
In general we recommend users to use Custom Dimensions as we will deprecate Custom Variables at some point. With Matomo (Piwik) 3.0 Custom Dimensions will be most likely installed by default.
When I enable “Purge old logs” in the Privacy settings, how do I make sure that no historical data is lost?
If you enable ‘Purge old visitors logs‘ in the Administration > Privacy menu, Matomo (Piwik) will regularly delete your Visitor Logs from the Database. The Logs are used by Matomo to process Reports such as “Top Keywords”, “Top pages”, etc. If some old logs are deleted from your database, but reports have not been yet processed, the data will be lost forever.
We highly recommend that before deleting old visitor logs from your database,
1) you setup the automatic archive processing,
2) and run the
console core:archive console command until completion at least one time, making sure there are no errors during the execution.
This will ensure that all daily reports for each website have been pre-processed and the logs are no longer needed for these days.
Matomo (Piwik) custom variables tracking provides a powerful & easy way to track custom values and variables about your visits (for example “Username”, “Membership level”) or page views (eg. “Category:Sport”). You can track up to 5 variables for each Visit on your website. On top of these 5 custom variables for each visit you can also track up to 5 custom variables for each page view.
Learn more about Custom Variables Analytics.
We are always looking for more quality developers to join the Matomo (Piwik) fun! If you want to be listed on the Matomo Consulting page, you need to know about Matomo internals: please have a look at the developer documentation, the code and the coding standards that we use to review submitted code.
To be an official Matomo Consultant, you need to either:
- submit patches to some of the current issues, bugs, or features
- or submit a new plugin
We will then review your work and consider adding you in the official Matomo Consulting listing.
For inspiration, please have a look at the Matomo roadmap ; the list contains lots of interesting problems to solve, in different fields: performance and scaling, User Interface, Web analytics reports, core mechanisms, Plugins related tasks, etc.
If you need more information or if you want to become a Matomo consultant, please contact us at : we are looking forward to helping you!
To respect the privacy of your visitors, it is recommended to include the Matomo (Piwik) Opt-out iframe in your website. This iframe will display to your users a short text and let them opt-out in one click.
To find the code for the iframe, login to Matomo, then click Administration and then click Privacy > Users opt-out.
Here is what the opt-out iframe looks like:
You can easily customise the opt-out iframe’s font color, font family, font size, as well as the background color.
Learn more in the Privacy user guide.
To track visitors, Matomo (Piwik) by default uses 1st party cookies, set on the domain of your website. Cookies created by Matomo start with:
_pk_ses. When you use the Heatmap & Session Recording plugin, a cookie
_pk_hsr will be created.
When you exclude yourself from being tracked using the cookie method or using the iframe opt-out method, Matomo will create a cookie
piwik_ignore set on the domain of your Matomo server. Your server might be a third party cookie if Matomo is setup on a different URL from the website being tracked. (Please note that the
matomo_ignore cookie does not contain personal information or any ID and the cookie value is the same for all visitors.)
Matomo by default does not use third party cookies but you can enable a third party
_pk_uid cookie it if you wish.
Learn more about What data does Matomo track?.
Default expiration times
The cookies described above will eventually expire and be removed from your users’ browsers. The default expiration times are listed below:
_pk_id– 13 months
_pk_ref– 6 months
_pk_hsr– 30 minutes
In some countries, the law requests websites to provide a way for users to opt-out of all tracking, in particular tracking cookies.
[...] // Call disableCookies before calling trackPageView _paq.push(['disableCookies']); _paq.push(['trackPageView']); [...]
disableCookies(), or if you are importing server logs in Matomo which do not contain cookie information.
When cookies are disabled, some data in Matomo will be less accurate. Specifically…
- Ecommerce and Goal tracking attribution: By default, Matomo stores the website or keyword or campaign used to find the website in a cookie, so that we can credit this website when the visitor makes a conversion (Goal conversion or Ecommerce order). If the conversion happens in the same visit, Matomo will always credit the referrer (even if cookies are disabled). However imagine the following use case: the visitor uses a newsletter link tagged with a campaign, visits 5 pages on your website but does not buy. He then comes back 2 hours later directly typing your website URL (therefore a Direct Entry visit), then buys during this second visit. When cookies are enabled, Matomo credits the conversion to the initial Campaign. When cookies are disabled, the conversion is not attributed to the original newsletter link as this data is not available.
- Reports such as “Days since last visit”, “Visits by visit count”, “Visits to Conversion”, “Days to Conversion” will count all visits without cookie similarly to new visitors.
What are Secure Cookies? Secure cookies is a type of cookie which is transmitted over encrypted HTTP connection. When setting the cookie, the Secure attribute instructs the browser that the cookie should only be returned to the application over encrypted connections.
Then all tracking cookies are created with the Secure cookie attribute.
Note: this security feature should be used only if the website is available under HTTPS only.
- User IP address (see also: IP anonymisation)
- Optional User ID
- Date and time of the request
- Title of the page being viewed (Page Title)
- URL of the page being viewed (Page URL)
- URL of the page that was viewed prior to the current page (Referrer URL)
- Screen resolution being used
- Time in local user’s timezone
- Files that were clicked and downloaded (Download)
- Links to an outside domain that were clicked (Outlink)
- Pages generation time (the time it takes for webpages to be generated by the webserver and then downloaded by the user: Page speed)
- Location of the user: country, region, city, approximate latitude and longitude (Geolocation)
- Main Language of the browser being used (
- User Agent of the browser being used (
From the User-Agent, we use our Universal Device Detection library to detect the browser, operating system, device used (desktop, tablet, mobile, tv, cars, console, etc.), brand and model.
Some information is also stored in first party cookies and then collected by Matomo:
- Random unique Visitor ID
- Time of the first visit for this user
- Time of the previous visit for this user
- Number of visits for this user
(Note: it is possible to disable tracking cookies)
Data that may be tracked (optional)
You may also configure Matomo to track optional information about your users or how they are using your website and apps:
- Custom Dimensions
- Custom Variables
- Site Search
- Viewing and clicking on Contents
- Mouse movements, clicks, and scrolls
- Form interactions
- Video and audio interactions
Data tracked which may be personal data
Some data tracked by Matomo can be personal, private, sensitive and/or confidential. The following information may contain such personal data, depending on what pages you track and what data is being collected (see also: how not to process any personal data):
- IP Address is considered personal data, unless you have enabled the IP anonimisation to at least 2 bytes.
- User ID may be personal data (you may also activate the privacy feature to replace each User ID with a pseudonym).
- Custom dimensions and Custom variables may store personal data.
- Site searches (on your website) may be personal data (for example when users search for their name or postcode on your website search engine).
- Both Heatmap pages and Session Recordings, may contain personal data (for example, a Profile page on a social media website would include the name and photo of the user which would be recorded in the Heatmap and/or the Session Recording). If you want to not track these data, then you can specifically discard tracking them by using
data-matomo-maskattribute on these page elements containing personal data.
- In Session recordings, please note that by default all form fields values are automatically discarded and not tracked. To track form field values in Session Recordings, you would need to manually mark the form fields to track with
- Both Page URLs and Page titles and Custom Events may contain personal data depending on how your website(s) are designed (for example when the Page URL or URL parameters include email, postcode, name, or a physical address).
- Referrer URLs may contain personal data (for example when your users come from another website which leaks your visitor’s personal data in their page URLs).
- Tracking cookies IDs may (or may not) be considered personal data, and can be disabled.
- Geolocation is based on the IP address and may be considered personal data.
- Ecommerce Order IDs is generally considered personal data as the order ID can be linked back to the customer. You may also activate the privacy feature to replace each Order ID with a pseudonym.
How does Matomo detect unique and returning visitors? (with User ID, Visitor ID from cookie and/or fingerprint)
This FAQ explains how does Matomo (Piwik) Tracking API detect unique visitors, and returning visitors, depending on how the Tracking API is used.
When a visitor views a page or screen, Matomo will attempt to detect whether this request belongs to an existing visit, and/or whether the visitor has visited the website before.
How does Matomo detect whether the visitor is known?
- If a User ID is set, either via
setUserIdin your favorite SDK or via
&uid=in the Tracking API, this User ID will be converted (hashed) into a Visitor ID hexadecimal string. The hashed User ID becomes the Visitor ID. We look first for visits where the
log_visit.idvisitormatches this Visitor ID (User ID). If no visit is matched, we look for visits where the
log_visit.config_idmatches the visitor fingerprint.
- When a Visitor ID was manually set in the Tracking API via
&cid=(see: Tracking API reference for
cid), we only look for visits where
trust_visitors_cookiesis set to 1 (see: FAQ about
trust_visitor_cookies), and a visitor ID is found either in first party cookie
_pk_id(see: first party tracking cookies) or in the third party cookie (see: enabling third party cookies), we only look for visits where
log_visit.idvisitormatches the visitor ID from cookie.
- Otherwise when a visitor ID is found in a first party cookie or in the third party cookie, we look first for visits where the
log_visit.idvisitormatches the visitor ID from cookie. If no visit is matched, we look for visits where the
log_visit.config_idmatches the visitor fingerprint.
- Finally, when there is no visitor ID found in first party cookie (nor in the third party cookie) and a visitor ID was not specified via
&cid=, we only look for visits where the
log_visit.config_idmatches the visitor fingerprint.
When matching visits by visitor/user ID, Matomo looks through the entire history of visits that are currently in the database. When matching visits by device fingerprint (
log_visit.config_id), we only look back
window_look_back_for_visitor seconds. By default, this value is set to 30 minutes. This setting can be changed: learn more.
If a visitor is found, then Matomo will assign the current request to this existing visitor, either by updating the current visitor’s visit or by creating a new visit when appropriate (learn more about what Matomo considers a visit)
How does Matomo detect a returning visitor?
A visitor will be marked as ‘Returning visitor’ when:
- she has visited the website at least once before this visit (this can be detected via the ‘visit count’ and ‘first visit time’ and ‘last visit time’ found in tracking cookie and sent to Tracking API as
- or she has visited the website but with tracking cookies deleted or lost, Matomo still managed to find a previous visit from this person (applicable when customising
- or she has purchased an item on the website before this visit (according to the ‘last ecommerce order date’ found in tracking cookie and sent to Tracking API as
How is the visitor fingerprint processed?
The visitor fingerprint is a hash of a set of the visitor’s settings and attributes. The fingerprint (also called
config_id or config hash) is a unique string calculated for a visitor based on their operating system, browser, browser plugins, IP address and browser language. This fingerprint is necessary to process unique visitors accurately, but we aim to take all possible measures to protect users privacy:
- the website ID is used to process the visitor fingerprint hash which means that on your Matomo instance, a given user/visitor will have a different fingerprint hash when browsing your different websites. (this is the default behavior which can be disabled by setting
- the IP address used to create the hash will be the anonimized IP address when you have enabled IP anonimisation which is the default privacy setting in Matomo (when you select “Also use anonymised IP when enriching visit: No” then the full IP address will be used in the hash calculation).
- a unique salt is used for each Matomo instance so that a same user/visitor’s hashes are different across several Matomo servers (this cannot be disabled).
How are visitors tracked across multiple domain names?
When you track multiple domain names in the same website in Matomo, you likely want to track your visitors across all the domains. You can use Cross Domain linking for this, learn more in our Measuring Visitors Across Domains – Cross domain linking FAQ.
When measuring activity with the Matomo (Piwik) Tracking API, the following HTTP headers may be used:
Host– the hostname of the HTTP request, the hostname of the Matomo server.
Referer– used to track Referrer information such as website, search engine, social network.
User-Agent– used to detect the information about browsers, operating system, devices by device-detector library.
Cookie– when Opted-out from tracking, or when Third party cookies are used.
Origin– used when cross-origin resource sharing is enabled.
Accept-Language– used to detect the users’ language
X-Forwarded-For– when Matomo is setup behind a proxy
DNT– used to detect whether a visitor’s device is opted-out from tracking (Matomo privacy)
Yes, Matomo (Piwik) 2.15.0 and newer can be used with CSP. However, you cannot use the standard tracking code generated by the Tracking Code Generator in the Matomo UI as it is not allowed to use inline scripts when having CSP enabled. CSP is a security concept to prevent cross-site scripting (XSS) attacks as well as related attacks.
Instead make sure to put the tracking code into files like this:
<script src="http://example.com/matomo/matomo.js" async defer></script>
matomo.js should be loaded from your Matomo server and
tracking.js should contain the actual tracking calls like this:
var idSite = 1; var matomoTrackingApiUrl = 'http://example.com/matomo/matomo.php'; var _paq = window._paq || ; _paq.push(['setTrackerUrl', matomoTrackingApiUrl]); _paq.push(['setSiteId', idSite]); _paq.push(['trackPageView']); _paq.push(['enableLinkTracking']);
Make sure to specify the correct
idSite if needed and to replace the Matomo Tracking API URL. You can build this URL by appending
/matomo.php to your Matomo domain.
If you load
matomo.js from a different domain make sure to allow the Matomo domain like this:
An example response header looks like this:
Header set Content-Security-Policy "default-src 'self'; script-src 'self' http://example.com; style-src 'self'; frame-ancestors 'self'; frame-src 'self';"
If CSP should work in all browsers you might have to add further headers. At the time of writing this article you might as well need to set
X-WebKit-CSP for Safari and
X-Content-Security-Policy for Internet Explorer support. Read more about Content Security Policy.
Two-factor authentication increase your account security by adding an additional layer of verification when you log in. Each time you log in, you will not only be asked to provide your login and password, but also an additional authentication token which changes periodically and is generated typically on your mobile device (phone or tablet). This means that even when someone knows your username and password, they still won’t be able to log in unless they have access to your mobile device.
We strongly recommend you to use two-factor authentication for the safety of your account.
You can activate two-factor authentication by going to “Administration => Personal Settings”. There you will find a link to activate it. When you set this up, make sure to backup your recovery codes in case you lose your mobile device or if you cannot access it anymore.
A user with super user access can force every user to have two-factor authentication enabled. In this case, you might be forced to set up two-factor authentication and you won’t be able to disable it anymore.
When the Matomo server is unavailable (down) how does this affect my websites loading speed and tracking data collection?
It may happen that your Matomo (Piwik) analytics platform service is down / unavailable temporarily. Here are some important notes:
Your websites will still load correctly and should not be affected by any problem on the Matomo side. In the worst case scenario where Matomo server(s) are completely down and do not serve the
If for a few minutes or a few hours, your Matomo service is down, you may have lost data for this time period. In some cases, it is possible to replay most, or all, of the lost data. Learn more about how to replay your Matomo web server access logs and restore your tracking data that was not imported during the outage.
I have custom needs for a new Matomo functionality, such as a new custom plugin or a new report. Who can build for me a quality solution to solve my requirements?
If you have custom needs and requirements, for example if you need a new functionality in Matomo (Piwik), or a new report in your analytics dashboard, or even a new custom plugin, you can get in touch with the leading Matomo experts by filling in our form: https://matomo.org/development/
After you send in the form below we will check the requirements and will get back to you as soon as possible with a proposal and estimate.
We have created many quality solutions for Matomo clients over the years and we look forward to helping you.
Matomo (Piwik) is an analytics platform that comes with a set of APIs (Tracking API and Reporting & Management API), a web application with a modern user interface, but Matomo also comes with a powerful console tool.
To use the console, connect to your server running Matomo using SSH or your server console. The tool is a script located in Matomo’s root directory and called console. You can run it with the command:
The Matomo console has many uses and new commands are regularly added to the console. By default, Matomo has commands to enable and disable plugins (
plugin:deactivate), modify the config.ini.php file pragmatically (
config:set), clear the cache (
cache:clear), run the archiver (
core:archive), delete old log data (
core:delete-logs-data), invalidate specific old reports (
core:invalidate-report-data), run the scheduled tasks (
scheduled-tasks:run), update Matomo system and database after the files were updated (
core:update), enable the development mode (
development:enable), run the system check diagnostics (
diagnostics:run), open and watch the content of the Matomo log messages (
log:watch), and many others.
List all of the commands available on your Matomo server by running:
Plugins you use from the Marketplace may also add new console commands. For example the CustomDimensions plugin will add new console commands to list information about custom dimensions (
customdimensions:info) or to let you add and remove custom dimensions (
At Matomo (Piwik) we are fond of libre and free and open software! Besides the Matomo platform, we have created and maintain other open source projects:
Our free projects related to Matomo
- Device Detector: the Universal Device Detection library will parse any User Agent and detect the browser, operating system, device used (desktop, tablet, mobile, tv, cars, console, etc.), brand and model.
- Mobile SDKs: we created and maintain the iOS SDK for Matomo and the Android SDK for Matomo to let you measure your mobile applications.
- Matomo Mobile app: our mobile app running on Android and iOS devices is free/libre software project.
- Several Plugins for Matomo: all plugins are published on our open Marketplace.
Reusable PHP components
- Cache component is a PHP caching library based on Doctrine cache.
- Decompress component is a PHP library that provides several adapters to decompress files.
- Network component is a PHP library that provides network tools in particular manipulating and anonymising IP addresses.
- INI component is a PHP library to read and write INI configuration files.
Other Open source projects
- CI Trigger is a tool for Travis CI that lets you restart your builds automatically on a schedule.
- Github Changelog Generator: a handy tool that queries the GitHub issues API to create and format a changelog based off the closed Github issues.
- Github Issues Mirror: we created this tool to let any Github issues users create a read-only mirror of all issues. This has several advantages: Data ownership, Better for SEO in case not all of your GitHub issues are indexed by Google, in case GitHub is down you can still access your issues. Our Issues mirror is here: issues.piwik.org.
- Github Sync: a tool to let you synchronize labels and milestones accross several GitHub repositories. We use this to synchronise our issues labels and milestones across 50+ repositories.
To realise our epic mission, the Matomo team and the ever-growing community are building our dozens of popular tools around the project under fully open source/libre license: the Matomo core platforms (including all hundreds of features), the Matomo contributed plugins, Tracking SDKs, dozens of libraries to integrate Matomo with some of your favourite tools, and even more useful tools and products.
The founders of Matomo, core engineers and some other innovative companies are also offering some premium plugins which can be purchased on the Matomo Marketplace. As opposed to open source plugins, these premium plugins are not released under an open source compatible license and you are not allowed to redistribute premium plugins to others. (Note: if you ever need to edit or modify the source code, you can get a permission on simple request to the developers.)
Why Premium plugins? Researching, building, documenting, testing and maintaining quality products take years of experience and months of work. When you purchase a premium plugin you get a fully working product, with free updates for duration of license and you stay in full control of your analytics data. When purchasing a premium plugins you also directly help the Matomo core engineers to grow and keep innovate! That’s because a % of earnings on premium plugin license sales directly fund the new Matomo versions and cool features. In particular, plugins sales will fund:
- the core Matomo Analytics (formerly Piwik Analytics) platform innovation: where everything is open and will always be.
- all free and open source plugins created and maintained by us. Already twelve of them and we will create more in the future.
- our free Long Term Support for all users of Matomo.
To summarise: everything that the Matomo project officially releases under “Piwik” is open source and free software and this will never change. On the Marketplace, innovative companies also sell Premium features for Matomo (such as Media Analytics, Audit Log or Experiments – A/B Testing) and when your purchase them you help support building more great features in the Free Software Matomo Analytics (formerly Piwik Analytics) platform.
Does Matomo have a professional services team who can assist with on-site training, implementation and/or software customizations?
Yes, we assist clients of all sizes with on-site training, implementation, customization requirements, and our Matomo Cloud (formerly Piwik Cloud) service. Contact our Support team to get started.
In the context of GDPR compliance, a data processing agreement (DPA) is a legally binding document to be entered into between the controller and the processor in writing or in electronic form. It regulates the particularities of data processing – such as its scope and purpose – as well as the relationship between the controller and the processor.
In the context of Matomo you have two options:
- When you use the official Matomo Analytics Cloud service a Data Processing Agreement is available and can be viewed here: matomo.cloud/dpa. You may agree to the DPA when you sign-up to the service, or later (in Matomo Administration > GDPR Overview page).
- When you self-host Matomo on your own servers, then you do not have a Data Processing Agreement available, but your data processors may offer a DPA and suggest steps for GDPR compliance. Learn more in our article: How to make Matomo GDPR compliant in 12 steps, and in our GDPR user guide.
No. You may not use the Matomo (Piwik) trademark or any other mark associated with the Matomo offering in your domain name or URL. (For example, “www.piwik-service.net” is not allowed). Learn more about the Matomo trademark.