Mamoto
how to

How do I make Matomo faster?

By default, Matomo (Piwik) reports are processed when you request them in the User Interface. Please see How to setup auto archiving of your reports every night? to automate the generation of Matomo reports. See also How long does the Matomo archiving process? for expected speed for high traffic websites.

If you are running Matomo analytics for a high traffic websites (or hundreds of them), see our guide Optimize Matomo server for speed.

How do I check in real-time whether my goal conversions are triggered correctly on my website?

The visitor log will always show the result of a goal in real time, you will need to find out the Visitor ID to correlate this with the goal. This can be easily found in the HTTP requests.

In your target web page start the web console and view the network tab. Filter the results to only show Matomo requests. The piwik.php request contains your Visitor ID in the URL parameters.

This ID will match with a visitor in your visitor log.

Viewing this user’s visit history you will be able to see if they have successfully converted a goal.

To find the visitor quicky when you only have the Visitor ID, you can create a Segment so you will only see this user’s visits:

• Click Add new segment from the Segmentation menu.
• Then select Visitor ID from the first dropdown menu, then the is operator.
• Copy and paste the Visitor ID established earlier in the last field
• Save and apply the segmentation.
• Then open the Visitor Log to see all the visits and interactions by this Visitor (pageviews, clicks, downloads, events, forms, videos, goals…).

Example segment to find a specific Visitor ID:

How do I use Extractions to track action data with Custom Dimensions?

One of the key features of Custom Dimensions is the ability to track custom data associated with actions such as page views. Often this requires you to add custom code to your site or make use of a tag manager. However, it is also possible to collect data directly from a Page URL, Page Parameters or Page Titles with the help of Matomo’s built-in Extraction feature.

Every site is unique, so the Custom Dimensions and values you choose to focus on will likely vary. Additionally, there may be different methods for collecting the same information depending on how your site is configured. On this page, you’ll find general instructions on how to set up each type of extraction, along with an example of when and how you might use a certain type of extraction.

It is important to remember that Extractions can only be used on Action scoped Custom Dimensions. You can learn more about scopes in the Custom Dimensions guide.

How to Set Up Extractions for Custom Dimension Data

You can set up extractions on the configuration page of the Custom Dimension they are associated with. You can get to your Custom Dimensions by clicking the cog icon  in the blue top menu. Once there, find the Websites or Measurables link (the name varies depending on your version of Matomo) in the Main Navigation along the left-hand side and then click on the Custom Dimensions link.

Once on the Custom Dimension page, scroll to the Action Dimensions section. Next either, click the big green button to create a new dimension or click on the edit icon  to configure an existing one.

You can find the relevant settings for creating and managing extractions under the Extract Value heading.

Your next steps will vary slightly depending on the type of extraction you require.

How Matomo extracts the value using RegEx

When configuring extractions via the Page URL and Page Title, you will need to use RegEx search patterns. Learning all of the RegEx variables is beyond the scope of this document. However, one important aspect unique to its use with Custom Dimensions for Matomo is that the first expression in a bracket will extract the value to set against the dimension. To provide a couple of examples:

Custom Dimension for Page ID via Page URL

• Website URL Path: /news/780546/new-nightvision-camera/
• RegEx Search Pattern: /news/(.*)/.*
• Extraction Result: 780546

Custom Dimension for Author Pages via Page Title

• Website Page Title: Posts By Jane Doe
• RegEx Search Pattern: Posts By (.*)
• Extraction Result: Jane Doe

If you are unfamiliar with regular expressions, we highly recommend you learn about regex before using it and always remember to test your RegEx patterns extensively.

Developers Note: You don’t need to escape forward slashes as Matomo does this for you automatically. e.g. use /news/ instead of \/news\/

Page URL Extraction Example

To use the Extraction feature on Page URLs, the data you plan to track needs to be accessible within the URL. An example use case for URL extraction is tracking the language of a visit on a multi-language site. In the following URL structure, the language code for English en is clearly defined:

https://example.com/lang-en/plugin/

In the URL above, the first part contains the domain https://example.com/. This is followed by the section where the language lang- is set with en representing the two-letter language code for English. Finally, the remainder of the path /plugin/ is the specific page someone is viewing. Following that same structure, the equivalent page in French would have the following URL:

https://example.com/lang-fr/plugin/

As these pages share a common structure, you can safely extract the language code with a RegEx (regular expression) pattern targeting the language code. For the example URL structure above, you can use the RegEx pattern /lang-(.*)/.*/ to capture the language code as shown in the screenshot below:

The above regex looks for the initial /lang- prefix within the URL, then the grouped wildcard (.*) extracts the language code to be associated with the custom dimension. Finally, there are two slashes with a wildcard in the middle /.*/ to ensure that the RegEx pattern catches every page with a language prefix.

Once this custom dimension has been created, you can test it by visiting any page following the same URL structure. To confirm that the data is being tracked appropriately, you should head to the Visits Log, find your specific visit and hover over the URL to see any associated Custom Dimensions. In the screenshot below, you can see that the Page Language dimension has been set as equal to en.

This is just one example of a regex pattern in use. It is possible to create pretty advanced patterns depending on your specific URL structure. There is another example of RegEx in use within the Page Title section below.

Page Title Extraction Example

While Page Titles are often unique for each page, they often share partial similarities. For example, you might include the word Blog for every blog post or Members Area for members-only sections of your website. Consider these example page titles for two blog posts:

• “New Smartphone Makes Your Coffee – Tech Articles”
• “Why You Need to Use Analytics – Marketing Articles”

While the first half looks likely to change for every article, there is a clear pattern for the second part of the title which includes the category that the blog post is in, e.g. Tech or Marketing. If this pattern is consistent across the entire site, you could craft a RegEx pattern designed to extract the blog post category. In this case, you might use the following pattern:

.*–\s(.*)\sArticles

Breaking down the individual components in the pattern above .* matches any number of any characters, until the – kicks in looking for the break in the title. Next, the \s represents a space character to avoid unnecessary spaces within the custom dimensions value. Then the grouped wildcard (.*) selects the actual category text, before the final space character \s and Articles closes off the pattern. Therefore, the extracted values from the above RegEx example would be the words shown in bold below:

• “New Smartphone Makes Your Coffee – Tech Articles”
• “Why You Need to Use Analytics – Marketing Articles”

To test this is working, you can visit any pages matching your pattern and then find your pageview within the Visits Log. If you were following the example above, you would see the following when hovering over the page view:

Page Parameter Extraction Example

Page parameters are elements shown at the end of your URL. They often contain arbitrary data for various reasons, some of which you may want to set up Custom Dimensions for. The first parameter within a URL is preceded by a ? and any following parameters are separated with a &.

As an example, some affiliate programs (where people refer traffic to a site for payment) track referrals via query parameters. This would look a little something like the following URL where ref is the query parameter, and affiliate is the parameter value:

https://example.com/plugin/?ref=affiliate

If you were running an affiliate program this way, it could prove useful to create a custom dimension that tracks which page views were referred by affiliates and which affiliates are driving the most traffic.

Parameters are a little easier to configure than Page URLs as they don’t require RegEx. Instead, you just need to specify the parameter that should be tracked.

Once you have set up the match, you can test that it’s working by visiting a URL containing your page parameter and then finding your page view in the Visits Log. Following the example above, you would see the following when hovering over the page view:

More Resources

You can learn more about how to report on and analyse these values in the complete Custom Dimensions guide.

How do I exclude traffic from an IP or a range of IP addresses?

To exclude all traffic from a given IP or IP range, log in Matomo (Piwik) as the Super User. Click on Administration > Websites/Measurables > Settings. You will find the option to specify “Global list of Excluded IPs”. Specify one IP address per line. Each Matomo admin user can also specify the list of IPs or IP ranges to exclude for specific websites.

You can define a given IP address, or IP ranges (132.4.3.* or 143.2.*.* for example) to be excluded from being tracked on all websites. You may also use the CIDR notation for IP addresses for example: 112.4.2.0/24, or 2001:db8::/32.

When you exclude visits from these IP addresses, it will only apply to new visits going forward. Historical visits from these IP addresses will not be deleted.

Note: even if you have enabled IP anonymisation, IP exclusion will still work as expected (the IP exclusion occurs before the IP is anonymised). This guide is applicable only for Matomo On-Premise and Matomo Cloud.

How do I exclude URL query parameters from the URLs tracked, and from Pages reports?

It is common that websites use URLs query parameters or session ID parameters that are not relevant to data analysis (unique ID, meaningless parameter).

You can easily ignore a number of parameters from the URLs, and prevent them from appearing in the “Behavior > Pages” report. Login as the Super User, go to Administration > Manage Websites > Global list of Query URL parameters to exclude field.

Each Matomo (Piwik) admin user can also exclude query parameters for specific websites, by entering them in the Excluded Parameters list for this website, in Administration > Websites > Manage.

If you are using Matomo for WordPress, then you can configure the query parameters directly in WordPress by going to Matomo Analytics => Settings => Exclusions.

For example take this URL path: hello.html?module=peace&vid=476tgkg. If you configure Matomo to exclude the URL parameter vid from Page Urls then the URL will be tracked as: hello.html?module=peace.

To exclude multiple parameters, specify each parameter on a new line, for example to exclude two parameters:

vid
sessionid

When you specify one or several parameters to exclude from your URLs, note that it will only affect data going forward. (URL parameters will not be removed from your historical data and reports)

How do I export the Raw data from Matomo (users, actions, clicks)?

We design the Matomo Analytics (formerly Piwik Analytics) platform in a way that all the data is yours and can be easily exported. We offer many APIs which let you get all of your data, and one API in particular which lets you get all of the RAW data.

The API you want to use is Live.getLastVisitsDetails and is listed here: developer.matomo.org/api-reference/reporting-api#Live

You can use this API to download the data for a given website (or all websites), for given day / week / month / year (or all-time), and you can even specify a Custom Segment to filter out the data and return only the users that match a particular criteria.

If there is any data that you cannot export via our standard APIs, you may want to consider the Custom Reports premium feature which lets you create any report based on your requirements in seconds. It is our mission to help you keep full control of your data!

See also: How do I make the Matomo Analytics (formerly Piwik Analytics) data available to my data warehouse?

How do I set the time zone for my reports?

Matomo (Piwik) lets you specify the time zone to use for each website in the Websites admin panel. Click on Administration > Websites > Edit. Note: changing the website’s timezone will only affect Reports going forward.

You can also change the global timezone, so that any new website you create in the future will use your specified global timezone. Go to Administration > Measurables > Settings, and under “Default Time zone for new websites” you can specify the timezone.

Note: Matomo internally stores all times in UTC which is a software engineering best practise.

How do I specify the currency used in the Goals revenue reports?

By default, Matomo (Piwik) reports revenues in $ US dollars.

To change the default currency used by Matomo, login as Super User, then click on ‘Administration’, then ‘Websites’. Below the list of websites, you will find a section ‘Default Currency for new websites’. There you can specify the currency to use by default in Matomo for new websites.

To change the currency of a given website, go to ‘Administration’ then click on ‘Websites’ then click ‘Edit’ next to a website. In the column ‘Currency’ you can choose a new currency for this website.

How do I specify which websites to load by default in Matomo?

Login to Matomo (Piwik), in the top menu click on “Administration” and in “Personal > Settings”: you may select the website to load by default under “Report to load by default”.

Each user can specify which websites should be loaded in Matomo. Alternatively, users can choose to load the All websites dashboard, which gives an overview of the status and evolution of all websites available to the user.

How do I specify the date used by default in Matomo reports?

By default, Matomo (Piwik) will load reports for “yesterday”. Each Matomo user can specify, in their “User settings” admin panel, the date to load by default in Matomo reports: “Today”, “Current week”, “Current month”, or “Last 7 days”, “Last 30 days”, “Yesterday”, etc.

How do I add more than the default 5 custom variables?

Note: If you are not already using Custom Variables to measure your custom data, we recommend to use the Custom Dimensions feature instead. There are many advantages of Custom Dimensions over Custom variables. Custom variables will be deprecated in the future.

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

First you need to be able to connect to the server running Matomo over SSH, so you can type commands to the Matomo console. To increase the custom variables slots from 5 to 10, type in the terminal:

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

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

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

You can now track up to 10 custom variables in the visit and page scope. Enjoy!

Note: this console command will update your Matomo Database schema and will add columns in several tables in order to track more custom variables.

How do I control the categories tree structure in the Page URLs and Page titles reports?

By default, Matomo (Piwik) will report your Page URLs and Page titles in ‘categories’, automatically constructed based on the slash character / as a delimiter.
For example, a Page with a URL “http://example.org/about/contact” will be reported under the category “about” in the Page URLs report. When you click on it it will open the pages inside this category, and show the stats for the subpage “contact”. This feature is very useful because it helps visualize which sections of your website have the most traffic, rather than having all your page URLs at the same level.

This grouping feature is also very useful with Page Titles. You can use it for tracking custom flash events (“game / clickStart”, “game / registerNewUser”), video events (“videos/ bestOf2011 / start”, “videos/ bestOf2011 / pause”), simply organize your pages into a easier to analyse structure, etc.

In the Matomo Javascript tracking code, you can specify custom page titles by calling piwikTracker.setDocumentTitle() (Learn more about the JS Tracking API). For example, to track a custom page view when a user clicked on a button in your web app, you could write

piwikTracker.setDocumentTitle("ajax/click view button");
piwikTracker.trackPageView();

You can also customize the delimiter to use for splitting your page URLs and Page titles into categories (or disable the feature by setting the delimiter to a character not in use in your Page titles). Edit your config/config.ini.php file, and set the following:

[General]
action_title_category_delimiter = ::

You can then define your custom page names as follows:

piwikTracker.setDocumentTitle("Products :: Gardening :: Seeds id=123");

and your pages and categories will be grouped according to the :: delimiter.

How do I add more than the default 5 custom dimensions?

By default Matomo (Piwik) provides five Custom Dimensions slots. You may configure Matomo to track more Custom Dimensions. New Custom Dimension slots will be created in both the ‘visit’ scope and ‘action’ scope.

First you need to be able to connect to the server running Matomo over SSH, so you can type commands to the Matomo console. To add 10 new Custom Dimensions slots from 5 to 15, type in the terminal:

$ cd /path/to/piwik    
$ ./console customdimensions:add-custom-dimension --scope=visit --count=10

You can now track up to 15 custom dimensions in the visit scope. Enjoy!

You can create at least 50 dimensions in each scope (100 in total), and possibly even a few more (there is usually a hard limit from the database which will be hit when you create between 100 and 200 dimensions).

This console command customdimensions:add-custom-dimension updates your Matomo Database schema and adds new columns in several tables in order to track more custom dimensions.

How do I track impressions and clicks and CTR of image banners and/or internal banner ads or text ads?

Matomo (Piwik) provides a powerful and easy to use functionality that is designed to help you measure how many times a piece of Content was seen by your users, and how many times it was clicked on. We call this feature Content Tracking. Content Tracking reports how often a specific ad or a banner was displayed on any of your pages and how often a visitor actually interacted with them. We call these two parts content impression and content interaction. This feature is not only limited to ads or banners. You can use it for any kind of content. Learn more about Content Tracking.

Content Tracking reports will let you see:
– how many times a given ad was viewed by users (when it became visible in the browser)
– how many times a given ad was clicked
– the ratio of clicks / views, ie. how likely is it that a user clicks on the ad after seeing it.

How does this work? Once a page has loaded we log a content impression for each content block (ad block) within that page which of each consists of a content name (eg. “Sunset Poster”), a content piece (“product743.jpg” or “Buy Product 1 now”) and a content target (http://the-banner-link-url). As soon as a visitor clicks on a content block a content interaction is logged, allowing you to analyze the ratio of content impressions to content interactions.

By default. Content tracking does not track the location of the banner of the page. We don’t report whether the ad was displayed at the top of the bottom. To learn even more about how your page is overall used, and your banners overall clicked, check out the Heatmap reports. You can create a Heatmap for a given page, and then you can see visually how many people scroll down to a particular ad, how many moved their mouse over the ad, how many clicked on a particular ad, etc.

After the top 500 or top 1000 rows, Matomo automatically groups pages, keywords, websites, etc. under the label “Others”; How do I force Matomo to not limit the data?

For performance reasons, Matomo (Piwik) will by default only archive the first top 500 pages, top 1000 keywords, top 1000 websites, Custom Variables, etc. Matomo will then sum all the remaining pages, keywords, etc. under the label “Others”. If you wish to archive all the data, or simply archive more than the current rows limit, you can override these values in the configuration file config/config.ini.php.

This guide applies to Matomo On-Premise hosted on your own infrastructure. If you are using Cloud-hosted Matomo, reach out to the support team to learn more.

For example, to limit all tables to 5000 entries, add the following under the [General] category in config/config.ini.php:

[General]
; maximum number of rows for any of the Referers tables (keywords, search engines, campaigns, etc.), and Custom variables names
datatable_archiving_maximum_rows_referrers = 5000
; maximum number of rows for any of the Referers subtable (search engines by keyword, keyword by campaign, etc.), and Custom variables values
datatable_archiving_maximum_rows_subtable_referrers = 5000

; maximum number of rows for any of the Actions tables (pages, downloads, outlinks)
datatable_archiving_maximum_rows_actions = 5000
; maximum number of rows for pages in categories (sub pages, when clicking on the + for a page category)
datatable_archiving_maximum_rows_subtable_actions = 5000

; maximum number of rows for any of the Events tables (Categories, Actions, Names)
datatable_archiving_maximum_rows_events = 5000
; maximum number of rows for sub-tables of the Events tables (eg. for the subtables Categories>Actions or Categories>Names).
datatable_archiving_maximum_rows_subtable_events = 100


; maximum number of rows for the Site Search table
 datatable_archiving_maximum_rows_site_search = 5000

; maximum number of rows for the User ID report
datatable_archiving_maximum_rows_userid_users = 5000

Custom dimensions rows limit

If you are using the Custom Dimensions and/or Custom Variables plugin, you can also adjust these settings:

As of Matomo 4:

[General]
; maximum number of rows for all individual Custom Dimensions reports
datatable_archiving_maximum_rows_custom_dimensions = 5000
; maximum number of rows for the Custom Dimensions subtables (list of all Page URLs per dimension value)
datatable_archiving_maximum_rows_subtable_custom_dimensions = 5000

; maximum number of rows for Custom Variables names report
datatable_archiving_maximum_rows_custom_variables = 5000
; maximum number of rows for Custom Variables values reports
datatable_archiving_maximum_rows_subtable_custom_variables = 5000

Before Matomo 4:

[General]
; maximum number of rows for all individual Custom Dimensions reports, and for Custom Variables names report
datatable_archiving_maximum_rows_custom_variables = 5000
; maximum number of rows for the Custom Dimensions subtables (list of all Page URLs per dimension value), and for Custom Variables values reports
datatable_archiving_maximum_rows_subtable_custom_variables = 5000

Custom Reports

If you are using the Custom Reports premium feature, you can also adjust these settings:

[CustomReports]
datatable_archiving_maximum_rows_custom_reports = 1000
datatable_archiving_maximum_rows_subtable_custom_reports = 500

Media Analytics

If you are using the Media Analytics premium feature, you can also adjust these settings:

[MediaAnalytics]
datatable_archiving_maximum_rows_media = 1000
datatable_archiving_maximum_rows_subtable_media = 500

Other report limits

Some reports do not have a specific row limit definable in the config.ini.php file, for example the Location reports (i.e. Regions & Cities).
By default this is set to 500, and can be changed by adding the following under the [General] category.

datatable_archiving_maximum_rows_standard = 5000

Reprocessing reports

After doing this change, if you want your old reports to be re-processed with this new number of rows, see FAQ on how to re-process reports.

Archiving all data (unlimited rows)

If you really need to archive all data, you can set a very high number, for example one million: 1000000.

How do I measure and give people access to their reports for some page sections / categories / mini-sites / languages?

Sometimes your website or app includes multiple “sections” (or page “categories” or “mini-site”), and you want to track and report them separately from each other. For example your website is translated in multiple languages, or when your app is serving multiple markets, and you want to see reports for each language or market (“section”).

Solution 1) Tracking each website section as its own website and use Roll-Up Reporting

This works by tracking each “section” in its own separate website in Matomo​​ and use Roll-up Reporting to get aggregated reports across all sections/websites.

This allows you to easily grant people read or write access to the report about a particular “section” without giving them access to data for all “sections”.

To track the data, first you will need to create new websites in Matomo. Then in the JavaScript tracking code, the line containing _paq.push(['setSiteId', 'ID_SITE_HERE']); will need to be referencing the correct website ID so you need a it of logic to set ID_SITE_HERE depending on which “section” your visitors are currently browsing.

Once the data is tracked, you can use Roll-Up reporting feature to aggregate your websites together in a Roll-Up and view all reports across all websites. Learn more in the Roll-Up Reporting user guide.

You can also give users explicit permission to access any of these websites reports by creating new users and managing their permissions.

If you end up creating many websites, you might want to automate the process of creating/updating/deleting websites via the SitesManager API.

Solution 2) One website, one custom dimension, and several custom reports and/or segments

​In this solution we will track the “section” of your websites in a new Custom Dimension, and then create Custom Reports to see reports for each of the categories you need a report for.

Create a new custom dimension in “Action” scope

First, you will need to create a Custom Dimension of Action scope called for example “Section”. Secondly​, you will need to track this dimension value in your website. ​For example you can use JavaScript and call the setCustomDimension function. ​Or if there is a URL parameter which has your “category” value, then you can configure your dimension to use this URL parameter as the dimension value. Learn how to create and track a custom dimension in the User guide.

Once the custom dimension is tracked you will be able to view the list of all values in the report. See example in the online demo.

(recommended) Create a new custom dimension in “Visit” scope

If you track Goals or Ecommerce then we also recommend to create a second custom dimension, but this time in the scope “Visit” (the first dimension above was in the scope “Action”). Having the custom dimension also in the “Visit” scope will make it easy for you to attribute Goals and/or Ecommerce orders to the last visited “Section” of your website. So you will see a list of all your website sections/categories (that were last viewed before the user converted) and the following metrics will be displayed: number of visits, conversions, conversion rate, revenue, etc. This valuable data will be displayed below every Goal or Ecommerce report.

Creating the “Sections” custom reports

Finally, you want to see the detailed report for each section of your website. To be able to view any Matomo report for a “section”, we will create a Custom report in Matomo. For this custom report we will 1) select dimensions of “Page URL” or “Page Title” for example, and 2) also define a “Filter” such as Where custom dimension 'Section' is 'News'.

Then when viewing this custom report, it will only show those pages that match the filter and therefore belong to this particular section of your website. Learn more about creating custom reports in the User guide.

(If you end up creating many reports, you might want to automate the process of creating/updating/deleting custom reports via the CustomReports API, contact us for more information).

(optional) Create segments for important “Sections”

You can also create Segments such as Visits where custom dimension 'Section' is 'Profile' and apply the segment to any report in Matomo, and the reports will only include users that match the segment. You can also get scheduled email reports created and including data for these segments only. Note that when you’re using Segments, the segmented reports will include all the pages these visits did, so in the pages report you will see pages where ‘Section’ is ‘Profile’ but also any other page from these visits such as ‘Sports’, ‘Technology’, ‘Ecology’, etc.

If you end up creating many segments, you might want to automate the process of creating/updating/deleting segments via the SegmentEditor API.

How do I track how many users open and read my newsletter emails (using a pixel / beacon)?

With Matomo (Piwik) you can add a small image beacon (pixel) in your newsletter emails, so you can track how many people actually read and open the newsletter email.

To track how many people open and read your newsletters, you can add the following HTML image code in your newsletter:

<img src="https://matomo.example.com/matomo.php?idsite=YOUR_MATOMO_WEBSITE_ID&rec=1&bots=1&url=https%3A%2F%2Fexample.com%2Femail-opened%2Fnewsletter_XYZ&action_name=Email%20opened&_rcn=internal%20email%20name&_rck=newsletter_XYZ" style="border:0;” alt="" />

Once you add this code in your newsletters, when your users open and read the newsletter, it will add a new “Page title” entry for “Email opened” in your Behavior > Page titles report.
You will also be able to see this information in the Visitor Log.

In this example, replace:

• https://matomo.example.com/ by your Matomo URL
• YOUR_MATOMO_WEBSITE_ID by your Website ID (learn more)

When you use the HTML code above, the following information will also be recorded in Matomo:

• &url=%2Femail-opened%2Fnewsletter_XYZ records a pageview with the URL set to to “/email-opened/newsletter_XYZ” in Behavior > Page URLs report.
• &action_name=Email%20opened records a Page Title set to “Email opened” in Behavior > Page titles report.
• &_rcn=internal%20email%20name records a visit from a Campaign and sets the campaign name to “internal email name” in Referrers > Campaigns report.
• &_rck=newsletter_XYZ will also set the campaign keyword to “newsletter_XYZ” (set it to the name of this particular email newsletter for example “Summer-deals-2017-August”) in Referrers > Campaigns report.
• when the people receiving your emails are all on the same internal networks and using a similar email client, you will find that the Unique Users/Unique Visitors KPI metric value will be wrong. To solve this issue you want to append the parameter: &cid= which should be set to a uniquely generated string of exactly 16 hexadecimal characters (containing only characters 01234567890abcdefABCDEF). This will set the Visitor ID to a unique string for each email recipient ensuring Matomo tracks them correctly.
  • &rec=1 in order for the request to be actually recorded.
  • &bots=1 o include all the connections made to this request, bots included.

You may have noticed some special characters here such as %20, %2F. That’s because the URL is encoded. We strongly recommend you to do so in order for your tracking not to break. Many tools are available on the web in order to encode your URLs such as urlencoder.org.

If you would like to access the previous tracking code easily, keep in mind that you can always find the tracking code generator within the “Matomo > Administration >Tracking code > Image Tracking”.

Tracking even more data: the user ID example

You can go deeper in your URL tracking by inserting other parameters such as the user id if you have this information within your emailing database. One of the main benefit of tracking the User ID is to connect data across multiple devices and browsers for a given user.

You only need to add the following parameter &uid=XXX where XXX equals the dynamic value of the user ID.

Make sure that UID from your emailing provider is the same as the one used on your website in order for your data to be consistent.

Important note about inaccurate data

Some email providers (including gmail/google apps) pre-load all images from email messages by default, which results in Matomo tracking an email open even if the user did not actually open the email yet. This inaccuracy affects any other email analytics tools as well.

Other resources

• How to measure the performance of a newsletter (or any email) with Matomo
• When tracking visitors using an image beacon instead of the JavaScript tracker, what are the differences?

How do I make the Matomo Analytics RAW data available to my data warehouse?

If you need to access Matomo RAW data and import it in your data warehouse or BI tool, there are two options: HTTP API data export, or direct database export.

1) Export all data using our HTTP API

Using our HTTP API you can export all your individual users data and all users actions (visits, pages, clicks, events, downloads, custom dimensions, user location, user information, and more). The API used to export all your Raw data is called Live.getLastVisitsDetails and lets you export all the user and clickstream data for a given website and a given date. Optionally a Custom Segment when you need to export specific segment of users). For example if you wanted to export the full dataset for yesterday, you would use the following API call:

https://demo.matomo.cloud/?module=API&method=Live.getLastVisitsDetails&idSite=62&period=day&date=yesterday&format=xml&token_auth=anonymous&filter_limit=100

• Replace the domain name demo.matomo.cloud by your Matomo Analytics (formerly Piwik Analytics) URL
• In &token_auth=anonymous, replace anonymous by the token_auth of your API user. We recommend you create a new user in Matomo, for example called ‘api-data-warehouse-export’ and grant this user a ‘view’ permission on the website you’re exporting to data warehouse, and then use this user’s token_auth in your API calls.
• The &filter_limit=100 parameter makes sure that all the data for this day will be returned. Use &filter_limit=-1 to return all rows.
• The data can be exported in JSON, XML, CSV, and more. Replace &formal=xml by your favorite data format.
• This API could be called once a day and all output data can be imported in your data warehouse.

Important note about high traffic Matomo servers

if you export a lot of data, for example more than 10,000 visits and their associated actions and clickstream, then the HTTP request above may take a long time or even time out (depending on your server and PHP settings). You may get errors such as Maximum execution time of 0 seconds exceeded. Up to a certain limit you can increase the PHP memory limit, but it is not recommended to increase above 4G and sometimes 4G is not enough to return thousands or dozen thousands of visitors and all their actions.

Therefore when you export a lot of data, we recommend that you only export 10,000 at a time and use our paging &filter_offset= feature. Here is how this works: to export the first 10,000 records, instead of filter_limit=-1 you would write filter_limit=10000&filter_offset=0. Then, to export the next dataset, you would write filter_limit=10000&filter_offset=10000. Then to export the next dataset, you will write filter_limit=10000&filter_offset=20000. You repeat this until there is no more result in the dataset.

2) Direct read-only access to the MySQL database

Another solution is to directly access the Matomo Analytics (formerly Piwik Analytics) MySQL database where all your data is stored. This solution should be faster to import a lot of data, especially when your data warehouse supports data import from MySQL. We recommend to create a Read-only mysql user who can only accces the Matomo database and read data from it (not allowed to write). You will find more information about the Matomo database structure in our developer guide. Note that the database schema may change in the future.

For example to select the data from the database, similar to the Visits log, you can use the following query:

     SELECT *
     FROM matomo_log_visit
     LEFT JOIN matomo_log_link_visit_action ON matomo_log_visit.idvisit = matomo_log_link_visit_action.idvisit
     LEFT JOIN matomo_log_action ON matomo_log_action.idaction = matomo_log_link_visit_action.idaction_url
     LEFT JOIN matomo_log_conversion ON matomo_log_visit.idvisit = matomo_log_conversion.idvisit
     LEFT JOIN matomo_log_conversion_item ON matomo_log_visit.idvisit = matomo_log_conversion_item.idvisit;

(Note: the query result set will contain some duplicated columns because the same columns exist in multiple tables.)

A list of useful SQL queries to export all visits and actions is also provided in another FAQ.

If you need more information about Data warehousing best practises, please contact the Matomo professional support team.

How do I view Matomo application logs?

Matomo (Piwik) application logs are messages that are written by Matomo.

You can view logs by installing the LogViewer plugin. The plugin can be installed via the Matomo Marketplace with just a few clicks in your Matomo installation. As a Super User simply go to the Administration and select Marketplace in the left menu. There you will find the plugin and can install it with just one click.

This plugin will be useful if you experience any problem and want to troubleshoot your Matomo installation, for example when some tracking requests are not processed correctly.

Configuring logging in Matomo

By default Matomo won’t show anything in the LogViewer plugin as logs are written only to screen. In order to actually view logs you need to enable either logging to file or to the database. The database log writer is recommended when you use more than one server for your Matomo installation.

You can read about this in detail in the FAQ article How do I enable logging in Matomo.

In most cases it is enough to add the following lines to your config/config.ini.php file:

[log]
log_writers[] = file

The Matomo application log is located at piwik/tmp/logs/matomo.log.

If you do not see any log messages afterwards this might be just because there were no warnings or errors yet. You can increase the log level by adding the following line to the [log] section to see if it works in general:

log_level = DEBUG

Enabling logging for Matomo Tracker

The Matomo Tracker API (piwik.php) needs an additional configuration in order to actually log messages. See the documentation page about enabling Debug logging in the piwik.php tracker

Using the LogViewer plugin

Once logging is configured you can view the logged messages as a Super User by going to the Administration and selecting LogViewer from the Diagnostic section.

You can search for any log messages, filter by log level, switch between the file and database writer and export log messages. Handy is the possibility to narrow down the displayed messages by clicking on a column. For example you can click on a RequestId and see all messages that were logged during the same request.

How do I force the reports to be re-processed from the logs?

In some rare occasions it may be useful to force Matomo (Piwik) to re-process the reports from the original logs. By default, reports will only be processed once (preferably with an automatic cronjob setup to run every hour) and then archived in the database. When you visit the Matomo UI for a previous day (or week, month, etc), all you see is pre-processed data read directly from these archive tables.

1) Invalidate the existing historical aggregate reports

To force Matomo to re-process your reports you can use one of the following solutions:

• (Recommended) Invalidate historical reports by calling a Console command, or using the API, or using a user interface, to tell Matomo to invalidate and re-process the past reports.
• (Not recommended) or you could edit your config/config.ini.php file, and set (when you are done, do not forget to set these values back to 0):

  [Debug]
  always_archive_data_day=1 ; force archiving of all daily reports
  always_archive_data_period=1 ; force archiving for all period reports (week, month, year)
  

• (Not recommended) or to reprocess reports for a specific day, or specific period, you can delete the two Mysql tables matomo_archive_* for the specific month containing the dates to re-process. To delete the tables, you can use a tool such as phpMyAdmin which is usually provided by your web host. If you disable browser archiving in your matomo, then you’ll also have to invalidate the entire month in order for the reports to be re-archived. (This does not always apply for Matomo 3.x and below.)
• (Not recommended) or to reprocess archiving for all reports for all dates, you will have to delete all matomo_archive_* tables in the Matomo Mysql Database. To delete report data for one full year including monthly reports, you may have to delete up to 24 tables (12 months * 2 tables). If you disable browser archiving in your matomo, then you’ll also have to invalidate every day you want to re-archive in order for the reports to be re-archived. (This does not always apply for Matomo 3.x and below.)

You are almost done!

2) Re-process your reports

When you login your Matomo, Matomo will re-trigger the processing of the report data which will re-create the archive tables. This may take one second on a small website but it could take several minutes for bigger websites.

When you want to ensure that reports load fast, invalidate the date ranges you want to re-create archives for and run the following command to pre-process your report data for all websites:

./console core:archive --force-all-websites --url=YOUR_MATOMO_URL_HERE

(this command is a little customisation of the standard core:archive cron command. To learn more about what the parameters mean, run ./console help core:archive)

if you’re using Matomo 3.x

Run the following command with the --force-all-periods parameter to pre-process your report data for all websites:

./console core:archive --force-all-websites --force-all-periods=315576000 --force-date-last-n=1000 --url=YOUR_MATOMO_URL_HERE

You also do not need to invalidate data in the past.

Summary

Congratulations, you have re-processed your data and it should now appear as expected in your dashboard.

How do I write SQL queries to select visitors, list of pageviews, searches, events in the Matomo database

When you want to easily extract RAW data from your website visitors and app users, all the information you will need is accessible from the Matomo database and you sometimes may want to query it using SQL. In this FAQ you will find a list of SQL queries you can easily re-use.

Matomo Database Schema documentation

When using SQL to query your analytics data, you may want to learn more about the database schema and the meaning of various columns: read the Matomo Database Schema reference doc to learn more.

The SQL queries below will read a lot of data at once and use significant memory on the database, especially if your Matomo collects a lot of data.

SQL query to select all visits and actions (during a certain time period)

Run this standard SQL query to extract from Matomo all of the raw data and (all rows and all columns) for all visits and all their interactions on all your websites. In this example we extract all value from the first 14 days of May by using the column visit_last_action_time:

SELECT *
FROM matomo_log_visit 
LEFT JOIN matomo_log_link_visit_action ON matomo_log_visit.idvisit = matomo_log_link_visit_action.idvisit 
LEFT JOIN matomo_log_action ON matomo_log_action.idaction = matomo_log_link_visit_action.idaction_url 
LEFT JOIN matomo_log_conversion ON matomo_log_visit.idvisit = matomo_log_conversion.idvisit 
    LEFT JOIN matomo_log_conversion_item ON matomo_log_visit.idvisit = matomo_log_conversion_item.idvisit
WHERE visit_last_action_time >= '2022-05-01' 
AND visit_last_action_time < '2022-05-15';

SQL query to select all visits and actions for a specific website ID

All the data in Matomo tables is separated for each website by using the column idsite (website ID):

    SELECT *
    FROM matomo_log_visit
    LEFT JOIN matomo_log_link_visit_action ON matomo_log_visit.idvisit = matomo_log_link_visit_action.idvisit
    LEFT JOIN matomo_log_action ON matomo_log_action.idaction = matomo_log_link_visit_action.idaction_url
    LEFT JOIN matomo_log_conversion ON matomo_log_visit.idvisit = matomo_log_conversion.idvisit
    LEFT JOIN matomo_log_conversion_item ON matomo_log_visit.idvisit = matomo_log_conversion_item.idvisit
    WHERE idsite = X;

SQL query to select the list of all site searches

Select all visit actions where the action type is 8, indicating site searches:

    SELECT matomo_log_visit.idvisit, 
           server_time, 
           matomo_log_action.name as search, 
           matomo_log_link_visit_action.custom_var_v5 as searchresults 
    FROM matomo_log_visit 
    LEFT JOIN matomo_log_link_visit_action ON( matomo_log_visit.idvisit = matomo_log_link_visit_action.idvisit ) 
    LEFT JOIN matomo_log_action ON( matomo_log_action.idaction = matomo_log_link_visit_action.idaction_name )
    WHERE type = 8
    ORDER BY idvisit, server_time;

SQL query to select all actions where an Event action contains a specific string

Run the following SQL query to select all Events, where the “Event action” matches a certain string (in this example my-event-action-to-delete):

    SELECT *
    FROM matomo_log_link_visit_action llva 
    JOIN matomo_log_action as la  
    WHERE llva.idaction_event_action = la.idaction  
    AND la.name LIKE '%search%';

SQL query to select all Event names, where the Event action contains ‘search’

    SELECT llva.*, la_names.*
    FROM matomo_log_link_visit_action llva
    JOIN matomo_log_action as la
    JOIN matomo_log_action as la_names
    WHERE llva.idaction_event_action = la.idaction
    AND llva.idaction_name = la_names.idaction
    AND la.name LIKE '%search%'
    AND idsite = X;

    /*You can additionally add two more AND statements to only query a specific timeframe:*/
    /*This will only work in MySQL versions lower than MySQL 8*/
    AND server_time >= '2021-03-01'
    AND server_time < '2021-03-29'

More resources and SQL tips

See also the following links:

• Selecting IP addresses in SQL.
• Select users within a range of IP addresses.
• Deleting visits with SQL queries.
• Matomo Database Schema reference guide.

Exporting RAW visitors and actions data via the HTTPS API (Alternative)

You can also alternatively export all this RAW data using our HTTPs API, so you don’t have to use SQL queries. The API used to export all your Raw data is called Live.getLastVisitsDetails and lets you export all the user and clickstream data for a given website and a given date: Learn more.

How do I force Matomo to use SSL (https) for improved security?

Configuring Matomo (Piwik) so that all requests are made over SSL (https://) is an easy way to improve security and keep your data safer. To ensure that logins, passwords and the token_auth are not sent in the clear, you can manually set a config file setting.

Important Note: Enabling SSL (https://) in Matomo without first ensuring that you can load Matomo over SSL may cause Matomo to not be accessible.

First ensure that you can load Matomo over SSL by replacing http:// with https:// and testing to see if the page can load. For example: https://yourserver.com/matomo/index.php or https://matomo.yourserver.com

We also recommend you use a valid SSL certificate. If you use NGINX web server, you likely need to add the following line to your nginx config: fastcgi_param HTTPS $https if_not_empty;.

• Once you have confirmed that you can load Matomo over SSL, install the plugin ForceSSL from the Marketplace. Learn more about how to install a plugin in Matomo.
• Or alternatively, you can also edit your config/config.ini.php file, and add the following under the [General] section, set the following:

  [General]
  force_ssl = 1
  

Matomo will then automatically redirect all http:// requests to route to the https:// equivalent. Learn more tips about how to secure Matomo.

If for some reasons you need to disable the “Force SSL” feature, simply remove force_ssl=1 from your config.ini.php file.

How to track error pages (404 pages) in Matomo? Which URLs are 404 and which referrers lead to these pages?

Pages regularly appear and disappear on websites, other websites might link to wrong URLs on your website, etc. You can track with Matomo (Piwik) which URLs are leading to a 404, and which referrer pages link to 404 on your website.

• Setup a custom 404 page: you can easily do this if you use a CMS (for example, in wordpress, all 404 pages are loading a custom 404 template). If you don’t use a Content Management System, you can usually specify a 404 custom page in your webserver configuration file.
• Add the Matomo tracking code in this custom 404 page. In the Javascript tracking code, add the following:

  _paq.push(['setDocumentTitle',  '404/URL = ' +  encodeURIComponent(document.location.pathname+document.location.search) + '/From = ' + encodeURIComponent(document.referrer)]);
  

before the line

_paq.push(['trackPageView']);

• In your Matomo report, in Behavior > Pages Titles, you will now have a new entry for the 404 pages. It will also list the full URL of the 404 pages, as well as all referrers leading to this page. Enjoy!

To get advanced reporting about your 404 error pages, you may want to consider the Custom Reports premium feature which lets you create a new report for 404 error pages. It lets you analyze the 404 reports faster and gives you more insights.

How do I track visits on my intranet?

Matomo (Piwik) can track visits on your intranet website as long as Matomo itself can be accessed by people in your intranet network.

What is different between a normal website and an intranet website? When tracking visits in an intranet website, Matomo assumes that many people will possibly visit the intranet website pages using a similar configuration (For example, similar computers, similar phones, similar IP addresses), and Matomo will use first party cookies to more accurately define how a unique visitor is identified.

To make sure that all unique visitors are tracked correctly in your intranet, there are a few choices:

1) Instead of creating a “Website” in Matomo, create an “Intranet” website. Go to Administration > Measurables > Manage, and click “Add a new measurable”, and select “Intranet Website”. (if you are not seeing the ‘Intranet’ option, please make sure you use at least Matomo 3.6.1 and that the plugin ‘IntranetMeasurable’ is activated).

2) Or you may also use the ‘User ID’ feature to assign your users with a unique persistent User ID string. This will make sure your users are tracked accurately across all devices. Learn more in User ID guide.

If you have already created a website in Matomo and want to convert it to an Intranet website, you can make your website an intranet by running the following query:

UPDATE `site` SET type = 'intranet' WHERE idsite = XYZ

(Replace XYZ by the website ID you want to change to an Intranet).

How do I get accurate geolocation for people viewing my Intranet site? When many people viewing your website share the same IP address (for example because they’re connecting via a VPN or from within your intranet network), then to still track geolocation for these we recommend using this third party plugin from the Marketplace IntranetGeoIP plugin.

How do I know which version of Matomo I am using?

• Go to Matomo On-Premise
• Go to Matomo for WordPress
• Go to Matomo Cloud

Matomo On-Premise

• Log in to your Matomo as a super user
• Click on the cog icon in the top right to get to the administration area
• The system summary widget should show you the installed Matomo version

Matomo for WordPress

This applies if you are using our WordPress plugin to host your Matomo. It does not apply if you are only using the WP-Matomo WordPress integration.

• Log in to your WordPress admin dashboard as an admin
• In the left menu click on “Plugins => Installed Plugins”
• Locate the row that is showing the Matomo plugin
• You should see the version number in the middle

Please note that Matomo for WordPress 1.X includes Matomo On-Premise 3.X while all future versions of the plugin the major version number matches the Matomo On-Premise version number. Meaning Matomo for WordPress 4.X include Matomo On-Premise 4.X.

More details

You can also find the detailed version numbers in the Matomo System Report. It will show you exactly which version number of Matomo for WordPress and Matomo On-Premise is being used.

Matomo Cloud

Matomo Cloud users are usually on the latest available Matomo version. Unsure if you are using Matomo Cloud? This usually applies if the login URL to your Matomo contains .matomo.cloud or .innocraft.cloud.

How do I generate fake data (generate visits, actions, conversions, etc.) in Matomo?

When you are testing Matomo (Piwik) it may be useful to generate test data. Learn how to generate test data in Matomo in this post using the VisitorGenerator plugin.

How do I accurately measure the time spent by visitors on my pages, including the time spent on the last page of their visit? (using the heart beat timer)

By default, Matomo (Piwik) will accurately track the time spent on all your pages, except the last page view of the visit, as Matomo counts the “Time spent on page” as 0 seconds by default.

When your visitor views only one page in the website, the “Visit” duration will be set to a default of 10 seconds (The “Time spent on page” will still be tracked as 0 seconds).

-> It is possible to configure Matomo to track the time spent in the visit accurately (the “Visit duration” metric), and including the time spent in the last page view of each visit.

Learn more about Accurately measuring the time spent on each page in the JavaScript Tracking code guide.

How do I automatically login my users in Matomo when they go from my CMS to Matomo?

Some Matomo (Piwik) users automatically provide their CMS customers with Matomo statistics. If you want to provide a one-click automatic login to Matomo for your users, you can use the ‘logme’ mechanism, and pass their login & the md5 string of their password in the URL parameters:

https://stats.example.org/index.php?module=Login&action=logme&login=your_login&password=your_MD5_password

This will securely login the user (create a cookie in their browser) and redirect to the index.php on successful login. Note that this authentication method doesn’t work for a user with Super User access.
You can also specify the URL to redirect after a successful login, if different from the default Matomo dashboard page:

https://stats.example.org/index.php?module=Login&action=logme&login=your_login&password=your_MD5_pwd&url=http://piwik.mycompany.com/subpath/

You can also specify a website ID (idSite) that will be loaded by default after the redirect:

https://stats.example.org/index.php?module=Login&action=logme&login=your_login&password=your_MD5_pwd&idSite=145

Important: we recommend to make this request over https (SSL) in order to keep the password hash secure, and we also recommend to POST the password and login URL parameters (instead of sending it as GET parameters, which may be visible in browser history and web server access logs).

Since version 3.0 Matomo does not store the password as md5 any longer. As a result there is no way to access the md5 hashed password using the API. To generate the md5 password, you need the user’s raw password and then call the md5() hash function on this raw password using your favorite programming language.

How do I ask for user consent before using tracking cookies and/or measuring user analytics?

By default Matomo tracks users (visits and actions) without consent.

If you need to ask for consent, follow the steps in Asking for user consent to activate Matomo Analytics tracking. For example you may want to ask for consent before enabling tracking cookies, or ask for consent before tracking session recordings or before activating any tracking in Matomo.

You can also configure Matomo cookieless to avoid cookie consent.

fyi: in the future we may create more documentation about integrating with an existing consent manager tool.

How do I customise the colors, fonts, font sizes of the Opt-out iframe so it matches my website design and styles?

As part of respecting your users privacy, we recommend to include the Matomo Opt-out iframe in your website. This lets your users easily opt-out of being tracked in your Matomo instance. When you include the opt-out ifame in your website, by default the opt-out feature will use the default browser HTML styles (display black text on white background with the default font), and unfortunately this default design does not look nice for most websites.

Luckily it is possible to customise the look and feel of the opt-out iframe on your website. To customise the opt-out iframe, go to Matomo > Administration > Privacy, and navigate to the section “Matomo opt-out for your visitors”. You are able to customise the font-color, the background color, the font size and the font family. To customise the opt-iframe you can use the following URL parameters:

• backgroundColor, a hexadecimal color string for example ffffff or ddd
• fontColor, a hexadecimal color string for example ffffff or ddd
• fontSize, a valid CSS font size for example 1.2em, 15pt, 15px or 50%
• fontFamily, a string containing only letters, space, or hyphen eg. Lucida, Courier new
• language, the language of the opt-out text, a two letter code eg. en or de (see the list of all languages or get involved)

In cases where you need to customise even more aspects of the opt-out form (for example change the opt-out text itself) you can implement a custom visitor opt-out form using JavaScript.

How do I enable users to login into Matomo inside an iframe?

By default, the Matomo login screen will not load in iframe, as a security measure to prevent clickjacking. You can manually enable Matomo login screen to work from inside an iframe. However it is not recommended for security reasons. Learn more in this FAQ (the INI setting is enable_framed_pages).

Instead of loading the login screen in an iframe, you might want to use the logme() method to automatically log your users in Matomo remotely instead.

How do I log in to my account when I cannot verify my account using two-factor authentication because I don’t have access to my mobile device

As part of the two-factor authentication set up, you’ll need to download or copy a set of recovery codes which you can use when you lose your mobile device, or when you simply cannot access the device to generate the authentication code.

Please treat your recovery codes with the same level of security as you would your password. We recommend saving them for example in a password manager.

Using a two-factor authentication recovery code

Use one of your recovery codes to automatically regain entry into your account. You may have saved your recovery codes to a password manager

• Type your username and password to prompt authentication.
• The “Two-factor authentication” screen will show the Authentication code field.
• Enter your two-factor recovery code in the Authentication code field.
• Click “Verify” button.

Once successfully logged in, proceed to set up two-factor authentication on your new device.

Each recovery-code will only work once, so we also recommend to delete the used recovery code from your password manager.

When you don’t have access to your mobile device or your recovery codes

As soon as you have used all recovery-codes, you won’t be able to log in anymore. If you have used a few recovery-codes, you may want to generate new recovery-codes by going to “Administration => User Settings => Show recovery codes”.

If you have no access to your mobile device anymore but you still have access to recovery code, use the steps above to set up two-factor authentication on another device (each recovery-code will only work once so it’s important to not use this technique often)

If you have no access to your mobile device and no recovery codes, you need to contact a user with super user access and ask them to reset your two-factor authentication for you. A user with super user access can do this by going to “Administration => Users”, and then clicking on “Edit” your user.

If you are a super user yourself and are unable to log in, you can disable two-factor authentication through the command line

$ ./console twofactorauth:disable-2fa-for-user --login=yourlogin

or if you use Matomo on our Cloud, please get in touch with our support.

How do I White Label Matomo, to change the Logo, the Colors, add custom widgets, etc.

To customise your Matomo (Piwik) experience, you have a few options:

1. Browse the Themes Marketplace and install use one of the free themes offered by the community.
2. As a Super User, go to Matomo, click Administration, and in “Settings” you can customise the Logo displayed in Matomo, as well as customise the Favicon icon.
3. For even more control and customisation: develop your own custom theme for Matomo
4. To remove the Matomo branding from the application, use the White Label Analytics plugin.

Contact us for more information about offering a white labelled fully serviced Analytics platform.

How do I include Matomo reports within an Iframe?

For security reasons, including Matomo (Piwik) in an iframe first require you make small change to your config/config.ini.php file: see this FAQ.

How do I specify the URL that users should be redirected to, when they logout of Matomo?

By default when user logs out he is redirected to the Login form. In your config/config.ini.php you can add under the [General] category the option:

login_logout_url="http://example.org/page"

When the user logs out, he will be redirected to this URL instead.

How do I delete all statistics for a given website, or for all websites?

It is possible to keep all the websites information (names, defined goals, etc.) and only delete the stored analytics data. There is not currently a tool available to delete all data automatically, but you can manually delete all data for a specific website directly within the database server.

Connect to your Mysql database storing your Matomo (Piwik) data with your favorite database client (for example phpMyadmin) and do the following:

• To delete statistics data for all websites, run the following query for each matomo_archive_* table:

  DROP TABLE matomo_archive_numeric_Y, matomo_archive_blob_Y;
  

• To delete statistics data for a given website, run the following query for each matomo_archive_* table:

  DELETE FROM matomo_archive_numeric_Y, matomo_archive_blob_Y WHERE idsite = X;
  

The archive tables will automatically be re-created from the Visitor logs when Matomo processes your reports (assuming you do not purge your old visitor log data).

• To delete log data for a given website, execute the following query:

  DELETE FROM matomo_log_visit WHERE idsite = X;
  DELETE FROM matomo_log_link_visit_action WHERE idsite = X; 
  DELETE FROM matomo_log_conversion WHERE idsite = X; 
  DELETE FROM matomo_log_conversion_item WHERE idsite = X;
  

with X replaced by the website ID you wish to reset.

The alternative solution is to use the Delete old reports and Delete old tracking data features, click to see the FAQ.

If you want to delete Visitor log data (and not Report data) then read this FAQ: How do I delete old visitors statistics for a given website and/or date?

How do I configure my Matomo server to allow cross domain requests? (CORS)

Matomo is an analytics platform that collects data (Tracking API) and reports (Analytics API) this data in interesting formats. Sometimes you want to query this data from across other domains for example using cross-domain Ajax calls (XMLHttpRequest).

By default browsers implement the same-origin policy which prevents browsers from directly requesting data from other domains. Luckily, modern web browsers allow developers to perform cross-domain requests with one trick: the server must allow cross-domain requests by responding to the request with the Access-Control-Allow-Origin header set to a value that includes the domain of the requesting code, for example Access-Control-Allow-Origin: https://example.com. You can also set the header to * to match and allow all domains.

You can set your domain names for CORS in the Matomo GUI, the feature can be found in Administration > System > General settings

Alternatively you can set the domains in the config.ini.php file. To allow your Matomo to serve data to all domains add the following to your config file:

[General]
cors_domains[] = *

To allow Matomo to serve cross-domain requests to only example.com and dashboard.example.com

[General]
cors_domains[] = "http://example.com"
cors_domains[] = "http://dashboard.example.com"

Reference: Cross-origin resource sharing.

If you are using the Heatmaps and Session Recordings plugin you may also need to add Access-Control-Allow-Origin: * to your websites configuration (The websites where you are installing the Matomo tracking code) in order to allow Matomo to access the specific resources required for the Heatmaps and Session Recordings plugin.

How do I migrate a particular website in Matomo to a different Matomo installation?

To move a website (and its data) to a new Matomo instance, you can use the Migration plugin.

After you migrated a website’s data from one Matomo instance to another, please remember to update the Tracking codes in your website and ensure that they reference the correct Matomo URL and the correct Website ID.

Migrating data from one Matomo to another is very helpful in several use cases:

• When your Matomo instance includes websites from different customers and you want to move one customer’s web analytics data in its own Matomo instance. You can setup a new Matomo instance for this customer and then migrate their website’s data over to this new Matomo instance. Then you can delete their data from your Matomo instance.
• When you currently have multiple Matomo instances running and want to consolidate them into one main Matomo instance (eg. for easier maintenance). You can migrate all your websites data from your multiple instances into your chosen main Matomo instance, by running the Migration tool on each Matomo you want to migrate. Once all your websites data from your other instances is migrated and after you have updated all Tracking codes to reference the new instance URL and website ID, you could uninstall these other Matomo instances.

See also: How can I move all of Matomo data from one server to another?

How do I set some of my website directories or pages to not be tracked?

If you wish to set some specific pages or directories to not be tracked by Matomo (Piwik), we recommend that you modify the Matomo Javascript Tracking code, and replace

_paq.push(['trackPageView']);

by a small if statement to test whether the current page must be tracked or not.
To exclude traffic for all page URLs which contain /admin or which contain user/private, write:

if (!window.location.pathname.match(/(\/admin|user\/private)/))
{
_paq.push(['trackPageView']);
}

In this example, all URLs except the ones containing “/admin” or “user/private” will be tracked by Matomo.

If you are not using the JavaScript tracker but you are using the Server Log Analytics capability, then you can exclude particular log lines from being imported by adding the parameter --exclude-path= such as python misc/log-analytics/import_logs.py --exclude-path=*/exclude/* --exclude-path=*/also-exclude/* [...]

How do I measure my single-page websites and apps with Matomo?

Single-page websites and web applications have become a standard over the last years. Getting the tracking of such websites and apps right is crucial to your success as you need to ensure the measured data is meaningful and correct. It can be challenging to accurately measure single-page applications and we have documented this process in our article: How to track single-page websites and web applications using Matomo Analytics (formerly Piwik Analytics).

How do I export data from Matomo in CSV or XML or JSON format?

To export data from Matomo, simply follow the steps below:

1. Select the date range you want to export data for by clicking on the calendar icon.
2. Open the report you would like to export data from.
3. Hover the report with your mouse: icons will appear in the footer below the report.
4. Click on the “Export this dataset in other formats” icon in the footer of the report: 
5. Choose your export format (CSV, JSON, XML, RSS, HTML), report type (Standard or Metadata report), the report row limit, and click the “Export” button to download your report data.

Alternatively you can directly call the Reporting API as documented in the Reporting API Reference.

How do I delete rows of a report and specific visits to clean-up some of the reporting data?

Sometimes you may see unwanted data in your Matomo reports. For example you may see in “Behavior > Events” some un-wanted or incorrecly named events. Or in “Acquisition > Campaigns” you may see campaigns that are not real campaigns or were incorrectly named. When this occurs and you want to clean up this data, it is possible to delete some the affected rows within your reports, by deleting the visits which created these data points in the first place. To delete specific parts of a report, follow the steps below:

• Login to Matomo as “Super User”
• Click on “Administration (cog icon)” on the top right of the dashboard
• Click on “Privacy > GDPR Tools”
• Select a website from the dropdown, which you want to delete the data from
• Choose the appropriate condition under “Find data subjects by”. For example if you wanted to delete incorrect rows from your reports in “Acquisition > Campaigns” you would select “Campaign > Name” is “THE-INCORRECT-CAMPAIGN-NAME”
• Click on “Find Matching Data”
• Select the rows you want to delete
• Click on “Delete Selected Visits”

Once you have deleted the visits which led to the incorrect data in your reports, within a few hours Matomo will automatically re-process the historical data reports. After the re-processing of reports is complete, the reports will not show the incorrect data anymore.

Note: this works only when you still have access to the RAW visits details for the time period which you wan to correct data for (ie. when you haven’t yet deleted old tracking data).

How do I restrict viewing the analytics reports to one or more allowed IP addresses or IP ranges?

For additional security and preventing un-authorized IP addresses from accessing Matomo (Piwik) dashboards, you can configure a set of allowed IP addresses. Since Matomo 3.6 you can also configure hostnames. However, please consider that any hostname will be resolved within each request. This may slightly slow down your Matomo.

IP addresses can be allowlisted by adding them under your [General] section in config/config.ini.php:

login_allowlist_ip[] = 204.93.240.1
login_allowlist_ip[] = 204.93.240.*
login_allowlist_ip[] = 204.93.177.0/24
login_allowlist_ip[] = 2001:db8::/48
login_allowlist_ip[] = matomo.org

When configured, only users from a configured IP address can log into your Matomo. You can define one or multiple ; IPv4, IPv6, and IP ranges.

By default, if a allowlisted IP address is specified via login_allowlist_ip[] then both the reporting user interface as well as HTTP Reporting API requests will only work for these allowlisted IPs. But in some cases you need to allow all IP addresses access to your Matomo HTTP Reporting API endpoint. To allow all IP addresses to access the Matomo Reporting API, set in your config file under [General]:

login_allowlist_apply_to_reporting_api_requests = 0

When allowlisted IP addresses are configured and you try to access Matomo but your IP is not allowed, you will see an error like this: “You cannot use this Matomo as your IP 1.2.3.4 is not allowlisted”.

See also: How do I exclude traffic from an IP or a range of IP addresses?

How do I delete old visitors statistics for a given website and/or date?

Sometimes, you may need to delete some or all Visits log data for a given date, and/or a given website. For example if you have imported log files incorrectly in Matomo (Piwik) you may want to delete the invalid data that was imported.

Delete visits using the UI

As part of the GDPR Privacy features in Matomo, you can easily delete visits. Learn more in the FAQ How do I delete rows of a report and specific visits to clean-up some of the reporting data? and in the guide: GDPR Guide “Right to erasure”.

Delete visits using a console command

A console command lets you delete all visits log data (including Visits, Actions, Goal conversions, Ecommerce activity).

To use this console command, login to your server (using SSH) and go in the Matomo directory. Execute the following command to display the help:

./console help core:delete-logs-data

The following options are available:

• --dates lets you delete log data with a date within this date range. Eg, 2012-01-01,2013-01-01
• --idsite lets you delete log data belonging to the site with this ID. Comma separated list of website id. Eg, 1, 2, 3, etc. By default log data from all sites is purged.
• --limit lets you pick the number of rows to delete at a time. The larger the number, the more time is spent deleting logs, and the less progress will be printed to the screen. (default: 1000)

For example to delete all log data for month of January 2015 on website ID 42, execute:

./console core:delete-logs-data --dates=2015-01-01,2015-02-01 --idsite=42

Notes
* all the visits log data for the given date range and website ID will be permanently deleted.
* When a date range is entered (comma separated), the time will be set to the beginning of the day (midnight UTC) so for example using --dates=2015-01-01,2015-01-02 will delete all the data only for the 1st of January 2015 (in UTC timezone).
* The core:delete-logs-data command uses UTC when deleting log data, so you will need to adjust the command depending on the time zone that your website uses. To delete the data for a specific day for a website that is UTC +4 for example, you will use the following --dates parameter to delete data for the specific day of 1 January 2015 (in UTC+4 in this example): --dates="2014-12-31 20:00:00,2015-01-01 20:00:00"
* this console command does not delete your archived report data but only delete the raw visits log data.

Delete visits using SQL query

Run the following SQL query to delete visits matching a certain criteria, for example here we delete all visits where the screen resolution wasn’t tracked properly in the date range 2019 May 1st-May 16th:

DELETE log_visit, log_link_visit_action, log_conversion, log_conversion_item 
FROM log_visit 
LEFT JOIN log_link_visit_action ON log_visit.idvisit = log_link_visit_action.idvisit 
LEFT JOIN log_action ON log_action.idaction = log_link_visit_action.idaction_url 
LEFT JOIN log_conversion ON log_visit.idvisit = log_conversion.idvisit 
    LEFT JOIN matomo_log_conversion_item ON log_visit.idvisit = log_conversion_item.idvisit
WHERE config_resolution = 'unknown' 
AND visit_last_action_time >= '2019-05-01' 
AND visit_last_action_time <= '2019-05-16';

or delete all data for a given website:

    DELETE log_visit, log_link_visit_action, log_conversion, log_conversion_item
    FROM log_visit
    LEFT JOIN log_link_visit_action ON log_visit.idvisit = log_link_visit_action.idvisit
    LEFT JOIN log_action ON log_action.idaction = log_link_visit_action.idaction_url
    LEFT JOIN log_conversion ON log_visit.idvisit = log_conversion.idvisit
    LEFT JOIN log_conversion_item ON log_visit.idvisit = log_conversion_item.idvisit
    WHERE log_visit.idsite = X;

Delete actions (pageviews, events…) using a SQL query

Run the following SQL query to delete all actions, in this example all Events, where the “Event action” matches a certain string (in this example my-event-action-to-delete:

    DELETE llva.* 
    FROM matomo_log_link_visit_action llva 
    JOIN matomo_log_action as la  
    WHERE llva.idaction_event_action = la.idaction  
    AND la.name LIKE '%my-event-action-to-delete%';

Or for example, if you tracked in the past some custom events with some bogus data (say an event value that is too large), then you can delete the bogus event actions by running the following SQL queries:

    # First, check the data that will be deleted
    SELECT * FROM matomo_log_link_visit_action WHERE custom_float >= 99999999
    # Then delete the data
    DELETE * FROM matomo_log_link_visit_action WHERE custom_float >= 99999999

Or for example to delete any site searches tracked before a certain date (type = 8 is for site searches, see DB schema reference and TYPE_SITE_SEARCH for other action types):

    DELETE matomo_log_action 
    FROM matomo_log_link_visit_action 
      LEFT JOIN matomo_log_action ON idaction_name=idaction 
    WHERE type=8
      AND server_time < "2020-06-01";

Related FAQs

If you want to configure Matomo to automatically purge your old data (whether visits log data, or statistics reports data), see this FAQ How do I delete historical Matomo data? (purge old logs and/or old processed reports)

If you want to delete old reports, read this FAQ: How do I delete all statistics for a given website, or for all websites?

How do I remove tracking data tracked from specific IPs?

Deleting tracking data for specific visits using a Visitor IP can be done using our GDPR Tools

How your Matomo is configured to anonymise tracking data will determine how easy it will be to delete previously tracked data using a visitor IP.

Determine the IP address you need to search

If you are not anonymising the Visitor IP

Then you can use the GDPR tools to remove the tracking data using the full IP address for example 192.168.100.10, with the steps listed below.

If you are anonymising the Visitor IP in Matomo

First, determine how many bytes of the IP address are being anonymised in the Matomo privacy configuration.
Then replace the corresponding numbers in the IP address you want to delete tracking data for with 0.
For example if you need to delete tracking data for the IP address of 192.168.100.10, then you would replace 2 bytes of the IP address as follows: 192.168.0.0.

Deleting the tracked data

You can do this by following these steps:
1. Go to Admin > Privacy > GDPR Tools
2. Select the website that you want to remove the data for using the Site Selector.
3. Under “Find data subjects by” select Visitor IP Equals 192.x.x.x (Replace this with the IP you would like to lookup)
4. You will then be presented with a list of all visits that match the search criteria. By default all of the visits that match the search criteria will be selected, if there are any visits you wish to keep you can deselect them
5. Scroll to the bottom of the page and click “Delete Selected Visits”

Just keep in mind that the more bytes anonymised by Matomo, the higher the likelihood of deleting tracking data for legitimate visits.

Once the tracking data has been deleted, you will need to invalidate the reports and reprocess the data to get accurate reports for any time periods that these visits occurred in. These reports will become available again once the archiving process has completed.

Related FAQs

If you want to delete old tracking data for specific date ranges for any of your sites in Matomo using this FAQ: How do I delete old visitors statistics for a given website and/or date?

If you want to delete old reports, read this FAQ: How do I delete all statistics for a given website, or for all websites?

How do I get reports for a custom date range?

Matomo (Piwik) reports on days, weeks, months and years, and you can also specify a Custom Date Range in the Calendar. Click on the calendar, then on “Date Range”. Now select on the left calendar the starting date for the range, and in the right calendar the end date of the range. Matomo will process in real time the reports for the requested date range.

In the Analytics API, you can also get reports for a custom date range. For example, to request any report for the range “Feb 15th – Feb 25th”, you would use the parameters:

&period=range&date=2011-02-15,2011-02-25

How do I see how long ago was a report generated?

When viewing reports for Today, or This week, or This month, or This year, the reports you are looking at were processed some time ago: for example the reports for “Today” were maybe processed a minute earlier or they could be several hours old. How often reports are processed is configurable in Matomo. It is often important to know how fresh (or stale) the data you’re looking at can be.

To see how long ago was a given report generated, open (for example) the report under Visitors > Devices, and hover your mouse on the first report title. A help icon with a question mark will be displayed, and when you click on this icon it will show the help box. At the bottom of this help box you can see when the report was processed:

Note: the text Report generated 28 min 31s ago is only displayed when the date range you’re looking at include “Today”.

How do I search within reports?

Most data table reports have a small search bar below the report. Here you can type data and press Enter key to search for this string within the report displayed above. For example, in the “Keywords” report, you can search for nature and it would return all keywords matching nature.

The search field is actually a Regular Expressions. For example, a search for nature|life would match all rows containing nature or life. All search strings containing any of the special characters from this list: . + * ? [ ] $ ( ) { } = ! | must be escaped with a back slash, eg. if you want to search for keywords containing love! you would search for love\!.

Advanced tip: if you want to find all rows in the report that do not include a particular sub-string or in other words: to hide and exclude all rows that match a particlar sub-string such as brand, you would use the following regular expression: ^((?!brand).)*$

How do I accurately measure the same visitor across multiple domain names (cross domain linking)?

Cross domain tracking makes it possible for Matomo (Piwik) to record the same visitor on two related websites, for example an Ecommerce website and a separate shopping cart website, as a single visit.

Why is setting up cross domain needed for accurate visitor tracking across domains? Matomo uses a visitor ID to record visit data. Visitor ID values are stored in cookies on the web domain of the visit. These cookies are first party cookie and can only be accessed on the specific domain name that they were created, so other domain names cannot access these cookies and the visitor ID. So when you need to track your visitors across different domains, the visitor ID must be forwarded from one domain to the other domain using a special mechanism which we call Cross domain linking, described in detail below.

To setup accurate cross domain tracking, follow these steps:

1. Configure your domain names as Alias URLs for your Matomo website. Login to Matomo and click on Administration > Websites > Manage. Edit your website, and specify all your domain names in the Alias URLs field. There must be two or more domains for cross domain to work.
2. Generate your JavaScript tracker code. In Administration > Websites > Tracking Code, click on “Advanced: Show” link, then check the option “Enable Cross Domain linking” (If this checkbox is not clickable, please check you have defined at least two Alias URLs for this website). This will also automatically check the box “In the ‘Outlinks’ report, hide clicks to known alias URLs”.
3. Check your generated JavaScript tracker code is valid. In the generated Tracking code in Matomo you should see the following two lines:

   _paq.push(["setDomains", ["*.domain1.com", "*.domain2.com"]]);
   _paq.push(["enableCrossDomainLinking"]);
   

Please note that cross domain linking won’t work when cookies are disabled.

1. Paste this JavaScript tracker code into all your websites to be measured across domains. In the example above, you need to add the JavaScript tracker code to domain1.com and domain2.com. It is important to add the code to all your domains specified as Alias URLs on your Matomo website.
2. Check that the Cross Domain linking is working correctly. Go to your domain1.com and click on a link to your domain2.com. If Cross Domain linking is enabled and working, the URL of domain2.com will contain a new parameter &pk_vid=. This pk_vid parameter will contain a string of data which includes the Visitor ID. This way the current visitor ID is forwarded to the page of the different domain. Similarly when a user clicks from domain2.com to domain1.com, the domain1.com URL will also have this new pk_vid parameter.

You have successfully configured Cross Domain linking: congratulations!

Advanced: Handling Dynamically Generated Links

Note: the feature below is available since Matomo 3.3.1.

The cross domain detection feature works by adding the pk_vid query parameter to every link on the page when it is loaded. This is only done once, so if your webpage or webapp adds links dynamically to the page through JavaScript, they will not have this query parameter added to the URLs.

This doesn’t mean cross domain detection for such links is impossible, but it does mean you’ll have to do a little more work.

First, in your JavaScript that generates the link, get the pk_vid=... query parameter to use by calling the Matomo tracker’s getCrossDomainLinkingUrlParameter method:

var crossDomainQueryParam;
_paq.push([ function() { crossDomainQueryParam = this.getCrossDomainLinkingUrlParameter(); }]);

Then make sure this value is appended to the link URL:

// NOTE: this example uses jquery, which you may not use in your website/webapp.
//       how you add the query parameter will depend on how your link is generated.
var $linkToAdd = $('<a>my new link</a>')
    .attr('href', 'http://myotherdomain.example.com/page.html?' + crossDomainQueryParam);

$('body').append($linkToAdd);

Notes:

• You can add the query parameter to the link at any time, as long as it is added before it is clicked/visited.
• You need to append the query parameter to all links on domain1.com going to domain2.com, and on all links on domain2.com linking to domain1.com (see the list item 5. above: “Check that the Cross Domain linking is working correctly.”).

Goal funnel conversion across multiple domains

When you enable cross-domain tracking using the instructions above, you’ll be able to track your conversion funnels and funnel steps across your multiple domains.

A/B tests across domains

When running an A/B test, you can only run it on one domain. It won’t work to run an A/B test on multiple domains (because the A/B test variations are stored in the local storage or first party cookies on the domain, and are not shared across domains).

However you can still use cross-domain tracking with A/B testing when for example you run a A/B test on one of the domains, and on another domain you trigger Goal conversions. The A/B test will be able to use these cross-domain goal conversions into account in the calculation of the A/B test’s success metrics.

Cross-domain tracking and Roll-Ups

When you create a Roll-Up and aggregate several websites together, it is not possible to use cross-domain tracking. Cross-domain tracking only works within one Website in Matomo (one Website having multiple domain names).

How do I segment people that have been identified using cookies vs fingerprint?

If you are enabling cookies on demand depending on whether a visitor has given you cookie consent or rejected cookie consent (see our Asking for Consent developer guide), then you may want to use a segment to get separate reports for these two different groups.

This is useful because disabling cookies impact Matomo’s report accuracy. Having segments for each group means you don’t mix less accurate data and accurate data when analysing for example the number of unique visitors or acquisition channels.

To view all reports only for people that have given cookie consent or where cookies were used to identify the visitor over a longer period create a segment based on the “Profilable” segment:

To view all reports only for people that have not given cookie consent or where cookies were not used (eg because cookies were disabled in the visitor’s browser) create the segment like this:

Please note that this feature requires at least Matomo 4.

How do I change the default email address “From:” in PDF/HTML email reports and other emails sent by Matomo?

You can edit the default noreply@yourdomain.com email address that will appear in the PDF reports emails and all other emails sent by Matomo by editing the configuration file config/config.ini.php, and adding under the

[General]

section, the following line:

noreply_email_address = "info@example.org"

All reports by email will now be sent from “info@example.org”

Please note: Changing this setting will change the email address used for all emails sent by Matomo.

How do I change the default email address “From:” in password reset emails?

Matomo will use the configured no-reply email address for password reset emails.

You can however change the “reply-to” email address and name that will be used by Matomo when sending a password reset email.

This can be done by editing the configuration file in the config/config.ini.php, and adding under the

[General]

section, the following two lines:

login_password_recovery_replyto_email_address = "no-reply@yourdomain.com"
login_password_recovery_replyto_email_name = "No-reply"

How do I import Google Analytics data in Matomo?

In 2019 we released the Google Analytics data importer so you can import all your historical web analytics reports from GA into Matomo easily.

It is important to plan your migration from Google Analytics to Matomo

When you start to import Google Analytics data into Matomo, a new website will be created within Matomo automatically to import the data from Google Analytics. The import can not go into an existing website in Matomo. For example, if you have been testing Matomo and tracking your website into a website already, then this data can’t be merged with the imported data from Google Analytics (which will be into a newly created website). So only after you have setup data migration, then you will be able to track your website visitors to this newly created website, while the historical Google Analytics data is importing (which can take several days).

Recommended steps for migrating from Google Analytics

1. Make sure you use the latest version of Matomo and the Google Analytics importer plugin.
   If you use Matomo Cloud, the plugin is installed by default. If you self-host Matomo, you can install the plugin in a few clicks.
2. Setup Google Analytics import in Matomo
   Follow the steps in the user guide “Import Google Analytics data” to get started. Follow the “Setup” steps to a) Creating Google OAuth Client Config and b) Authorizing Matomo.
3. Schedule the Google Analytics import to run
   For more details please see the section “Running the Google Analytics import” of the above guide.
4. Proceed to embed the Matomo tracking code into your website
   Now that the new website has been created for the import, then you can use the Matomo JavaScript tracking code for this newly created website.
5. Check that your website is now tracked in Matomo correctly
   Check you can see your own visits and other visitors in real-time (if you are not seeing data, use this faq).
6. Update the Import Job and set the “End Date” to today’s date
   Then the data will stop importing now that you are tracking the data in Matomo directly. If you don’t do this step, the data will keep importing from GA and may cause conflicts with the data now being tracked in Matomo.
7. Double check that you have implemented Matomo tracking correctly
   Are all your Goals conversions still working and tracking data as expected? Are your custom dimensions also tracking as expected?

Congratulations for migrating your Google Analytics data, and having full control over your websites’ visitors’ data!

Final steps to remove Google Analytics

Once you’ve confirmed that everything is reported as expected in Matomo:

1. You may remove your Google Analytics tracking codes from your website. This will stop the collection of your visitors data by Google as well as slightly increase the page load speed.
2. (Optional) after a few months or a year, once you’ve confident about using Matomo, you may also delete the property from your Google Analytics account.
3. (Optional) once you have migrated all your properties to Matomo, you may also delete your Google Analytics account.

Thank you for taking these steps towards more privacy and take control of your data.

How do I track a Phonegap app with Matomo?

To measure your Phonegap app with Matomo (Piwik), you can include the default JavaScript Tracking code in your app pages. Then you will need to make one change to the default Tracking code:

• Locate the line: var u="//{$MATOMO_URL}";,
• Replace it with the following: var u="https://{$MATOMO_URL}";. Note that http: or https: is pre-pended in front of your Matomo URL.

Congratulations: your Phonegap app users will be correctly tracked in Matomo.

How do I force Matomo to only track Page URLs that belong to my website?

For example when you have a website with a URL of “example.com”, by default Matomo (Piwik) will track all requests for this website, even those requests for Page URLs that do not belong to “example.com”. If you add the JavaScript tracking code on pages of “another-website.com”, these requests will be tracked in your website “example.com” in Matomo.

It is possible to configure your website in Matomo so that only requests to “example.com” will be tracked, and all other requests ignored. Go to Administration(cog icon) > Websites > Manage > click “Edit”. Below the “URLs” field for your website, there is a checkbox “Only track visits and actions when the action URL starts with one of the above URLs.”. If you click this checkbox, and click “Save”, Matomo will then only track requests where the domain and the path is an exact match of one of the URLs you specified for this website. This means each valid subdomain has to be specified separately. For example when the known URLs are ‘http://example.com/path’ and ‘http://good.example.com’, tracking requests for ‘http://example.com/otherpath’ and ‘http://bad.example.com’ are ignored.

How do I send Matomo emails using SMTP server? (for example using Gmail SMTP)

You can configure Matomo to use your SMTP server as the mailserver (instead of using the default mailserver that PHP is configured to use).

To configure a SMTP server for Matomo, login as Super User, go to Administration > System > General Settings. Under ‘Email server settings’ you may configure the SMTP server form as follows:

• Use SMTP server for e-mail. For Gmail SMTP use YES
• SMTP server address. For Gmail SMTP use smtp.gmail.com
• SMTP Port. For Gmail SMTP use 465
• Authentication method for SMTP. For Gmail SMTP use Login
• SMTP username. For Gmail SMTP use your gmail username
• SMTP password. For Gmail SMTP use your gmail password
• SMTP encryption. For Gmail SMTP use SSL

Also you may need to go in to Gmail and enable the option “Allow Less Secure Apps” here. Stay assured Matomo is still secure.

If you have enabled 2 step verification (2FA/MFA) with Gmail, you will need to set up a password in Gmail specifically for use in Matomo. It’s done in the “App passwords” section of your Gmail account. Then enter this generated “App password” in Matomo > Settings > Email server settings > SMTP password.

All Matomo emails (Scheduled PDF Reports, Password reset confirmation, etc.) will now be sent using Gmail servers.

Some of the Page URLs are tracked in duplicate (for example both “Default.aspx” and “default.aspx” are tracked as different pages), how do I force Matomo to record them as the same custom url?

If in your Page URLs report you are seeing the same page URL appear under different entries, then you can use the setCustomUrl command which lets you overwrite the default Page URL by your custom URL for one or several pages.

This may be useful if for example you’re seeing the same page appear under “index.html” and/or “index” and/or “/”. You could detect this case in JavaScript in your website and call _paq.push(['setCustomUrl', "/index.html"]); to track all these pages under the same URL “index.html” in Matomo.

Or if for example you are seeing both “Default.aspx” and “DEFAULT.aspx” and you want to track them as “default.aspx”. In your Matomo Javascript Tracking tag, you can add the following line:

_paq.push(['setCustomUrl', location.href.toLowerCase()]);

just before the line:

_paq.push(['trackPageView']);

Then all your pages will now be tracked as lowercase, eg. “Default.aspx” or “DEFAULT.aspx” will be tracked as “default.aspx”.

If instead of the Javascript Tracker you are using the import_logs.py Log Analytics tool, then you can pass the following option to the import_logs.py script:

--force-lowercase-path

How do I set a custom URL using the Matomo Javascript tracker?

Often when tracking pages in a mobile app or when a webpage URL contains arbitrary information, it becomes necessary to set the URL that Matomo tracks in order to ensure the reports generated are accurate and usable.

This can be done using the Matomo JavaScript tracking with the following code:

_paq.push(['setCustomUrl', 'https://yourdomain.com/your-new-page-url']);

As you can see from the example above, we need to specify the full URL of the page.
Simply setting the custom URL to something such as /your-new-page-url will not work.

How do I track the URL Hash tags so that the #hash appears in the Page URLs report, and in Visitor Log?

By default Matomo (Piwik) will remove the #hashtag part of the URL to keep your reports clean. However it is common that you wish to record the hash tags as they may contain interesting and relevant information.

To track URL hash tags (enable/disable) login as Super User, click on “Administration” and on “Websites”.

• In the “Global websites settings” section, below the “Page URL fragments tracking” title, you can enable Hash tags tracking by enabling the checkbox “Keep Page URL fragments when tracking Page URLs”. This setting will be applied to all websites.
• You may also enable/disable Hashtags tracking for each individual website. In the listing of Websites, click “Edit”. In the column “URLs”, below the help notice, you will find a checkbox “Keep Page URL fragments when tracking Page URLs”, which lets you set your preference for websites.

Note:
* URL Hash Tags are only tracked when the user loaded the Page and the URL contained a hash tag. If the user loads example.html and then clicks on an anchor link to example.html#contact within this same page, Matomo will not track this click as a new page view.
* When #hashtags tracking is disabled, tracking Campaign parameters via the hash tag will still work as expected.

How do I track my RSS/Atom feed subscribers?

Until Oct 2012, Matomo (Piwik) was relying on Feedburner and the ‘Awareness API’ to provide RSS. It used to provide the following information:

• Reach: Reach is the total number of people who have taken action — viewed or clicked — on the content in your feed.
• Circulation: Circulation is an approximate measure of the number of users who requested your feed. This is the “Readership count”.
• Hits: Hits are a raw measure of request traffic for your feed. This metric includes automated bots requests, visitors viewing the feed but not subscribing, etc.

Unfortunately, Feedburner now owned by Google decided to shut down permanently their API. Feed Analytics could be done within Matomo and if you are interested in this project, you can leave a comment in this ticket.

How do I momentarily disable Matomo User Interface and/or Matomo visitor Tracking?

Before a Database upgrade on a high traffic Matomo (Piwik) server, it is highly recommended to:

Disable Matomo Tracking

In the config/config.ini.php, add the following

[Tracker]
record_statistics = 0

This will cause all Matomo Tracking API requests (to matomo.php or piwik.php) to return quickly the response and status code 204, without connecting to the database or doing any processing. Requests for configs.php for Heatmaps & Session Recordings will still return a status code 200.

Disable the Matomo User Interface and APIs

To disable the User Interface and the APIs, but still track all of your data correctly, you can enable maintenance mode.

When maintenance_mode is on, a maintenance message instead of the standard Matomo reporting interface. Your data is still tracked as expected, but the UI and the Reporting APIs are disabled.

If you run the Matomo Database Upgrade script using the shell/console command, we highly recommend to turn Matomo off while the upgrade is in process. Disabling the Matomo User Interface will prevent other users from accessing Matomo while the Database upgrade is in process.

To do so, add the following in the config file:

[General]
maintenance_mode = 1

If the line [General] already exists, add the line maintenance_mode = 1 below the line [General].

The following XML messages will be returned by the API:

<result><error message="Matomo is in scheduled maintenance. Please come back later. "/></result>

The Reporting API endpoint index.php will return an http error status code 503 (Service unavailable) while it is in maintenance mode.

Re-enable Tracking API and UI

When the Matomo update is finished, do not forget to re-enable Visit Tracking and/or the User Interface.

And if you need to recover any missing data that wasn’t tracked during the maintenance window, learn more in about replay the traffic to Matomo and ingest logs of piwik.php requests

How do I disable all automated emails so that Matomo doesn’t send any email?

If you wanted to disable all emails from a particular Matomo instance (for example when you restore a database dump in a new test instance), you can edit your config.ini.php and set the following setting under the [General] section:

emails_enabled = 0

This is useful when you’re restoring a database dump that has other people’s email addresses, and you don’t want to send them any emails from the test instance.

How do I enable “Unique Visitors” metric for Yearly reports and for Custom Date Ranges?

The “Unique Visitors” metric (as well as the “Users” metric) can be found under “Visitors > Overview” in Matomo.
​
If you’re using Self-hosted Matomo, by default unique visitors metric KPI is processed for days, weeks and months. If you’re using the Matomo Cloud service, unique visitors metric KPI is processed for days and weeks only.

About the “Unique Visitors” column you can see in some reports: when you view a “Day” report, you can also find a “Unique Visitors” column in most reports. For example the number of unique visitors who reached your website from a specific Website Referrer, or the number of unique visitors who use a particular device or browser. This “Unique Visitors” column is only available in “Day” reports and unfortunately it cannot be added in the Week/Month/Year/Custom Date Range reports.

But if you are looking at getting the overall “Unique Visitors” metric (or unique “Users” metric) for Years and Custom Date Ranges, this can be enabled on request. (By default for performance reasons the “Visitors > Overview > Unique Visitors / Users” metrics are disabled because the SQL query to process unique visitors/users is quite costly and take minutes to run on a High traffic Matomo server.)

Note: This document below is written in an assumption that you’re using On-Premise Matomo, if you have any question regarding availability of Unique Visitors or Unique Users metric in Matomo Cloud, please contact our Support team.

You can decide to enable or disable the unique visitors metric for specific periods by adding the following in your config/config.ini.php:

[General]
enable_processing_unique_visitors_day = 1
enable_processing_unique_visitors_week = 1
enable_processing_unique_visitors_month = 1
enable_processing_unique_visitors_year = 0
enable_processing_unique_visitors_range = 0

By default, unique visitors are processed for days, weeks and months (they are set to 1). You can for example enable yearly unique visitors by setting enable_processing_unique_visitors_year = 1

Important notes:

• processing the Unique Visitors metrics is using the Matomo (Piwik) logs. This requires that the feature “Delete old logs” is not used on your Matomo server.
• after enabling these settings in your configuration file you will need to force Matomo to re-process your historical data as explained in this FAQ.

More information about unique visitors

The number of unique visitors across the month is processed by calculating the number of distinct visitors looking at the logs for the whole month.

When you select a date range, by default there is no unique visitors metric processed by default. And if you sum up the daily unique visitors metric you will not get the total unique visitors across the date range: this is because one visitor may visit the website on several days, and when you sum a number of uniques per day you will end up counting the same visitor multiple times. Therefore to get the number of unique visitors accurately across a date range period, you cannot sum the number of uniques for the sub-periods within and must enable this feature.

How do I enforce tracking without cookies

To prevent cookies from ever being used log in as a super user, go to “Administration -> Privacy -> Anonymize data” and enable the checkbox “Force tracking without cookies”. Enabling this option will automatically update the JavaScript tracker to ensure all trackers won’t use cookies. Additionally, Matomo will ignore all received tracking cookies on the server side.

Cookies will be disabled even when using the consent methods in Matomo tracker and calling for example the cookie consent methods won’t enable cookies.

This setting will affect all sites. If you want to disable cookies for specific sites only you may need to use the according javascript tracker methods.

This feature requires Matomo 4 or newer.

How do I disable the visits log or the visitor profile feature?

For privacy compliance you can disable some features that show every action a visitor took (raw data) in the user interface and API. You can easily disable these features by following below steps.

If you are using Matomo On-Premise 4 (or newer), Matomo for WordPress 4 (or newer) or Matomo Cloud

• Log in as a super user
• Go to “Administration -> General settings”
• In the “Live” section you can either disable visitor profile feature only or the visits log and the visitor profile
• Confirm the changes by clicking on “Save”.

Note that for example disabling the visits log also disables related features that are built on top of this such as the segmented visits log, the real time map and the real time widget.

The feature can be enabled again any time.

If you are using Matomo On-Premise 3 or earlier

• Log in as a super user
• Go to “Administration -> Plugins”
• Deactivate the “Live” plugin

Should you change your mind you can simply activate this feature again.

How do I setup Matomo to track multiple websites without revealing the Matomo server URL footprint which appears in the Javascript code in all websites?

By default, the Matomo (Piwik) Javascript code on all tracked websites contains the Matomo server URL. This is fine for most users, but someone (eg. a competitor) could run a script that would look at thousands or millions of websites and search for your Matomo server URL in the source code of these websites. This person could then find out all websites tracked in your Matomo instance. In some cases you might want to hide this Matomo URL completely while still tracking all websites in your Matomo instance. It is possible to do by modifying your Matomo Javascript code, and point it to a “proxy piwik.php script” instead of your Matomo server URL. This piwik.php script has to be uploaded on each of the websites tracked, and will automatically “forward” all requests to your secret Matomo server.

• All documentation on how to install this script is at matomo-org/tracker-proxy.
• Follow the instructions carefully and you will then have all your websites tracked without revealing your common Matomo URL, ensuring that nobody can find out the websites tracked by Matomo!

Note: this proxy technique also supports the Opt-out feature to exclude visits via the ignore cookie. You may also be interested in White label plugin for Matomo to provide a customised Matomo colors and product name to your clients.

How do I enable basic JavaScript error tracking and reporting in Matomo? (browser console error messages)

Matomo offers a basic feature for tracking JavaScript errors that occur on your website or web app. It will track errors that occur in JavaScript and would be displayed in users’ browser developer tools console.

To enable this feature, you can add the following line to your JavaScript tracking code:

_paq.push(['enableJSErrorTracking']);

Once you enable JS error tracking, JS errors will be tracked as Events and appear in the Behavior > Events report. Events will have the following details:

• Event category = JavaScript Errors
• Event action = the URL of the page where the error occured, with the line number appended (and the character column number)
• Event name = the error message as it appears in your visitors’ browser’s console (developer tools)

So when you open the Event Names report, you can click on the error message to see the page URL(s) on which the error occurred.

Notes:

• currently the stack trace is not recorded, which makes it sometimes harder to troubleshoot.
• the same error will be only tracked once per page view. If the very same error is happening multiple times, then it will be tracked only once within the same page view. If another page view is tracked or when the page reloads, then the error will be tracked again.
• when you enable this feature it will start tracking errors as events. If you already use Events for other purposes, these new error events might somehow “pollute” your Event reports and add noise. As a workaround, you may create Custom reports to filter out the “JavaScript Errors” events if needed.

How do I get the number of active unique users to my app?

Matomo (Piwik) measures your users and their interactions with your website or app. In order to accurately measure the number of known and active unique users to your app, you can use the User ID feature which will let you assign User ID string to each of your signed-in users. When this User ID is assigned then Matomo will calculate a new metric called “Users” which is the number of unique users who used your app in the selected time period. This metric is reported in Visitors > Overview report and will also appear in the VisitsSummary.get API response under nb_users metric (more info). This metric represents the number of unique active users (visitors with a known User ID). Learn more in the User ID guide. This metric is enabled only for some periods, and this can be configured (FAQ).

How do I set up Matomo offline tracking?

The Matomo JS tracker supports tracking users while they are offline and executing the tracking requests as soon as they come online. This can be for example useful in progressive web apps (PWA). To make use of this feature follow below steps.

Step 1. Create a file for the service worker

If you don’t have a service worker yet, then you need to create a file for your service worker in the root directory of your website. In below example we assume the file is called service-worker.js.

Step 2. Register service worker

If you have not registered a service worker yet, register your service worker like this in your website:

if ('serviceWorker' in navigator) {
    window.addEventListener('load', function() {
       // adjust `service-worker.js` to match the file name of your worker
        navigator.serviceWorker.register('https://static.matomo.org/service-worker.js'); 
    });
}

Every page where you want to utilise offline tracking needs to include this snippet.

Step 3. Initialise offline tracking

Within your service worker (for example in your service-worker.js) add this code:

// replace `https://your.matomo.domain` with the domain and path to your Matomo installation
self.importScripts('https://your.matomo.domain/offline-service-worker.js');
matomoAnalytics.initialize();

The method initialize supports currently these options:

• queueLimit: Defaults to 50 and defines how many requests will be queued max while a user is offline. If more requests than the configured limit are queued, the oldest requests will be removed.
• timeLimit: Defaults to 86400 seconds (1 day) and specifies after how many seconds the tracking requests should be disregarded if the user does not come online. This is set to 1 day because the Matomo tracker API requires authentication should you try to record a tracking request for more than a day in the past. If you want to keep the requests for more than one day, you will need to change this setting and also configure the time after which Matomo tracking requests require authentication.

Example:

matomoAnalytics.initialize({queueLimit: 100, timeLimit: 86400*2});

Known limitations

So far only our standard tracking endpoints are supported: matomo.js, piwik.js, matomo.php and piwik.php. If you are using a custom path like tracker.js and tracker.php this is not supported yet.

This feature requires Matomo 4. It is currently available as part of our latest Matomo 4 beta release see our FAQ on how to update your Matomo to the latest beta release.

We need your feedback

Running into any issues?

We’d love to hear your feedback if this feature is working for you or not. Simply leave a comment on the offline tracking issue if this is working for you.

If you run into any issues using this feature please let us know in our GitHub issues tracker.

Are you a service worker or IndexedDB pro?

We’d love if you could help us review our implementation. You can check out the code in the offline tracking pull request. We appreciate any feedback to help us improve this feature!

How do I see page performance reports?

Matomo will automatically try to track performance data for each page view when using the Matomo JavaScript tracker. The reports contain the following metrics:

• Network time (connectEnd – fetchStart)
  How long it takes to connect to server. This includes the time needed to lookup DNS and establish a TCP connection. This value might be 0 after the first request to a domain as the browser might cache the connection.
• Server time (responseStart – requestStart)
  How long it takes the server to generate page. This is the time between the server receiving the request and start serving the response.
• Transfer time (responseEnd – responseStart)
  How long it takes the browser to download the response from the server.
• DOM Processing time (domInteractive – domLoading)
  How long the browser spends loading the webpage until the user can start interacting with it.
• DOM Interactive time (domComplete – domInteractive)
  How long it takes for the browser to load images/videos and execute any Javascript code listening for the DOMContentLoaded event.
• On load time (loadEventEnd – loadEventStart)
  How long it takes the browser to execute Javascript code waiting for the window.load event (when the DOM was completely rendered).
• Page load time
  How long it takes to load the whole page, from requesting a page until it is fully rendered within the browser. This is the sum of all previous metrics.

An overview of the average values of those metrics across all pages can be found on the “Behaviour -> Performance” report.

Performance metrics for each page can be found on the same page.

When moving the mouse over a specific row there is a row action available to open the following page performance report for a single page:

This feature requires Matomo 4 or newer.

How do I enable third party tracking cookies, as well as the existing first party cookies?

For Privacy reasons, Matomo does not use 3rd party cookies by default (only first party cookies, which can be easily disabled).

In some cases, it might be interesting to enable third party cookies, so that a same visitor will get the same ID across all your domains and subdomains. Matomo (Piwik) doesn’t report cross sites visits at this stage, so you will benefit from using third party cookies only if you run manual queries against Matomo database. To enable 3rd party cookies, edit your config/config.ini.php and add the following lines:

[Tracker]
use_third_party_id_cookie = 1

When this is enabled, Matomo tracker will serve a third party cookie containing an id visitor (16 chars ID). This ID will be the same for this visitor across all websites, and is stored in the database field log_visit.idvisitor.

Enabling third party cookies would typically require user consent.

See also: How does Matomo detect unique and returning visitors? (with User ID, Visitor ID from cookie and/or fingerprint)

How do I track a website within an iframe

Matomo can track a website within an iframe out of the box just like any other website. In some browsers there may be issues when cookies are enabled (Matomo might create a new visit on every page view). To make cookies work it is recommended to add the following snippet to your tracking code:

_paq.push(['setCookieSameSite', 'None']);

Please note that this requires your traffic to be on HTTPS. If you have mixed traffic on HTTP and HTTPS it might lead to duplicate or incomplete visits.

This feature requires Matomo 4 or newer.

How do I customize the Matomo Campaign parameters pk_campaign and pk_kwd?

By default, tracking campaigns in Matomo (Piwik) involves adding the required parameter pk_campaign (and optional parameter pk_kwd) to the URLs pointing to your website. Matomo also supports Google Analytics campaign parameters (utm_*).

Here is a comma delimited list of default parameter names that Matomo will read:

 campaign name parameters: mtm_campaign, matomo_campaign, pk_campaign, piwik_campaign, utm_campaign, utm_source, utm_medium
 campaign keyword parameters: mtm_kwd, mtm_keyword, pk_kwd, piwik_kwd, pk_keyword, utm_term

It is also possible to customize these parameter names. For example, we would like to use the parameters names “campaign” (instead of pk_campaign) and “keyword” (instead of pk_kwd). To do so, there are two required steps:

• 1) Override the parameters in the config file. In your config/config.ini.php, add the following:

  [Tracker]
  campaign_var_name="campaign"
  campaign_keyword_var_name="keyword"
  

Note: you may specify a comma separated list of campaign parameter names, in case you wanted Matomo to read the campaign name or value from several possible parameters. The first non empty value will be used.

• 2) Customize the parameters in the Javascript. In the Javascript snippet on all your pages, add the following before the trackPageView() call:

  _paq.push(['setCampaignNameKey', 'campaign']);
  _paq.push(['setCampaignKeywordKey', 'keyword']);
  

Notes:

• these two functions also accept an array of strings. If an array of names is specified, the first non empty campaign or keyword parameter value will be selected.
• the Campaign parameters can be used in the query string or in the hash as well (for cleaner canonical URLs), such as: “landing.html#pk_campaign=my campaign”
• to measure more than campaign name and keyword and up to five campaign dimensions, as well as support other standard UTM campaign tags, use the free plugin MarketingCampaignsReporting
• to find out the true value and success of all of your marketing campaigns, we recommend using the Multi Channel Conversion Attribution premium feature.

You may also be interested in creating an affiliate system with Matomo to track new customers and revenue from affiliates.

How do I configure outgoing (forward) proxy in Matomo (eg. squid)?

It is possible to configure a forward outgoing proxy in Matomo (Piwik), so that all outbound Internet connections (eg. to check for new versions of Matomo, for SEO plugin, Plugin updates, etc.) go through the proxy. Check the FAQ Configure Outgoing proxy for more details.

How do I exclude / ignore my traffic or specific users from being tracked in Matomo?

There are a few ways to tell Matomo (Piwik) to exclude and ignore your traffic:

• Set the ‘ignore cookie’: Login in Matomo, click “Administration” in the top menu, then in the ‘Personal > Settings’ page click the link below the section ‘Exclude your visits using a cookie’. (a matomo_ignore cookie without expiry date is created on the domain of your Matomo server).
• You may also ignore all traffic from a given IP address or IP address range or CIDR range (useful if you use one or more static IP addresses): check this faq.
• You may also exclude all traffic where the requests have particular User Agents.
• You may also include a Tracking Opt-out feature in your website, and use it to exclude your traffic. (a matomo_ignore cookie without expiry date is created on the domain of your Matomo server).
• You may also force Matomo to only track visits and Page URLs where the URL belongs to your website domain (useful to ignore traffic on your test/staging/qa instances)
• You may also define specific requests to be excluded (advanced users only)
• Aternatively, you may also avoid tracking one or more users that meet your specific criteria by implementing logic yourself in Javascript (or server-side) to hide the tracking code. So that when user(s) meet the criteria and should be excluded from tracking, then your code would ensure to not display the JavaScript Tracking code in your pages or apps. When the tracking code is not output in the page for some users, then these users won’t be tracked.

Note: when you exclude some traffic, it will only exclude it going forward and is not applied retroactively.

If you wanted to delete data that is already tracked, see the FAQ How do I delete specific visits to clean-up some of the data?

How do I use Matomo with the keyboard and which keyboard shortcuts are available?

The following keyboard shortcuts can be used to navigate the Matomo Analytics (formerly Piwik Analytics) user interface using your keyboard:

• z for Zen mode (Zen mode lets you focus and removes all distractions from the UI)
• s to open the Segment selector
• w to open Website selector
• d to open Calendar (d stands for Date)
• f to open the Search (f stands for Find)

If you use the User Session Recording product, you can conveniently pause the video, jump a few seconds backwards or forwards, replay the video if it is finished, or play the next or previous page view for the visitor: view the keyboard shortcuts for Session Recording.

I forgot my password or username, how do I reset my password?

To reset your password in Matomo (Piwik), go to Matomo: below the login screen you will find a link “Lost your password?”. After clicking the link, enter your Matomo username or Email address, and enter your new password (twice). A link to confirm your password reset will be sent to your email address.

Note: for security reasons, it is not possible to recover passwords, but only change them. We highly recommend to use a strong password and to enable automatic SSL for login screen in your Matomo server.

See also the other FAQ: How do I change the Super User’s password when password recovery emails are not sent?

How do I share a custom dashboard template with another user?

If you have spent time creating custom dashboards, you may find that you want to share them with other members of your team or organisation. Sharing Custom Dashboards can provide your team with a central point of reference. It can also enable people from outside your team to easily review your team’s progress against key performance indicators.

How to Share Custom Dashboards With Other Users

Sharing Custom Dashboards is easy as long as you have Super User permissions within your Matomo instance. To share a dashboard that you have access to, follow the step by step instructions below.

1. Login to Matomo as a user with Admin or Super User Permissions.
2. Access the Custom Dashboard you want to share via the Main Navigation under the Dashboard menu item. 
3. Click the Dashboard menu button within the data selector section at the top of the page to load the Dashboard Menu. 
4. Within the Manage dashboard section of the menu, click the Copy dashboard to user link to launch the dashboard sharing popup. 
5. Select the Username you wish to receive the dashboard and click OK.

Once confirmed, the user you selected will now have access to your dashboard template and your exact set of widgets and layout.

Note: If you delete your original dashboard, it will only delete your own dashboard. The dashboards that we copied to other users will still be accessible to them.

More Resources

• Tour of Matomo Interface
• Guide to Creating Custom Dashboards

What is the default widgets selection in a dashboard, and how do I update the default dashboard layout?

The default widgets selection is the combinations of widgets and layout which are used for all new users as their default dashboard. As long as a user hasn’t customised their dashboard already (by adding new widgets, or changing the column layouts, or modifying widget display settings), ​​then they get the default dashboard layout.

This default widgets selection and dashboard columns layout will be also used when any user creates a new dashboard, or when “Reset dashboard” feature is used.​​

How do I update the default dashboard layout?​​

To update the default dashboard ​layout, follow these steps:

1. Login as a Super User in Matomo
2. On any of your dashboards, customise​​ the widgets and layout until you are happy with the dashboard layout.
3. Click on Dashboard selector, then click on “Set as default widgets selection”
4. Click “Yes” to validate

Congratulations, your dashboard is now the default dashboard for your Matomo users.

How do I change the Super User’s password when password recovery emails are not sent?

To change the Super User’s password when password recovery emails are not sent, follow the steps below.

If you use Matomo 3.0 or newer

1. Generate the secure password hash. On a linux server, run the following command:

   php -r 'echo password_hash(md5("changeMe"), PASSWORD_DEFAULT) . "\n";'
   

2. Copy paste the output which will look like:

   $2y$10$FiknavjTDvUUTSMXGqgmUOfoKq2MkzlYt2/iu6cj02ZyI.40fUArC
   

3. Connect to your Matomo (Piwik) database using a tool such as phpMyAdmin or direct Mysql access.
4. The following SQL query must be executed on your database. Replace the ‘admin’ with your Super User username.

   UPDATE `matomo_user` SET `password` = "$2y$10$FiknavjTDvUUTSMXGqgmUOfoKq2MkzlYt2/iu6cj02ZyI.40fUArC" WHERE `login` = 'admin' AND superuser_access = 1 
   

5. Login to Matomo using the following credentials:

   login: admin 
   password: changeMe
   

6. Click on the Administration link in the top menu, then “Personal Settings”, then change your password to a more secure one.
7. Check you are using the most up to date version of Matomo.

If you use Matomo 2.1 or newer:

1. Connect to your Matomo database using a tool such as phpMyAdmin or direct Mysql access.
2. The following SQL query must be executed on your database. Replace the ‘admin’ with your Super User username. Note that it must be replaced twice in this SQL query.

   UPDATE `matomo_user` SET `password` = MD5( 'changeMe' ), `token_auth` = MD5( CONCAT('admin', password)) WHERE `login` = 'admin' AND superuser_access = 1 
   

3. Login to Matomo using the following credentials:

   login: admin 
   password: changeMe
   

4. Click on the username link in the top menu, then change your password to a more secure one.
5. Check you are using the most up to date version of Matomo.

If you use Matomo older 2.0.3 or older:

1. In your config.ini.php, change the [superuser] section to:

   [superuser]
   login = "admin"
   password = "807ff71b3301262e222ad05e5b7c4325"
   email = "admin@example.org"
   salt = "ffd09b1b27ad925d2a3ca842947f391d"
   

2. Login to Matomo using the following credentials:

   login: admin 
   password: ChangeMe
   

3. Go to Administration -> User settings, then update your email and change the password, click Save.
4. Update Matomo to the latest version as soon as possible!

Related

See also How do I recover Super User access and give SuperUser permission to another account?

How do I recover Super User access and give SuperUser permission to another account?

Sometimes it may happen that Super User access is lost. For example maybe there was only one Super User in Matomo and this person left on holiday, left the organization, or maybe even lost access to both their email account and their Matomo password.

When Super User access is lost, we need to grant another trusted Matomo user the Super User access. You can grant Super User permission to a given account by following the steps below:

1. Connect to your MySQL database
2. Run the following SQL query and replace the ‘username-here’ with the username for which to grant Super User permission:

   UPDATE `matomo_user` SET superuser_access = 1 WHERE `login` = 'username-here'
   

3. Logout and login again as this username.
4. You can now use Matomo as a Super User.

See also How do I change the Super User’s password when password recovery emails are not sent?

How do I exclude all requests with a specific User Agent from statistics ?

Sometimes, there are non human (bots) that visit your website. These bots can have many purposes (such as security scanning, performance scanning, monitoring, search engine bot, spam bot, etc.). Often, you do not want these bots to be tracked in Matomo (Piwik), because you may want to focus on how humans use the website, and not bots. In this case, you can tell Matomo to exclude traffic where the User-Agent of these requests match a given string.

Some bots are not tracked by default

Some of the visits with a specific user-agent will be detected by Matomo as a bot, and won’t be tracked. You can test if a User-Agent is detected as a bot by going to your Matomo > Administration > Diagnostic > Device Detection. In the “User-Agent” text field, copy paste the user agent you want to check. You can also check online on devicedetector.net.

How do I exclude new bots from being tracked?

To exclude traffic for a particular User agent (or several user agents), go to “Administration”, click on “Settings” under the “Websites” (or “Measurables”) section. Below the list of websites, you will find the option to specify “Global list of user agents to exclude”. You can enter there a list of user agents to exclude from being tracked by Matomo. Put one user agent per line. If the visitor’s user agent string contains any of the strings you specify, the visitor will be excluded from Matomo. You may also toggle the checkbox “Enable website specific user agent exclusion.” to enable this feature as a new column for each website in the Websites listing.

As of Matomo 4.1.1 it is also possible to exclude useragents using a regex (e.g. /bot|spider|crawl|scanner/i).

Notes:

• when you exclude some traffic, it will only exclude it going forward and is not applied retroactively.
• make sure not to include a very short string (with few characters) as it could block more requests than you would expect.

See also: Exclude traffic from IP address or IP ranges

How do I find the visitor IP Addresses?

Matomo by default tracks the full IP address of all visitors to your site (you can anonymize this IP if you wish).

To view your visitor IP addresses:

• In the User Interface, click Visitors > Visits Log. The Visits Log will display a list of all the visits during the selected calendar period, and for each visitor will display the IP address in the left.
• you can also fetch the visit IP addresses of a given visitor, or all visitors in a selected date range, using the Matomo Analytics (formerly Piwik Analytics) Live! API.
• you may also see the Visitor IP on the Visitor Profile report.
• the raw data is also available in the database, in tables matomo_log_* See this FAQ.
• you can add the Visitor IP address to Custom Reports and get for example, the list of pages by IP addresses, or any other breakdown report by Visitor IP.

Note: in all cases, the IP address will only be displayed if you are logged in Matomo: for privacy reasons, IP addresses are never displayed to the anonymous user.

How do I select IP addresses or Visitor ID directly from the database?

In the database, the IP addresses and Visitor IDs are stored in Binary form for storage efficiency. To display these values correctly you can use the following SQL query:

SELECT INET6_NTOA(`location_ip`) as ip, conv(hex(idvisitor), 16, 16) as visitorId FROM matomo_log_visit;

If you use MySQL 5.6.2 or earlier, you will have to use this SQL query instead (which only supports IPv4):

SELECT inet_ntoa(conv(hex(location_ip), 16, 10)) as ip, conv(hex(idvisitor), 16, 16) as visitorId FROM matomo_log_visit;

To select a specific visit if you know the idvisitor you can run this SQL query:

SELECT * FROM log_visit WHERE lower(conv(hex(idvisitor), 16, 16)) = 'a43f52349c8890af';

You may also be interested in: How do I select all users within a range of IP addresses?

How do I make Matomo report data public and viewable by anyone?

By default, report data and all information in your Matomo (Piwik) server are protected and nobody can access it. To view and access any analytics data, Matomo always asks you to sign in with a valid user account.

Some Matomo users may want to make their analytics data open and viewable by anyone. For example if you run a NGO, an open governmental service, an open source project, etc. the analytics data may be of use and interest to many people in your community. By making your Matomo data and communicating that your analytics data is public, members of your community may help you analyse the data and find interesting insights to drive you to overall do better work.

Before you decide to make your analytics data public, please consult with your colleagues and team members and make sure that everyone agrees with this decision.

If you wish to make all analytics data publicly viewable for a particular website, follow these steps:

• Login to Matomo as an Administrator or a Super User
• Go to Administration > Users
• Under “Manage access”, locate the “anonymous” user
• Choose “View” from the dropdown which is on the right to the “Username”, a pop up will appear
• Click on “yes” to set the right to view the report for the chosen website

If you later want to remove public access access to your data, follow these steps:

• Under “Manage access”, locate the “anonymous” user
• Choose “No access” from the dropdown, a pop up will appear
• Click “yes” to confirm you remove the permission for the anonymous user

Note that when an anonymous user (not signed in) visits your Matomo dashboard, we do our best to protect privacy and hide from display any Personally Identifiable Information (PII):

• Visitor Profile feature is disabled for the anonymous user
• the Visitor IP address and the Visitor ID are not displayed in the UI or API responses for the anonymous user

How do I select all users within a range of IP addresses?

It is possible to segment any analytics report and restrict the data to users who have a particular IP address, or where the IP address is within a given IP range.

For example if you want to restrict your reports to users who have an IP address matching 147.28.*.* then you can create a custom segment and specify the IP range:

• If you use the Segment editor, create a segment where “Visitor IP at least 147.28.0.0” AND “Visitor IP at most 147.28.255.255”. (Note: you can only define one IP range at a time using this technique.)
• Or to create a segment excluding all users within an IP range (for example to view your Matomo (Piwik) reports excluding all your colleagues’ requests), you would create a segment where “Visitor IP is less than 147.28.0.0” OR “Visitor IP is more than 147.28.255.255”. (Note: you can only define one IP range at a time using this technique.)
• If you use the API, the segment definition will look as follows: &segment=visitIp%3E%3D147.28.0.0%3BvisitIp%3C%3D147.28.255.255 (this is the URL encoded value for segment visitIp>=147.28.0.0;visitIp<=147.28.255.255)

Instead of using segments, you can also create Custom Reports. This lets you analyze and compare the data faster without having to switch between segments and you can get totally new insights into your data.

How do I tell Matomo to invalidate the past historical reports so they can be re-processed from the logs?

There are a few cases where you need to re-process some historical data directly from the raw logs.

For example a common use case is when you use the HTTP Tracking API to manually insert visits and actions in Matomo (Piwik) in the past (via the Tracking API parameter cdt which lets you define the date and time of the page view). If you set this date to a date in the past (for example, 3 days ago) and that Matomo has already processed the statistics reports for this date, you will not see the newly added data in Matomo.

Another example is when you create Custom Reports, or Funnels, and want to see the Custom report data and Funnel data for past dates as well. It is also useful when changing settings in the config file such as reporting more than the default 500 rows.

To tell Matomo to invalidate historical aggregated data for a website (or several), a date range (or for all past data), a segment (or for all segments), there are 3 similar techniques you can use.

1) Use the InvalidateReports plugin

You can use this free plugin by InnoCraft to invalidate your historical data directly within the user interface in just one click: get the InvalidateReports plugin. If you need to often invalidate historical data, this may be the easiest solution.

2) Use a console command

Alternatively you may use the core:invalidate-report-data console commmand:

./console core:invalidate-report-data --dates=2011-10-15,2012-01-01 --sites=1,3,5

3) Use the HTTP API

You can use the API function: CoreAdminHome.invalidateArchivedReports. For example if you imported data in the past for a few specific websites on a couple different dates you could write:

?module=API&method=CoreAdminHome.invalidateArchivedReports&idSites=1,3,5&dates=2011-10-15,2012-01-01&token_auth=xyz

It is possible to invalidate and re-process a segmented report only, simply add to the URL query the segment parameter: &segment=pageUrl=@example.org/contact.

In rare cases you may want to delete reports for a particular period (one of: day, week, month, year, range): setting the &period= parameter to the API call will force Matomo to only invalidate reports of the specified period.

Notes

• Your historical data will be actually re-processed the next time auto archiving will run. The archiving will re-process the reports data for these particular dates and websites.
  You can also manually run the archive command with: ./console core:archive --force-all-websites --url=YOUR_MATOMO_URL_HERE.
  (or if you are using Matomo 3.x, run the following command: ./console core:archive --force-all-websites --force-all-periods=315576000 --force-date-last-n=1000 --url=YOUR_MATOMO_URL_HERE)
• when invalidating report for a period eg. week it automatically invalidates all periods that include this one, eg. the enclosing month and year. We say the invalidation cascades up. By default, periods that are included are not invalidated (invalidating month will not re-process the days and weeks within the month). You may also force Matomo to invalidate inner periods by setting the parameter &cascadeDown=1 (in the CoreAdminHome.invalidateArchivedReports API) or --cascade (in the core:invalidate-report-data command).

How do I improve accuracy of “Time spent on page” and “Visit duration” metrics?

By default, when a user visits only one page view during a visit, Matomo (Piwik) will assume that the visitor has spent 0 second on the website. This has a few consequences:

• when the visitor views only one page view, the “Visit duration” will be 0 second.
• when the visitor views more than one page, then the last page view of the visit will have a “Time spent on page” of 0 second.

It is possible to configure Matomo so that it accurately measures the time spent on the last page of a visit. To better measure time spent on the page, follow these instructions in the JavaScript Tracking Client guide.

How do I get the time elapsed between two actions or two events in the same visit or even across multiple visits?

Currently Matomo does not process reports showing the time elapsed during between two specific actions or pages or events.

There are workarounds and ways you can measure the time spent between two actions.

If you need to measure the time between two actions done on the same page (for example clicking two different buttons on the same page), then it may work for you to 1) track a custom Event where for example “Event category” is ‘Elapsed time’ and “Event Action” is ‘Time to click button X’ and 2) manually keep track and store in the “Event Value” the actual time you want to measure as an integer, so the elapsed time in seconds (or even in milliseconds if you want more precision). Then in Matomo > Behavior > Events, you would see all the times you’ve tracked, and for each: the sum of all elapsed times, the average elapsed time, minimum and maximum elapsed time.

If you need to measure the time spent between two actions done on separate pages or even in separate visits, it may be easier to get the data directly from the database. See our database schema guide to see the description of the database structure.. In particular you can calculate the time spent between two actions by looking in the log_link_visit_action table at the field server_time column, which contains the datetime the action was tracked in the UTC timezone. Then by getting the difference between the two rows of the two actions, you will get the time elapsed between the two.

How do I remove from Matomo the links to “Professional Services” or “Matomo Consultants”?

By default, Matomo (Piwik) may display links to “Professional services”, or “Cloud-Hosted” or “Enterprise” solutions for Matomo. These links aim to help Matomo users make the most of their analytics platform, in particular help users find professional help for Matomo when they need it, as well as learning about premium functionality.

If you provide Matomo to your own clients, maybe you do not want them to see the mentions for professional services. Here is how you can remove these commercial mentions: Login as Super User, then go to Administration > Plugins, then disable the “ProfessionalServices” plugin.

How do I anonymize previously tracked raw data (visitors, visits) to remove personal data and delete database column values?

If you have tracked personal data such as the full visitor IP, you may want to anonymize this collected data, in case you do not have consent for this data or no longer have a legitimate interest (learn more in the GDPR User guide).

Note: Data anonymization cannot be undone.

Follow these steps to start the data anonymization process

To anonymize previously tracked raw data, follow these steps:

• Login to Matomo as a Super User
• go to Administration > Privacy > Anonymize data.
• In the section “Anonymize previously tracked raw data” you can configure a one-off data anonymisation process to run on data you have tracked in the past.
• choose to anonymise data for one website, or for all websites.
• choose the start date and end date to anonymize data for
• choose which visit or action data column to anonymize.
  • Visitor IP: If enabled, for all visits during this duration the IP will be anonymized by at least 2 bytes, for example ‘192.168.xxx.xxx’. If you have currently configured to anonymize by 3 bytes, then this setting will be respected and all IPs will be anonymized by 3 bytes.
  • Location: the location will be re-evaluated based on the anonymized IP (at least 2 bytes of the IP will be anonymized).
  • User ID: when you enable this option, the User ID will be replaced by a pseudonym to avoid directly storing and displaying personally identifiable information such as an email address. In technical terms: given your User ID, Matomo will process the User ID pseudonym using a salted hash function. Note: replacing with a pseudonym is not the same as anonymisation. In GDPR terms: the User ID pseudonym still counts as personal data. The original User ID could still be identified if certain additional information is available (which only Matomo and your data processor has access to).
  • Visit columns: specify a list of database columns in scope visit that you want to unset. Each value for that column will be set to its default value. Please note that if the same column exists in scope ‘conversion’, then this column will be deleted as well
  • Action columns: specify a list of database columns in scope action that you want to unset. Each value for that column will be set to its default value.

The process may take a long time and will therefore not be executed right away.

The anonymization should typically start within one hour.

You will be able to follow the current state of the process in the bottom of the “Anonymize data” page.

With Matomo you can also always anonymize Visitor IP addresses, geo-location information (country, region, city), pseudo-anonymize User ID, or respect the Do-Not-Track user preference: Learn more in the Privacy User guide.

How do I integrate Matomo with my existing tools and services?

You can integrate Matomo within many different platforms: CMS, Ecommerce, Forums, Websites, Programming languages, SDK, etc. Learn more in the list of Matomo Integrations.

How do I anonymize the referrer information?

Matomo stores from which URL (referrer) a user comes to your site. In some cases such a URL may contain information that can be considered personal information. For example a visitor might come from an ad or social network and the referrer URL might include various IDs that could identify an individual when the information is being cross referenced. Anonymizing will help prevent storing personal information that would be otherwise out of your control since you cannot control through which referrers your visitors find you and therefore you can otherwise not ensure that no personal information is being tracked.

If you want to prevent such information to be tracked, you can restrict the amount of referrer data that Matomo will store when a visitor enters your website. The more information is removed from the referrer information, the less likely personal information will be recorded. The more information you remove from the referrer, the less clear it will be how a visitor came to your website.

To anonymize the referrer follow these steps:

• Login to Matomo as a Super User
• go to Administration > Privacy > Anonymize data.
• In the section “Anonymize referrer” you can configure how much you want to anonymize the referrer

There are four options available:

• Don't anonymize the referrer. This is the default and does not anonymize anything.
• Remove query parameters from referrer URL. This will remove all URL parameters from the referrer URL. If for example the URL is https://ads.example.com/path/1/?adid=123456 then the stored referrer URL will be https://ads.example.com/path/1/. If the referrer comes from a search engine, then the searched keyword will not be stored as a result of this. This does however not affect imported keywords from the Search Engine Keywords plugin.
• Keep only the domain of a referrer URL. This will remove all URL parameters and the entire path from the referrer URL. If for example the URL is https://ads.example.com/path/1/?adid=123456 then the stored referrer URL will be https://ads.example.com/. If the referrer comes from a search engine, then the searched keyword will not be stored. This does however not affect imported keywords from the Search Engine Keywords plugin. Note that the entire domain (including subdomain) will still be stored and the subdomain itself could include personal information allowing someone to identify an individual. By removing the path it is less likely to store personal information since eg some ad networks may include IDs as part of the path. However, it will make it more hard to find out from which page exactly someone found you.
• Don't record the referrer URL but still detect the type of referrer. With this setting Matomo will still detect the type of referrer (eg search vs social vs website vs direct) and it also keeps the name of which search engine or social network was used to find you. However, no URL and no keywords that were used to find you will be stored. This is the safest choice should you want to prevent the tracking of any personal information.

Matomo campaigns are not impacted by any of these settings as the campaign information is provided by the currently viewed URL and not the referrer URL. This means campaign information will always be reported (also when specifically tracking a campaign info through HTTP API tracking parameters such as _rcn).

This feature requires Matomo 4 or newer.

How do I improve the detection accuracy of Unique visitors and Returning visitors?

If you import your server logs in Matomo (Piwik), you may have noticed that in this case Matomo does not track Unique Visitors as well as when using the Javascript tracker. You can configure Matomo to improve the detection of “Returning Visitors” and unique visitors.

By default, when trying to match visitors using a fingerprint (for example when cookies are not available), Matomo looks back only in the past 30 minutes (more details). We do this for performance reasons: to keep Matomo tracking fast, even if you track hundreds of thousands or millions of unique visitors per month.

For example, to configure Matomo to lookup a visitor up to 30 days in the past, you would need to set the setting to 30*86400 = 2592000 seconds under the [Tracker] section of your config/config.ini.php file:

[Tracker]
window_look_back_for_visitor = 2592000

Note that increasing the value of this setting may have negative performance impacts on your Tracking API requests speed.

If you do not use Log Import but use JavaScript tracker or another client, you can still improve the tracking of unique visitors and unique devices. See this FAQ for more information: How do I get the number of active unique users to my app?

How do I edit my username, or the username of another user?

Unfortunately in Matomo a user cannot edit their usernames. However there is an easy solution.

Follow these steps to create a new user with the correct username:

• Login as Super User in Matomo, or ask a Super User to follow these steps for you.
• Go to Administration​ ​​> Users.
• Change the email address for your current user (the one with the wrong username). For example change it to “example@example.com”.
• Create a new user with the right username.
• Assign this new user the same permissions as the old user.
• Save the changes.
• Then delete the old user.
  ​
  Now you can use the new user with the correct username!

How do I display more than the default 15 websites in the website selector?

By default, the website selector displays at most 15 websites / apps. The search box displayed at the top of the website selector lets you search for your other websites. It is possible to customise this and display more websites in the selector. Edit your config/config.ini.php file and below the category [General] change the following setting (in this example to display 30 websites):

site_selector_max_sites = 30

How do I see all user interactions in Visitor profiles and Visits log (not just the first 100)?

In Visitor profiles and Visits Log, by default Matomo will show the first 100 interactions in each visit, and may then display the message “more pages by this visitor are not displayed”. All interactions are tracked for all visits, but the UI doesn’t display the interactions by default to keep the reports fast.

You can configure Matomo to display more pages in Visitor Profiles and Visits log by updating the config/config.ini.php and setting the following INI setting under the [General] section, for example to show up to 250 actions per visit:

 [General]
 visitor_log_maximum_actions_per_visit = 250

How do I get the number of products left in the cart by each Visitor?

You may have a scenario where you may want to find the list of products left in the cart by a visitor, Matomo makes it simple with Ecommerce Analytics, User ID tracking and Custom Reports.

1) Track Ecommerce interactions

Follow our Ecommerce Analytics user guide for steps on tracking your ecommerce orders and product purchases.

2) Tracking a User ID for your customers:

Firstly in order to get the list of Customers, you need a way to generate and/or assign a unique persistent ID to each of your users, and then you need to send this User ID along with the data being collected by Matomo. Learn more in the User ID user guide.

3) Once you are tracking a User ID for your customers, create the custom report by following the steps below:

1. Click on “Custom Reports” > “Manage Reports”
2. Click on “Create new report”

3. Name and describe the report as desired
4. Under “Dimensions”, add “User ID”, “Number of Items in cart”

5. Under “Metrics”, add desired metrics
6. Click on “Create new report” (it will take 1 or 2 hours to process the report)
7. Choose the newly created report under “Custom Reports”

How do I change the default language of the Matomo UI for all user accounts?

By default, Matomo user interface may appear in English for all users who login to Matomo Analytics. Each user can choose their preferred language in their User Settings. But what if you want to change it for all users at once?

You can easily change and set a new default language for the Matomo user interface. To change the default language of Matomo, edit your config/config.ini.php file and add a new line under your [General] section:

default_language = de

This example sets the default language to German. Here is the list of supported language codes.

How do I create new visit on demand, so that several users using the same computer or browser are counted separately?

Matomo (Piwik) tries to guess visitors and unique visitors using several elaborate techniques (User ID, first party UUID cookie, heuristics matching user settings, using an optional third party cookie, etc.). If several people use the same system or browser, Matomo might count them all as one visitor. If you want to track a user’s request across multiple devices (laptop, smartphone, tablet) then you must use the User ID feature.

To create a new visit on demand you can use the &new_visit=1 parameter in the Tracking API (see Reference docs).

When you are using the Javascript tracker, you can also create new visits on demand. In your website in Javascript, whenever a user logs in the system (or whenever there is a need to create a new visit) you may write the following (before and after the trackPageView call):

_paq.push(['appendToTrackingUrl', 'new_visit=1']); // forces a new visit 

// the two lines must be above the call to track* function
_paq.push(["trackPageView"]);

_paq.push(['appendToTrackingUrl', '']); // do not force a new visit anymore (only do it once)

When the page loads and the page view is tracked, a new visit will be created in Matomo.

Notes

• this code should only be displayed once after the user has logged in; if you leave this code in all the page views, it would create a new visit for each page view and make your Matomo reports much less useful.
• See also How do I create new visit whenever a user visits my website using a new campaign or a new website referrer?
• See also How is a visit defined?

How do I create new visit whenever a user visits my website using a new campaign or a new website referrer?

Matomo (Piwik) tracks users on your websites or apps, and will group actions of a same user into a visit. Here are some rules which are applied to assign actions to visit:

• By default, Matomo will track in a visit all actions done by a visitor within 30 minutes of the last visitor’s action. See this FAQ to learn how to configure this 30 minutes delay.
• By default Matomo will create a new visit whenever a visitor views your website using a different campaign information from the visitor’s ongoing visit. You can disable this behavior by setting create_new_visit_when_campaign_changes=0 under [Tracker] section in your config/config.ini.php file.
• By default, Matomo won’t create a new visit when a visitor views your website using a different website referrer information. You may configure Matomo to force it to create a new visit whenever a visitor uses a new website referrer. To do so, edit config/config.ini.php file and under [Tracker] section add: create_new_visit_when_website_referrer_changes=1.
• By default, Matomo might also create a new visit when a visit had many actions. Learn more in this FAQ
• You may also create visits on demand by using the Tracking API or Javascript Tracker. Learn more in this FAQ.

How do I prevent Matomo from creating a new visit after 10000 actions?

Since Matomo 4.2, Matomo creates a new visit as soon as a visit had 10000 actions within the same visit. So when action 10001 is tracked, a new visit will be created and all future actions will be tracked into this visit. This is to make sure Matomo stays fast as a visit with too many actions can slow down Matomo and can put a significant load onto the database.

You can change this behaviour by adjusting the config/config.ini.php file. For example to create a visit only after 50000 actions add the following lines to your config file:

[Tracker]
create_new_visit_after_x_actions = 100000

If the category [Tracker] already exists in your config file, don’t add this line again. To never create a new visit because of too many actions set 0.

[Tracker]
create_new_visit_after_x_actions = 0

You only need to change this setting if it’s normal for your site or app to have this many actions within one visit.

How do I get the DB-IP databases or Maxmind GeoIp2 to improve accuracy of Country detection, and detect visitors’ Cities and Regions?

Matomo recommends the use of
1. DB-IP‘s databases,
2. or if you are willing to sign up for a MaxMind account: the MaxMind GeoIp2 databases which are currently more accurate at the city level.

These databases are sold either by DB-IP (DB-IP sells different databases, each with different amounts and types of information) or MaxMind.

The country and city databases can be used to determine the location of an IP address with different amounts granularity:

• The country database can only tell you the country of an IP address.
• And, the city database can tell you the country, region, city, postal code, geographic coordinates (latitude/longitude) and area code of an IP address.

The ISP and Organization database can be used to determine the ISP and company of an IP address.

You can find more information on the commercial DB-IP databases here.

Both providers provide two free databases that are less accurate than the commercial ones. One of the free databases can only be used to determine an IP address’ country. The other, the IP to City Lite, can be used to determine the same information as the commercial city database.

You can find more information on the free Lite databases here.

Needless to say, we recommend using one of the city databases.

Matomo includes a tool that will download the IP to City Lite database for you. You can access the tool by navigating to Settings > Geolocation.

If you want to install the database by hand, you can download each of the free databases here. Make sure to download the binary versions of the databases.

Keep in mind that geolocation data will eventually become out of date. It is recommended you update your databases at least once a month.* The free databases are updated once a month.

Note: The latest version of Matomo includes an auto-updater for these databases.

If you are installing the databases manually, then once you get the database you want to use copy it (the .mmdb file) to Matomo’s path/to/matomo/misc/ subdirectory. All common file names should already be supported. (You can find the list of supported file names here)

How do I install the PHP extension for GeoIP 2?

MaxMind provides an optional C extension that is a drop-in replacement for MaxMind\Db\Reader. This will speed up the location lookups for GeoIp2 PHP provider enormously and is recommended for high traffic instances.

Activate the GeoIp2 Plugin in Matomo

Check that the GeoIp2 plugin is activated in Matomo. To activate the plugin, go to the “Administration > Plugins” page and click “Activate” next to the GeoIp2 plugin.

Installing libmaxminddb

The PHP extension requires the C library libmaxminddb for reading MaxmindDB files. To install the library you need to download it’s latest tar ball and extract it, or clone their git repository.

git clone --recursive https://github.com/maxmind/libmaxminddb

Note: When cloning from git, run ./bootstrap from the libmaxminddb directory and then run the commands below.

To install it, run the following commands:

$ ./configure
$ make
$ sudo make install
$ sudo ldconfig

You can find more details about installing the library in their README

Installing Extension

After successfully installing libmaxmindb, you need to download or checkout MaxMind-DB-Reader-php.
Then run the following commands from the top-level directory of this distribution:

cd ext
phpize
./configure
make
sudo make install

You then must load your extension. The recommend method is to add the following to your php.ini file:

extension=maxminddb.so

Now restart the webserver and the GeoIP 2 PHP provider should mention if the extension is loaded in Matomo (Piwik) > Settings > Geolocation.

Note: You may need to install the PHP development package on your OS such as php5-dev for Debian-based systems or php-devel for RedHat/Fedora-based ones.

How do I get a license key for the MaxMind geolocation database?

To configure the free MaxMind geolocation database in Matomo you will need to first get a license key from MaxMind. To do this, follow these steps:

• Sign up for a MaxMind account
• Once you’re signed up, after a few hours you will receive a confirmation email with login details
• Log in to your account
• Click on “My license key”
• Click on “Generate a new license key”
• Enter a license key description, for example “Matomo”, and choose “No” for “Will this key be used for GeoIP Update?”

• Click on “Confirm”
• The license key will now be shown.
• This license key will be only visible once so it’s best to copy it and save it somewhere secure, or use it in your Matomo right away. If you ever delete this license key, you will need to change the license key in Matomo.

How do I install the GeoIP 2 module for Apache for accurate Geo location data?

Installing the module

To install mod_maxminddb for Apache please follow their installation instructions.

Configuring Matomo

After setting up mod_maxminddb for Apache, you may need to adjust the Matomo Geolocation settings, so Matomo uses the correct server variables. You can do that within the General Settings.

How do I get the geolocation download URL for the free MaxMind DB?

When you set up geolocation in your Matomo On-Premise, then you can choose between different location providers such as DB-IP and MaxMind. The MaxMind DB shows generally more accurate results for cities and regions.

If you are wanting to use MaxMind, follow these steps

• Create a license key as described in this FAQ
• Use this URL and append the value of your license key at the end of the URL:

  https://download.maxmind.com/app/geoip_download?edition_id=GeoLite2-City&suffix=tar.gz&license_key=

• Now you can copy / paste this URL into the Location Database Download URL field in your Matomo and save the change.

How do I install the GeoIP 2 module for Nginx?

Installing the module

To install GeoIP 2 module for Nginx please follow the instructions in their README

Configuring Matomo

After setting up GeoIP 2 for Nginx, you may need to adjust the Matomo GeoIp2 settings, so Matomo uses the correct server variables. You can do that within the General Settings.

How do I apply accurate geolocation to old visits, tracked before I enabled geo location?

If you want to know the location of the visits your website received before you started using Matomo with a geolocation database, there is a console command you can use. The command will geolocate every one of your visits that have not been located (or just the ones you want to geolocate). Since it goes through many visits in your database, it can take a long time to run.

Connect to your Matomo server over SSH, and open a terminal. The command is called usercountry:attribute and can be executed in the terminal by running (for example):

php ./console usercountry:attribute 2012-01-01,2013-01-01

Things you should note:

• The command will not work with the Apache or NginX server modules, since this requires sending requests through a web server.
• If you use the GeoIP2 PHP API it will take longer to run, so we recommend using this command with the GeoIP2 PHP extension. You can see how to install the PHP extension here.

After you run the script make sure you reprocess your reports so new reports w/ location data will be shown.

How do I get company and ISP information using GeoIP2 databases?

DB-IP IP to ISP database can be used to get company/provider information for visitors. MaxMind also provides an ISP database.

To use them, simply select & purchase the database you want and upload it to the misc Matomo directory. (If you are using a GeoIP server module you may have to do more to get it to work w/ Matomo. The relevant instructions are here for Apache, and here for Nginx.)

You will also need to check the Provider plugin in Matomo is installed and activated.

How do I track and measure how my Matomo service is being used?

The plugin AnonymousPiwikUsageMeasurement allows you to track usage data of the Matomo (Piwik) service into up to two Matomo installations:

• your own Matomo (can be configured optionally)
• a custom Matomo (can be configured optionally)

The plugin can be installed via the Matomo Marketplace with just a few clicks within your Matomo installation. As a Super User simply go to the Administration and select Marketplace in the left menu. There you will find the plugin and can install it with just one click. Learn more.

How do I track user acquisition and social media activity with Matomo?

Being able to monitor user acquisition and social media activity is essential for determining whether the outcome of your campaigns is in line with the business objectives. Determining the source of each website visit that gets you closer to your business goals enables you to focus your efforts in the directions that are worth it. Learn more in our article Tracking User Acquisition and Social Media Activity with Matomo (Piwik)

How do I customise any text label such as menus, report names, column names, event names and values, custom dimension names, custom report names, dashboard names and more?

Matomo user interface has thousands of text labels: menus, report names, column names, help text, setting names, tooltips, etc.
Sometimes you want to update these strings and customise them.

Overwrite label within Matomo app

For example, you may want to rename a particular sub-menu in Matomo to be more easily understood by your audience. To define custom strings (translations) for any of Matomo text/label, install the Customise Translations plugin from the Marketplace. This plugin lets you easily overwrite any string of Matomo. The overwritten strings will be stored in the database as plugin settings and will be persisted when you upgrade Matomo in the future.

Overwrite labels within reports data

For example, you may want to rename a Custom Dimension value (that you have tracked in the past) to make it more clear to your audience.
When you need to rename strings within the reports and the data, you can use another plugin called Custom Translations. This plugin lets you translate the following entities and tracked values into another language:

• Tracked custom dimension values
• Tracked event values
• Configured custom dimension names
• Configured custom report names
• Configured Dashboard names

How can I add the dimensions Campaign name, Campaign medium, Campaign source, Campaign keyword, Campaign content to a custom report?

If you want to add the dimensions like Campaign name, Campaign medium, Campaign source, Campaign keyword, Campaign content to your Custom reports, you can do that just by installing Marketing Campaigns Reporting plugin. By default these dimensions are not available in your Custom report except keyword.

Note: This FAQ written on an assumption that you are using Matomo On-Premises.

How do I add a referral exclusion in Matomo?

To exclude URLs so they do not appear in your Acquisiton report data (as the “Websites” channel and website referrer URLs), add the URLs you want to exclude to your list of website URLs, by following these steps:

• Go to Admin > Websites(or Measurables) > Manage,
• Edit the website in question,
• Add the URLs to be excluded to your list of “URLs” for this website.
  For example:

Then whenever Matomo will track visits in the future, any website referrer that matches the same hostnames as the “URLs” of your website, will appear as “Direct entry” instead of “Website” referrer channel.

How do I create a simple affiliates system and track new customers and new revenue for each affiliate?

It is possible to create a simple affiliate mechanism using Matomo. For this system to work, you give your affiliate a special URL parameter they use to link to your website. Then you can track all new customers and revenue generated by each of your affiliates using Matomo.

Track users and customers with an affiliate URL parameter

When your affiliates send to you new leads, they would append to their URL linking to you a new parameter: &pk_cpn=Affiliate-XYZ. When users will click a link to your website URL and including this pk_cpn parameter (which is an alias of pk_campaign), then the user will be tracked as coming from a Campaign named Affiliate-XYZ.

Reporting affiliate conversions and revenue

To track conversions and revenue:

• First you create a goal and set a Revenue for your goal which tracks the actual revenue of each conversion.
• ​​Then in Matomo > Goals, you would be able to see how many visitors came from each affiliate by looking at the “Conversions” and “Revenue” metrics in your Campaign names report for your goal.
• You are then able to use this report to calculate what revenue to pay your affiliates.

Instead of creating a Goal, you can use Ecommerce and see how many products and total sales each affiliate has generated.

Accurately credit your affiliates who first brought you the leads

In most cases your affiliates are the ones who first refer new leads to you. But by default Matomo credits the “last seen referrer” which will cause many affiliate conversions to be missed. You therefore need to manually enable the “First seen referrer” attribution in your website, to accurately attribute your affiliates who first brought you customers. Read our First seen referrer attribution FAQ.

Customising the affiliate URL parameter

Above we recommended you include the pk_cpn or pk_campaign parameter in your landing pages, but you can use another URL parameter by following the step below. This may be useful if for example you already have several links pointing to your websites which may use another URL parameter such as ref or affiliate_id. To define a new alias for this URL parameter, edit your config.ini.php file and under the [Tracker] section, define the comma separated list of valid campaign name parameters as below:

[Tracker]
campaign_var_name = "ref,affiliate_id,pk_cpn,pk_campaign,piwik_campaign,utm_campaign,utm_source,utm_medium"

In this example we added ref and affiliate_id as URL parameters at the start of the list, and we still leave the “default” parameters to make sure we still track any other campaigns that may use these. After changing this setting, any user coming to your page example.com/welcome.html?ref=AFFILIATE_ID_HERE will be categorised as campaign acquisition channel.

Limitations

Using Matomo as a simple affiliate system has some known limitation:

• If customers weren’t tracked by Matomo for some reasons (using ad-blockers, opted-out, or other reasons), then the goal conversion and the revenue wouldn’t be tracked at all, and therefore wouldn’t be attributed correctly to the affiliate.

How do I tell Matomo to track Unique Visitors based on the Visitor ID cookie, instead of using IP Address?

By default, Matomo (Piwik) will match a Unique Visitor based on the Visitor ID cookie (if visitor supports cookies) and/or based on a user fingerprint processed from the IP address and user device information (if visitor does not support cookies).

There are a few use cases when the default Tracker algorithm to track unique visitors does not work as expected. For example if you use Matomo on an Intranet and all users have the same IP address, or if many of your visitors come from a Company or University network and have all the same IP addresses, then Matomo may track many users as one unique visitor.

In these cases you can enable better unique visitors recognition:

• If your website has a login form, when users sign-in we recommend to tag your users with a User ID.
• Alternatively if you cannot use User ID then you may force Matomo not use the IP address and device info to decide Unique Visitors but instead rely on the Visitor ID found in the user cookie. To force Matomo to not rely on the IP address as a mean to differentiate one user from another, edit your config/config.ini.php and add a new section [Tracker] with the following:

  [Tracker]
  trust_visitors_cookies = 1
  

See also: How does Matomo detect unique and returning visitors? (with User ID, Visitor ID from cookie and/or fingerprint)

How do I clear the various caches in Matomo?

Matomo (Piwik) creates cache files during its normal operation. The caches are automatically deleted in Matomo during an upgrade of core, or an upgrade of a plugin. But in some cases it is useful to be able to delete manually.

To delete all cache files used by Matomo, you can run the following command in your Matomo directory:

 ./console cache:clear

Alternatively if you don’t have access to the server and command line, you can delete Matomo caches by deleting all the files and directories inside the path/to/piwik/tmp/ folder in Matomo (the tmp/ folder).

How do I change the number of rows in scheduled email reports (csv, html or pdf) and show more than the default 23 rows?

It is possible to change the number of rows displayed in email reports, but currently this is a global change and so it is not possible to customise the number of rows in individual reports (see feature request).

To change number of rows from the default of 23 rows to for example 50 rows, please edit your config/config.ini.php file and and set under the [General] category:

scheduled_reports_truncate=50

All reports in your scheduled email reports will now list up to 50 rows.

How do I exclude specific tracking requests in Matomo?

In this FAQ you will learn how to exclude specific tracking requests from being recorded across all sites depending on the sent Tracking API Parameters. This feature can be useful for example in these cases:

• you need to urgently stop specific requests from being tracked to temporarily fix a performance issue. For example, you start tracking a new event in a website or application and suddenly get sent a massive amount of tracking requests due to a bug in the tracking code implementation. Using this feature you can exclude the specific tracking requests for this newly added event but keep tracking all the other regular tracking requests.
• you want to ensure certain requests will never be recorded for example for privacy or security reasons and you can’t remove the tracking code from these pages.

Requirements

To use this feature you need to have Matomo On-Premise 4.0 or newer and you need to be able to modify the Matomo config file in $matomoRoot/config/config.ini.php.

Configuration

Add the following line to your config file to configure this feature:

[Tracker] # only add this line if it doesn't exist yet
exclude_requests = ""

• The structure for this configuration is: {tracking parameter name}{operand}{value to match}
• The following operands are supported:
  • Equals: ==
  • Not equals: !=
  • Contains: =@
  • Not Contains: !@
  • Starts with: =^
  • Ends with: =$
• The value to match on the right side should be URL encoded. For example: "action_name==foo%2Cbar" would exclude page titles with the name “foo,bar”.
• All comparisons are performed case insensitive.

For example "e_c==Media" means that all tracking requests will be excluded where the event category is Media.

Multiple exclusions can be configured separated by a comma. The request will be excluded if any expressions matches (not all of them). For example: "e_c==Media,action_name=@privacy". This would additionally exclude any request from being tracked where the page title contains privacy.

For a list of tracking parameters you can use on the left side view the Tracking API Reference.

More examples:

• Exclude all tracking requests for a specific site with ID 1: "idsite==1"
• Exclude where the event name is “file”: "event_name==file"
• Exclude where the page URL contains “restricted”: "url=@restricted"
• Exclude when cookies were used (for example you want to make sure to not track requests where cookies were used for privacy compliance): "_id!="
• Exclude logged in users: "uid!="
• Exclude not logged in users: "uid=="
• Exclude where the downloaded file URL contains “token”: "download=@token"

Other ways Matomo allows you to exclude traffic (directly in the Matomo UI):

• Exclude user agents
• Exclude specific IP addresses
• Exclude my own traffic
• Exclude URL query parameters

How do I enable tracking for visitors when JavaScript cannot be used on a page (or for Visitors that have disabled Javascript)?

Sometimes it is not possible to use the standard Matomo Analytics JavaScript Tracker in your app or websites. For example:

• to track visitors who have JavaScript disabled
• to track how often pages are viewed on a website you don’t control and won’t allow you to include JavaScript code in their pages (such as Ebay or other third party marketplaces).
• to track your newsletter emails opened rate (this is covered in a separate FAQ)

With Matomo you can still enable tracking of visitors when JavaScript cannot be used, using the Matomo Image Beacon.

You can include an image in your web pages, the image simply being a reference to the Matomo Tracking API endpoint, and Matomo will collect data about your users. Here is what the image looks like:

<!-- Matomo Image Tracker -->
<img src="https://matomo.example.org/matomo.php?idsite={$IDSITE}&amp;rec=1" style="border:0" alt="" />
<!-- End Matomo -->

In this example above, replace {$IDSITE} with your Matomo website ID, and replace https://matomo.example.org/ with your Matomo URL:

The following parameters can also be passed to the image URL:

• rec – (required) The parameter &rec=1 is required to force the request to be recorded
• idsite – (required) Defines the Website ID being tracked
• action_name – Defines the custom Page Title for this page view
• urlref – The Referrer URL: must be set to the referrer URL used before landing on the page containing the Image tracker. For example, in PHP this value is accessible via
  $_SERVER['HTTP_REFERER']
• idgoal – The request will trigger the given Goal
• revenue – Used with idgoal, defines the custom revenue for this conversion
• bots – Set &bots=1 to track all requests to the tracking image, including from bots and robots
• and more! – There are many more parameters you can set beyond the main ones above. See the Tracking API documentation page.

Note: this image tracking code does not use Javascript and is not able to create first party cookies, so Matomo will not be able to track some user information, learn more in When tracking visitors using an image beacon instead of the JavaScript tracker, what are the differences?

Enable Tracking for visitors who have JavaScript disabled

When you use the standard Javascript Tracking Tag, Matomo (Piwik) will only track visitors with Javascript Enabled in their web browser. You can configure Matomo to also track users who have disabled Javascript: to do so, edit the Matomo Tracking Tag and add a <noscript> element which includes the Image beacon:

<noscript><p><img src="http://matomo.example.org/matomo.php?idsite=1&rec=1" style="border:0" alt="" /></p></noscript>

After making this change, visitors with disabled Javascript will execute the noscript and will load the matomo.php image and will have their traffic recorded in Matomo.

Using Server-side Tracking or Log Analytics

In some cases tracking using an image tracker might not be the best option for your website or app. In these cases you can still implement tracking using Server-side tracking or alternatively with Log Analytics using your web server logs

How do I verify the cryptographic PGP signature of Matomo packages?

When we create a new Matomo (Piwik) release, right after the Matomo core packages .zip and .tar.gz have been created, the Matomo release manager signs the packages using his PGP key. This creates a cryptographic signature which gives you the possibility to check that the release package you have downloaded is the same as the one that was provided by Matomo team. Learn how to verify the signature in this blog post with instructions for Windows, Mac OS X and Linux.

How do I customise the JavaScript Tracker code on all websites at once?

To measure your websites with Matomo (Piwik) you are likely to use the Matomo JavaScript Tracking code, a small snippet of code that should be added in your websites pages. When visitors view your website, the Matomo tracking code gets executed by the browser and your visitor’s browsers load the matomo.js file from your Matomo server, for example: demo.matomo.cloud/piwik.js.

In some cases it may be useful to customise the matomo.js tracking code. This FAQ explains the best practise method to let you safely edit the matomo.js file. Note that this is an advanced feature and should be used with great care. First you will need to install and activate the plugin JsTrackerCustom. Login as a Super User in Matomo then go to Administration, click on Marketplace and install the plugin JsTrackerCustom. After activating this plugin, Super User can click on the Admin menu ‘Plugin Settings’ link. Any text entered in the field ‘Javascript code’ will be appended to the content of matomo.js.

For example, if you wanted to enable Content Tracking on all your websites at once, enter the following:

if ('undefined' !== typeof _paq) {
     _paq.push(['trackVisibleContentImpressions']);
}

Note: changing matomo.js will affect all your websites at once (all websites load the same matomo.js file). Use this feature with care: if you input invalid JavaScript code then it may create JavaScript errors on your websites.

How do I take notes of particular events influencing my traffic?

Often when using Matomo (Piwik) you may have findings from the data, insights, or maybe you just would like to note down the changes you have made on the website. In Matomo you can take notes on the graph and set any number of text messages. They’re called Annotations (click to learn more).

How do I get the Visitor Geo Location data from the Visitor IP? (or in JavaScript/JSON when IP address is not known)

In Matomo (Piwik) we recommend to configure Geo Location so that your visitors are accurately tracked. Once it is setup, you can use a geolocation database to get an IP to Country, or IP to City, or IP to Region information. We have added a simple API that you can re-use, called UserCountry.getLocationFromIP.

To use it, go to Matomo, click API, click on “UserCountry” then on the getLocationFromIp call.

Click to see a typical response from the UserCountry.getLocationFromIP API call.

You may use this simple Web API provided by Matomo to add geo location functionality to your Apps, for example.

JavaScript / JSON API to get the visitor geo location without knowing the IP address

Since Matomo 3.10.0 you can also use this API in JavaScript / JSON by simply calling the API without specifying the ip URL parameter. This is valuable because when you’re running in the browser in JavaScript it is not possible to get the IP address. So by simply calling this API: https://analytics.example.comorg/?module=API&method=UserCountry.getLocationFromIP&format=json in JavaScript you will get the geo location data for the current user requesting this request. This would be useful when you want to personalise the website’s content based on the user’s geolocation for example. Notes:

• This will work only when anonymous access is enabled and has access to at least one website.
• because this API request takes around 200ms or more, this is too slow for your website to depend on this request to personalise content. We would only recommend it when personalising elements on the page that are optional (after the main page was loaded) to ensure your website loads quickly.

How do I disable the update notification email when a new Matomo version is released?

At Matomo (Piwik) we have a policy to recommend users to use the very latest Matomo version. To help you with keeping up to date with the latest version, your Matomo server will automatically send you an email within a day after a new version was published. The subject email is New Matomo 3.0.0 is available and the message contains a direct link to your Matomo to update in one click. The email is only sent to users having Super User access.

If for some reasons you do not want your Matomo server to send these notification emails you can disable them by editing your config/config.ini.php file and adding below [General] the following: enable_update_communication=0

Note: this setting will also disable the New Plugin releases notifications emails. Plugin notifications is a feature you can enable in ‘General Settings’ that will send Super Users an email when a new plugin versions is released on the Marketplace.

How do I access a real time counter of visitors currently on my site?

On the Matomo (Piwik) dashboard you may add the widget “Real time > Real time visitor count”. This widget shows a counter of the number of people currently on the website.
By default Matomo uses a 3 minutes delay to define a “Visitor currently on the website”. You may edit this value in the config.ini.php file, for example set to 10 minutes:

[General]
live_widget_visitor_count_last_minutes=10

How do I fix the errors “Unable to write in the cache directory” or “The directory matomo/tmp/cache/*” is not writable.”?

It may happen that the User Interface of Matomo fails to load and display an error message which can mention Unable to write in the cache directory or The directory tmp/cache/* is not writable. This indicates there is a small issue around folders and/or file permissions within the Matomo directory. The full error message could be A fatal error occurred. The following error just broke Matomo (v3.10.0): An exception has been thrown during the rendering of a template "Unable to write in the cache directory"

These issues can be addressed by setting the correct permissions that will let processes read and write the tmp/ folder.

General solution: if your web server username is www-data then you can have your webserver own the files in this directory (replace www-data by the web server username, sometimes called apache):

sudo chown -R www-data:www-data /var/www/html/matomo/tmp/*

If your server is running SELinux or CentOS, you may be able to fix the issue with the following commands:

chcon -t httpd_sys_content_rw_t /var/www/matomo/tmp
chcon -R -t httpd_sys_content_rw_t /var/www/matomo/tmp/tracker/
chcon -R -t httpd_sys_content_rw_t /var/www/matomo/tmp/cache
systemctl reload httpd.service

If this error keeps occurring, the issue may be that the scheduled task (crontab) for the core:archive console command is running and writing these files as a different user. To solve the issue you want to modify your crontab so that it runs the core:archive command as the web server user, for example running as www-data or apache. See the the user guide for more details.

It has also sometimes helped to upgrade PHP to use a recent PHP release.

If you still experience this issue after following the steps above, please get in touch with us at matomo.org/contact and we will help troubleshoot further.

How do I get Matomo segments to behave as a filter?

Since Matomo 3.12.0 the segments behave no longer like a filter but instead include all data of visits that match a certain segment.

This means if you have a segment like page url contains example, and you view a Page title report, then all pages with a title that contained example used to be shown (before Matomo 3.12.0). With this new behaviour (3.12.0 and newer), all page titles are now shown that were viewed by visitors who also viewed a page with the title example as part of their visit. This means it does not only show pages that contained the word example, but also all the other page titles that were viewed by these matching visits.

To restore the previous behaviour, you can edit your config/config.ini.php and add the following setting:

[General]
enable_segments_cache = 0

How do I create Custom Segments of Visitors and apply the segments to filter my report’s data?

Matomo (Piwik) lets you easily create advanced Custom Segments of Visitors. You can save Custom Segments to reuse them later. As well as being available from the User Interface, Custom Segments can also be applied via the Analytics API. Custom Segments can contain unlimited number of AND and OR clauses, using any combination of more than 40 available dimensions (visitor attributes).

Alternatively, you can create Custom Reports which lets you filter any custom report depending on your requirements. This way you can for example add several reports that target a specific audience next to each other and compare them much easier.

Note: you may also apply custom segments to Custom reports scheduled to be sent by sms text message and/or email reports as HTML or PDF. With Matomo you can scheduled reports on a custom segment of your audience, better analytics for your team members and clients.

How do I monitor that Matomo service is up and running?

To setup monitoring of your Matomo analytics service, we recommend to setup the following monitoring checks:

• HTTP Reporting API and Core platform: request to /index.php?module=API&method=API.getMatomoVersion&token_auth=YOUR_TOKEN_AUTH_HERE should return http status 200
• HTTP Tracker API: request to /matomo.php should return http status code 200

We recommend to use https:// in the monitoring URLs checks, to make sure that your Matomo service works over secured connection.

How do I backup and restore the Matomo data?

You can easily backup and restore the Matomo data using the following commands.

Export your MySQL/MariaDB database in a file

You can use tools such as phpMyAdmin or mysqldump to do this. The simplest way to make a full copy of the MySQL database is to run the mysqldump command with this set of parameters:

$ time mysqldump --extended-insert --no-autocommit --quick --single-transaction MATOMO_DATABASE_NAME -uMATOMO_DATABASE_USERNAME -p > matomo_backup_database.sql

We can then compress this backup before sending it to the backup server:

$ tar zcf matomo-mysql-database-$(date +%Y-%m-%d-%H.%M.%S).sql.tar.gz matomo_backup_database.sql

Restore the backed up database dump

you can use phpmyadmin to import the file that you previously created, or restore the DB backup by running the following command:

 $ time mysql MATOMO_DATABASE_NAME -uMATOMO_DATABASE_USERNAME -p < matomo_backup_database.sql

This should create more than a dozen Matomo tables in your database and restore all your data.

Note: if you restore the backup in a “test” instance, you may be interested in disabling all email notifications.

How do I improve my website pages load time and speed and minimise Matomo JavaScript Tracker performance overhead?

Many studies have shown that performance matters a lot. For each 100ms a websites takes longer to load, a business may lose about 0.1% to 1% in revenue. It also matters because Google judges page speed as a ranking factor for search results page. At InnoCraft, we help our clients optimizing their Matomo (Piwik) integration and recommend different ways of embedding the tracking code tailored to their needs. The best way to embed the tracking code depends on your website, what you want to achieve, and how important tracking is to you.

Read more in our blog posts:

• Different ways of embedding the Matomo tracking code for faster website performance
• Performance optimizations you can apply today to load the Matomo JavaScript tracker faster

See also Will the Matomo Analytics JS Tracker slow down my site?

How do I remove the tracked domain or hostname from all page URLs?

Assuming you are using our JavaScript Tracker you can remove the domain from the tracked URL by adding this to your tracking code:

_paq.push(['setCustomUrl', window.location.pathname.substr(1) + location.search]);

This way only the path and URL parameters are being tracked and reported in Matomo.

How do I make “Transitions” feature work faster on high traffic websites?

Transitions is a very useful Matomo (Piwik) feature, which is also fundamentally different from most of the other Matomo reports. It does not use archiving to pre-process reports but instead it retrieves its information directly from the logs. This means that the Transitions report can take a few seconds to load on websites with more traffic, but on the other hand, Transitions does not require pre-processing and does not affect Archiving performance.

In our tests, Transitions could handle periods with several 100.000 pageviews quite well. Once you get into the millions, it starts to test your patience. But in general, performance depends heavily on the power of your database server and other things like traffic patterns.

Also, the first time you open Transitions on any page might be a fair bit slower than consecutive calls. This is because after the first time, the database caches are hot and the queries can be executed much faster.

If you have lots of traffic, you shouldn’t open Transitions on long periods of time. But that’s not really a problem because the most important thing is to have enough data in order to get statistically representative results. If you achieve this mass with a single day, it should be fine if you only use it for yesterday (or today).
Since the aggregation happens in the database, you can tune things by adding some indexes to the MySQL tables.

You can create the following INDEX to speed up Transitions on page URLs:

ALTER TABLE  `matomo_log_link_visit_action` ADD INDEX `transitions_url` (  `idaction_url` ,  `idsite` ,  `server_time` ), ADD INDEX `transitions_url_ref` (  `idaction_url_ref` ,  `idsite` ,  `server_time` );
ALTER TABLE  `matomo_log_visit` ADD INDEX `transitions` (  `visit_entry_idaction_url` ,  `idsite` ,  `visit_last_action_time` );

We have confirmed that these indexes drastically improve performance for pages that had a fairly low share of the overall traffic. They do add a little extra complexity when inserting new logs but speeding up Transitions also means having the queries it does out of system in a shorter amount of time, which in turn has a positive impact on tracking performance.
You may not need all of these indexes. Instead, you can add them one by one until the performance of Transitions is satisfactory.

Note: Adding these INDEXes will also increase the Performance of Page Overlay reports.

How do I configure Matomo Tracking for high reliability?

To configure Matomo (Piwik) Tracking for high availability, reliability, and better scalability, please see this other FAQ: How do I configure Matomo to use Redis for better scalability?

Note: if you need professional support, get in touch with the Matomo consultants who are experts in scaling and configuring Matomo.

Related user guides: learn more about Matomo requirements, and read tips how to optimize Matomo for speed. You may also be interested in Data Limits.

See also Will the Matomo Analytics JS Tracker slow down my site?

How do I configure Matomo to use Redis for better scalability?

When you track a lot of data in your Matomo (Piwik) server, you may find that the calls to the Tracking API (piwik.php) become a scalability bottleneck. We have created a new plugin QueuedTracking that we release away for free(dom) to you, the community. This plugin will help with scaling your Matomo server to track dozens or hundreds of millions of requests per month.

This plugin writes all tracking requests into a Redis instance instead of directly into the database. (There is also an option to use a MySQL queue instead if you prefer not to use Redis.) This is useful if you have too many requests per second and your server cannot handle all of them directly (eg too many connections in nginx or MySQL). It is also useful if you experience peaks sometimes. Those peaks can be handled much better by using this queue. Writing a tracking request into the queue is very fast (a tracking request takes in total a few milliseconds) compared to a regular tracking request (that takes multiple hundreds of milliseconds). The queue makes sure to process the tracking requests whenever possible even if it takes a while to process all requests after there was a peak.

To get started, install the QueuedTracking plugin from the Marketplace. Click on the FAQ tab to learn more about the requirements and how to use the plugin on your Production Matomo server. For any bug report or feature request, please post them in the plugin’s issue tracker.

Contact Matomo Consultants if you need help with high traffic Matomo setup, or if you’d like experts to take care of your Matomo setup, configuration, maintenance and security.

How do I fix the tracking failure “Request was not authenticated but should have.”

You see a failed tracking request with this error message when you use specific tracking parameters as part of the HTTP tracking API without authenticating the request correctly. Some parameters that require authentication are for example cip (forcing a specific IP address), or cdt (overrides the datetime of the request).

When such an error occurred, you need to make sure to set a token_auth of a user with at least write permission. If you have set a token, check the set token to make sure it is still the same and no copy/paste error has happened.

Or if you are tracking a Mobile App using iOS or Android SDK, you may get this error when some requests are sent more than 1 day after they were generated on the device, and the custom datetime of the request is too far in the past and then they fail. That’s because by default, Matomo accepts only tracking requests for up to 1 day in the past. You can change how far back Matomo will track your requests without authentication. The configured value is in seconds. You can change this setting in config.ini.php by setting under [General] the following value for example 10 days (default is 1 day):

[General]
tracking_requests_require_authentication_when_custom_timestamp_newer_than = 864000;

You may also be interested in disabling the tracking failure emails.

How do I fix the tracking failure “The site does not exist.”

You see a failed tracking request with this error message when an invalid idSite is configured as part of your tracking code.

For example, in the default JavaScript tracking code the idSite is configured like this:

_paq.push(['setSiteId', '1']);

When you get this error, make sure your tracking code includes this line (or for example tracker.setSiteId(idSite) if you configure the tracker manually). Then check the configured ID actually exists by going to “Administration” => “Measurables/Websites”. Maybe the site has been deleted, or never existed in the first place and setting the correct ID will resolve the problem.

How do I fix a truncated or rounded revenue or price value?

If you installed Matomo Analytics before Matomo 4.0, a revenue or price value might be truncated or rounded when the value is high. For example if you track a value of 12225201, the value might be stored as 12225200.

If you track high revenue or price values, you can fix this issue by running a database migration script like this:

ALTER TABLE  `matomo_goal` CHANGE `revenue` `revenue` DOUBLE NOT NULL;
ALTER TABLE  `matomo_log_conversion_item` CHANGE `price` `price` DOUBLE NOT NULL;
ALTER TABLE  `matomo_log_conversion` CHANGE `revenue` `revenue` DOUBLE NULL DEFAULT NULL;
ALTER TABLE  `matomo_log_conversion` CHANGE `revenue_discount` `revenue_discount` DOUBLE NULL DEFAULT NULL;
ALTER TABLE  `matomo_log_conversion` CHANGE `revenue_shipping` `revenue_shipping` DOUBLE NULL DEFAULT NULL;
ALTER TABLE  `matomo_log_conversion` CHANGE `revenue_subtotal` `revenue_subtotal` DOUBLE NULL DEFAULT NULL;
ALTER TABLE  `matomo_log_conversion` CHANGE `revenue_tax` `revenue_tax` DOUBLE NULL DEFAULT NULL;

Please note running this update script may alter your existing values. For example, if previously a value of 4.1 is stored, it might convert it to 4.099999. As a result, for example a changed value might not match a specific segment anymore.

If you’re wanting to test this first, you may compare the output of this SQL query (this query may run a long time):

    SELECT price, CAST(price as DOUBLE) FROM matomo_log_conversion_item WHERE price is not null ORDER BY price ASC LIMIT 10000;
    SELECT revenue, CAST(revenue as DOUBLE) FROM matomo_log_conversion WHERE revenue is not null ORDER BY revenue ASC LIMIT 10000;
    SELECT revenue, CAST(revenue as DOUBLE) FROM matomo_goal WHERE revenue is not null ORDER BY revenue ASC LIMIT 10000;

To see if any value would be changed as it depends on your MySQL version. Integers (numbers without a fraction part) should remain generally unchanged.

How do I fix a truncated event value?

If you installed Matomo Analytics before Matomo 4.0, an event value might be truncated or rounded when the value is high. For example if you track a value of 12225201, the value might be stored as 12225200.

If you track high event values, you can fix this issue by running a database migration script like this:

ALTER TABLE  `matomo_log_link_visit_action` CHANGE `custom_float` `custom_float` DOUBLE NULL DEFAULT NULL;

Please note this same DB field is also used for storing other data like how long it took to load a website and running this update script may alter your existing stored custom values. For example, if previously a value of 4.1 is stored, it might convert it to 4.099999. As a result, for example a changed value might not match a specific segment anymore.

If you’re wanting to test this first, you may compare the output of this SQL query (this query may run a long time):

    SELECT custom_float, CAST(custom_float as DOUBLE) FROM matomo_log_link_visit_action WHERE custom_float is not null ORDER BY custom_float ASC LIMIT 10000

To see if any value would be changed as it depends on your MySQL version. Integers (numbers without a fraction part) should remain generally unchanged.

How to configure Redis as a shared cache in a load balanced environment?

By default Matomo (Piwik) caches data in the local filesystem of each server. If your Matomo environment consists of multiple servers a common problem is that caches are only invalidated on one server instead of all servers. To workaround this we recommend to use a shared cache for all of your servers. You can do this by installing and configuring Redis.

Known issues:

• The Redis cache can be only used if all servers have the same path to the Matomo directory
• There may be temporary issues while deploying a new Matomo version if not all servers are updated at the same time.

To use Redis as a cache follow these steps:

• Make sure you are using at least Matomo 2.10 (latest Matomo version recommended)
• Install Redis see Redis Quickstart
• Install the PHP extension phpredis
• Don’t forget to restart your webserver
• Once successfully setup, enable it in the config file config/config.ini.php. Make sure to adjust the section [RedisCache] to your needs. You have to make this change on each of your server.

changes to config/config.ini.php:

[Cache]
backend = chained

[ChainedCache]
backends[] = array
backends[] = redis

[RedisCache]
host = "127.0.0.1" 
port = 6379
timeout = 0.0
password = ""
database = 14
; In case you are using queued tracking: Make sure to configure a different database! Otherwise queued requests will be flushed

How do I disable tracking failures notification emails?

To disable email notifications about Tracking Failures, edit your config/config.ini.php file and under the [General] section, add the following line:

 enable_tracking_failures_notification = 0

How do I configure Redis for session handling in a load balanced environment?

Matomo uses the database as a session handler. Matomo used to also support redis and file based session handlers, but these have been deprecated as of 2019 and do not work anymore.

How do I prevent Super Users from doing specific high risks administrative actions?

In Matomo, Super Users are trusted and can do a lot of important actions. For example they can:

• Install new plugins
• De-activate plugins
• Use the Marketplace and update plugins
• Modify Archiving settings
• Modify Update & Auto-update settings
• Modify Email server settings
• Modify Trusted Matomo Hostname
• Modify the geolocation settings

When would I want to prevent Super Users from doing these actions?

In cases where you may not 100% trust Super Users, then you may want to prevent Super Users from taking actions that could compromise security (such as installing new plugins). There are several cases where you may not trust Super Users, for example when you provide Matomo as a service to your customers, and Matomo Super Users may be your customers rather than your colleagues. Or when you run Matomo on the same server and account as other web applications, and you want to make sure that Matomo app is locked down as much as possible.

How do I prevent Super Users from doing high risks administrative actions?

Edit your config/config.ini.php file and set the following settings under [General] section:

; Disable installing new plugins and (de)activating plugins.
enable_plugins_admin = 0

; Hide and disable in the UI the following settings:
; - Archiving settings
; - Update settings
; - Email server settings
; - Trusted Matomo Hostname
enable_general_settings_admin = 0

; Disable the geolocation settings
enable_geolocation_admin = 0

You could also disable the Marketplace plugin to prevent new plugins from being installed.

How can I change the language of Matomo as a user?

By default, Matomo user interface may appear in English for all users who login to Matomo Analytics. Each user can choose their preferred language in their User Settings.

Follow the steps below to change the language:

1. Login to Matomo
2. Click on “Administration”(cog icon) on the top right
3. Click on “Personal > Settings”
4. Choose the language of your choice under “Language” dropdown
5. Click on ‘Save”

In JavaScript Tracker, how do I enable the use of navigator.sendBeacon()?

When tracking visitor actions in JavaScript on your website, it is possible to enable the use of the navigator.sendBeacon() method which Matomo will use to asynchronously transfer the tracking requests over HTTPs to the Tracking API. To enable this feature call the alwaysUseSendBeacon method as below:

[...]
// enable the use of navigator.sendBeacon()
_paq.push(['alwaysUseSendBeacon']);

// standard Matomo tracking code below
_paq.push(['trackPageView']);
_paq.push(['enableLinkTracking']);
[...]

Why would I use this feature? When enabling this feature, likely more of your clicks on downloads/ outlinks will be tracked and reported in Matomo (more accuracy). Also it will reduce the link tracking time to a minimum of 100ms instead of the default 500ms (default which can be increased), so that when they click on an outlink then the navigation to this clicked page will happen 400ms faster (faster and better user experience). Send beacon will only be used if the browser actually supports it.

Some ad blockers or other browser extensions may block the sendBeacon() feature which could again cause limited data loss in these cases.

Note: use of sendBeacon will be enabled by default starting in Matomo 4.

How do I get the most popular landing pages viewed by visitors coming through a specific channel type? (direct, search, website, social or campaign)

There may be times where you want to get a report for the top pages that users reached via a specific channel type, for example from a specific website or social network. This can be achieved in Matomo just by creating a Segment and opening the Entry page reports.

Follow the steps below to get the top pages used by visits from a specific channel:

1. On the Top control bar click “All Visits” (the Segment Editor)
2. Click on “Add New Segment”
3. Name the segment as desired
4. Choose “Referrers” > “Channel Type” by clicking the dropdown or search for “Channel Type”
5. Enter the desired “Channel Type” in the value field, either: direct, search, website, social or campaign
6. Click on “Save & Apply”
7. Click on “Behaviour” > “Entry Pages” on the left menu of your dashboard
8. You can now see your Top pages in the report, that visitors from your chosen channel have landed on.

How do I find a specific Ecommerce Order ID details?

To see the details of a specific Ecommerce Order ID, go to Matomo and follow these steps:

1. Make sure you have setup Ecommerce Tracking in Matomo.
2. Create a new segment and select condition where “Order ID is exactly XYZ”, for example in this screenshot we create a segment where Order ID is 1123581321:
3. Click the “Test” button in the “Add new segment” panel.
4. The Visits log will display for this Ecommerce Order, including all the details from the visit, which pages they viewed, how they found your website, and more. You can also click “Save and Apply” to save the segment and link to it or use it later.

How do I submit a feature request for Matomo?

We appreciate you taking the time to explain how we can improve Matomo (Piwik)!

If you realize that there is something you need that is missing in Matomo, please submit a feature request to Matomo.

See also: How do I report a bug in Matomo?

How do I see the pages that most visitors landed on? How do I access the top pages people use before leaving the websites?

Matomo (Piwik) reports Pages URLs and Page Titles. You can see the Top Entry Pages by clicking on Behavior > Entry pages. By default, it shows the top Entry Page URLs, but you can switch to the Entry Page Titles by clicking on the “Related report: Entry Page Titles” link below the report.

Similarly you can access the top pages that people see before leaving the sites, click on Behavior > Exit pages. It lists the “worst” Exit Pages URLs by default, but you can access the top exit page Titles by clicking on the Related reports link below the table.

How do I prevent Matomo from sending any email, when testing Matomo on a staging/non-prod environment?

Sometimes you may duplicate your production Matomo environment in a test or staging server. When you do so, your staging/testing Matomo instance may end up sending scheduled email reports or custom alerts to the people who had setup email reports in the production instance. You can prevent any emails from being sent from your test instance by adding the following setting under the [General] section in your config/config.ini.php:

[General]
; do not send any emails to users (including password reset, scheduled email reports, custom alerts, etc.)
emails_enabled = 0

How do I find a specific visitor logs by segmenting on Visitor ID?

To find visitor logs of a particular visitor you need to know an attribute of the visitor you are searching for. For example you can find a specific visitor based on their Visitor ID or User ID or a Custom Dimension value. In this example below it is assumed that you know the Visitor ID of the visitor you are looking for. To segment using the visitor ID, please follow the steps below:

1. On the Top control bar click “All Visits” (the Segment Editor)
2. Click on “Add New Segment”
3. Name the segment as desired
4. Click on the segment drop down, then click on “Visitors” from the list and choose “Visitor ID”.
5. Paste the Visitor ID in the “value” field. The segment reads “Visitor ID” is YOUR_VISITOR_ID
6. Click on “Save & Apply”
7. Open the Visitors > Visit logs report.

This will display the log of all the visits for this visitor for the chosen period. You can then click to open the Visitor Profile.

How do I downgrade from Matomo 4 to Matomo 3?

Matomo 4 comes with many database schema changes requiring additional steps to downgrade to Matomo 3. Please read the instructions fully before proceeding with the steps.

Please note that the downgrade process will change your token_auth. If you are using for example the Matomo HTTP API or the Matomo Tracking API this will affect you. You will need to change the token_auth in all your applications. Also some slight data conversions may occur while downgrading.

• We recommend making a backup of your code and database if any possible. If you still have a backup from before upgrading to Matomo 4, try to use the backups instead of following below steps.
• If you have a high traffic site we recommend enabling the maintenance mode.
• Download the latest version of Matomo 3.
• Extract the zip and replace the files on your server using the following instructions from the manual update process. The idea is that you basically remove all existing files except for config/config.ini.php and then copy over the new files. If you were using any plugins from the Marketplace, you will need to download them again from the Marketplace.
• Execute below queries on your database. You may need to adjust the matomo_ prefix depending on your DB table prefix.

    ALTER TABLE matomo_user ADD COLUMN alias VARCHAR(45) NOT NULL;
    ALTER TABLE matomo_user ADD COLUMN token_auth CHAR(32) NOT NULL;
    UPDATE matomo_user set token_auth = MD5(CONCAT(NOW(), UUID())), `alias` = `login`;
    ALTER TABLE matomo_log_visit ADD COLUMN config_gears TINYINT(1) NOT NULL, ADD COLUMN config_director TINYINT(1) NOT NULL;
    ALTER TABLE `matomo_log_link_visit_action` CHANGE `pageview_position` `interaction_position` MEDIUMINT UNSIGNED DEFAULT NULL;
    ALTER TABLE matomo_log_visit ADD COLUMN visitor_days_since_first INT(11) UNSIGNED NULL;
    ALTER TABLE matomo_log_visit ADD COLUMN visitor_days_since_order INT(11) UNSIGNED NULL;
    ALTER TABLE matomo_log_visit ADD COLUMN visitor_days_since_last INT(11) UNSIGNED NULL;
    ALTER TABLE matomo_log_conversion ADD COLUMN visitor_days_since_first INT(11) UNSIGNED NULL;
    ALTER TABLE matomo_log_conversion ADD COLUMN visitor_days_since_order INT(11) UNSIGNED NULL;
    UPDATE matomo_log_visit SET visitor_days_since_first = ROUND(visitor_seconds_since_first / 86400), visitor_days_since_order = ROUND(visitor_seconds_since_order / 86400), visitor_days_since_last = ROUND(visitor_seconds_since_last / 86400);
    UPDATE matomo_option set option_value = '3.13.6' where option_value like '4.0.0%';

• You can now disable the maintenance mode if you enabled it previously
• Open the Matomo UI
• You might be presented with another MySQL update changing a few more columns which you can execute either using the UI directly or on the command line should your database size be larger.
• You should now be able to use Matomo 3.

How do I send tracking requests to two or more Matomo servers?

Sending tracking requests to multiple Matomo servers is easily done using the Matomo JavaScript tracker.

The standard Matomo JavaScript tracking code contains the following lines for tracking to a single Matomo server:

_paq.push(['setTrackerUrl', u+'matomo.php']);
_paq.push(['setSiteId', YOUR_SITE_ID_HERE]); 

To add a second tracking URL to Matomo, we can add the following code below it:

var secondaryTracker = 'https://matomo.example.com/matomo.php';
var secondaryWebsiteId = YOUR_SITE_ID_HERE;

// Also send all of the tracking data to the new Matomo server
_paq.push(['addTracker', secondaryTracker, secondaryWebsiteId]);

It is not necessary to have the same Site ID in both the Matomo servers (Each tracker can have a unique Site ID for the website you are tracking)

Adding additional Matomo servers can likewise be added with the following:

var tertiaryTracker = 'https://matomo2.example.com/matomo.php';
var tertiaryWebsiteId = YOUR_SITE_ID_HERE;
_paq.push(['addTracker', tertiaryTracker, tertiaryWebsiteId]);

There is no limit to the number of trackers you can add via this method to send tracking requests to multiple Matomo servers.