The Google Analytics Importer plugin imports Google Analytics reports into a Matomo instance.
When you run an import, your Google Analytics (GA) Property will be automatically created as a Website into Matomo (as well as your Goals and Custom dimensions) and all historical reports in GA will be imported so you can view all your web analytics data in Matomo.
Note: Currently the importer plugin only supports Google Analytics properties starting with
UA-. The plugin does not at present support newer Google Analytics properties where the property ID starts with a
G. We are working to add support for these new property IDs.
For Matomo On-Premise and Matomo for WordPress:
- At least Matomo 3.12.0 is required to use the Google Analytics importer.
- PHP configuration needs to allow the use of the functions
- Your server must allow the execution of the CLI PHP from within a web request and must have
- Your Matomo instance should have cron archiving setup.
- Proceed to install the Google Analytics Importer plugin in your Matomo by following these steps.
Note: In some cases, the plugin does not work for servers running on Windows, we are investigating this and will provide a fix soon.
For Matomo Cloud
- Our cloud hosted service meets all the requirements automatically.
Before we can start exporting Google Analytics data from their API and importing it into your Matomo, there are two setup steps to go through: 1) Creating Google OAuth Client Config and 2) Authorizing Matomo to export your Google Analytics data. These two steps need to be done only once.
1) Optional: Purchase a temporary Google Workspace account
This step is not required, but makes the process of importing easier.
There are two types of Google projects that can be defined in the Google API Console: external and internal.
External apps can be created by anyone, but Google places a limit on the amount of time API authorizations can be used: after a week they will expire. Using this type of app, you will have to manually re-authorize Matomo every week in order for your imports to continue running. It’s unfortunate, but Google creates this policy and we don’t have a way around it.
Internal apps, on the other hand, do not have this limitation. Using an internal app you will only have to authorize Matomo once, BUT, internal apps are only available to users that have purchased Google Workspace. If you’d like to avoid the inconvenience of having to regularly re-authorize Matomo, it is advised to purchase an account for however long you need to run imports from Google Analytics.
2) Creating Google OAuth Client Config
Important note before we start: At no point during these steps will you be required to submit your ‘app’ to Google for verification. If you are prompted to submit your ‘app’ and do not have the option to click no or cancel, then please review the steps in this guide again to ensure that you have not missed an important step, or added additional information where not necessary.
Follow these steps to get your OAuth Client Config:
Sign in to the Google API Console
Click Select a project in the menu.
To create a new project click the “New Project” button in the overlay:
Give your new Project a useful name (for example
Matomo Google Analytics Importer).
After your project has been created, select it manually in the project list and click “open”.
Click on Library in the menu on the left, then search for Google Analytics API, and click on the item Google Analytics API. Then on the description page of this API, click the Enable button.
Do the same for the Google Analytics Reporting API.
Next we need to setup the OAuth Consent Screen. Click on the Google logo at the top to get back to the dashboard, afterwards click on OAuth Consent Screen in the left menu. If you have a Google Workspace account, select Internal. Otherwise, select External. Then click Create.
Choose a name for your app, then click Add Domain and add the top level domain of your matomo instance e.g. matomo.cloud
Select your email address from the drop down menu under User support email, and fill in your email address for Developer contact information
Important note: Do not upload an App logo here, doing so will require you to submit your ‘app’ to Google for verification which can take several months to complete.
Click Save and Continue and then click Add or Remove Scopes
Select the “Google Analytics API” scope with the
readonlyproperty and click Update then click Save and Continue
Next, we need to add Test Users in order to allow access to the Google Analytics API Scope.
Click Add Users and enter the email address you will be using to access the Google Analytics Data.
Click Save and Continue and then click Back to Dashboard
Go to the Credentials tab on the left menu
Click Create Credentials
Select OAuth Client ID
Select Web Application as the Application Type
Set a name for the application, for example
Matomo at https://matomo.my-website.example
Note: This needs to be a domain. If you have installed Matomo into a subdirectory, you need to enter the domain without the path. (so
https://my-website.examplein case of
Click on Add URI under Authorized redirect URIs. This needs to be set to your Matomo URL with this special URL/query
/index.php?module=GoogleAnalyticsImporter&action=processAuthCodeadded at the end. For example:
Note: the URLs above are HTTPS: we highly recommend you run your Matomo instance over SSL. If your Matomo doesn’t support https yet, you can replace the URL and use http.
If you are using Matomo for WordPress: the URL must begin with the entire path to Matomo’s admin page, eg,
Note: that the URL for Matomo does not have to have a subdomain, that is just an example.
Once you have entered the two URIs, click Create to finish creating the OAuth Client Credentials
You will now be presented with the OAuth credentials that were just created, you can click Ok to close this dialog, and then download your OAuth client credentials by clicking the download icon on the credentials overview page. (Note: if you change any settings above at a later point for example to fix a typo in one of the values, you will need to download the OAuth credentials again and re-upload it in Matomo.)
The steps in creating your OAuth Client Configuration are now complete. The ‘app’ that has been created during this process can remain as a ‘Testing’ or ‘Test Phase’ app without any need to submit it for review.
At no point during these steps would you have been required to submit your ‘app’ to Google for verification. If were prompted to submit your ‘app’ and did not have the option to click no or cancel, then please review the steps in this guide again to ensure that you have not missed an important step, or added additional information where not necessary.
You may still receive a warning from Google when completing the OAuth process saying “Google hasn’t verified this app”.
In this case, you can safely continue by clicking on “Advanced”, and then “Go to matomo.cloud (unsafe)” or “Go to yourdomain.com (unsafe)”
3) Authorizing Matomo
Once you have downloaded your OAuth client credentials, you can authorize your Matomo to have access to your Google Analytics data:
Login as a Super User in Matomo and go to Administration.
In the left menu, click on System and then Google Analytics Import. If you are not seeing this menu, make sure you have installed the GoogleAnalyticsImporter plugin.
Upload the OAuth client credentials you downloaded in How to set up Google OAuth Client config by clicking Configuration File, selecting the file, and clicking Save.
Important note: If you selected External when configuring your Google project, you may have to regularly re-authorize Matomo. Google makes sure authorizations for test users in External projects expire in seven days, at which point your imports will fail and you will have to re-authorize Matomo. Unfortunately, the only way around this is to temporarily purchase a Google Workspace account and make your project Internal.
Running the Google Analytics import
Once you’ve authorized Matomo, you can begin importing data. This is primarily done through the admin page, though you can use the command line as well. Depending on how much data you are importing it can take a long time to finish (more than one day in most cases).
Note: Google imposes a daily limit on the number of API requests you can make each day (at most 50,000). The import will hit this limit after importing about 4 months of data where every day has data. This takes just a couple of hours. This means the import has to be run over several days until the entire data set is imported.
Using the admin page
To use the admin UI:
- Go to the Google Analytics Import admin page.
Fill out the Schedule an Import form and click Start:
As the import continues, you will be able to monitor progress through the Import Jobs table below:
Refresh the page to get an updated status at any time.
Once the import is marked as finished, feel free to delete the status. If an import fails, you can view the logs located in
/path/to/your/matomo/tmp/logs/. There should be one for each job.
Using the Command Line
You can also run the import on the command line if you’d like to see more information about it’s progress as it’s going:
- First you’ll need some information. In your Google Analytics dashboard, open the property selector.
- Take note of the Property ID and the View ID for the property/view you want to import.
sshinto your Matomo instance
- Run the following commands to import your site:
$ cd /path/to/my/matomo
$ php ./console googleanalyticsimporter:import-reports --property=<property-id> --view=<view-id> --dates=<dates>
view-idsubstitute the GA property ID and view ID you noted above. For
datesspecify the date range of date you’d like to import, for example,
Then just wait until the import finishes, which could take some time.
If you would like to resume an existing import, supply the
--idsite=<idSite> parameter with the site that was created for this import (this will be in the import status table in the admin page).
Once the import finishes, you can remove the authorization you granted earlier. Matomo only needs access to Google Analytics while importing data, afterwards there’s no point in keeping it there.
Importing a Mobile App Property
If your GA property is for a mobile app, then you will need to check the
Mobile App checkbox before starting your import:
This will ensure that Matomo imports the correct data. The Screen Views metric in Google Analytics will be imported and used as the Pageviews metric in matomo. The Screens reports will be imported into the Page Titles reports in Matomo.
If you don’t check this box and your property is for a mobile app, the importer will ignore this data.
Importing Unsupported GA Dimensions
Some GA dimensions do not exist in Matomo, such as the demographics dimensions. You may want to hold onto this information when importing, and it is possible to do so by importing the data into a custom dimension.
In the import form, fill out the “Extra Custom Dimension Mappings” field with the GA dimensions you’d like to import:
Use this list to find the proper IDs for GA dimensions.
When importing, one custom dimension slot will be used up in the imported site for each extra mapping. (Note: there will be an error if there are not enough custom dimension slots in your Matomo.)
After your import
After you finish importing data into Matomo it is a good idea to back up your Matomo’s database. If the imported report data were to be purged or somehow deleted, you would have to re-import the data from GA. And if your GA property has been deleted, the data will be gone forever.
If you regularly backup your database (or your host does it for you), then you don’t really need to worry about this.
Workflows for Switching From Google Analytics
There are a couple ways to use the importer to retain your Google Analytics data when switching to Matomo. This section details possible workflows you can use.
Setup tracking to your matomo and import into a site with an end date
This is the simplest approach in terms of setting up and monitoring. To do it, Start importing your old data and set the end date to the day you start tracking with Matomo (today’s date for example), use the tracking code from the newly created site and start tracking.
Make sure there’s no overlap in the import end day and the day you start tracking. So, for example, if you start tracking on November 12th, make sure the import end date is November 11th.
Then end your tracking with GA whenever you’re ready to. This solution is also explained in more details in the Migrating from Google Analytics FAQ.
Import into a site and let the import continue until you are ready to stop tracking into GA
Another option is to have an ongoing import into your Matomo while still tracking into GA. For this approach you would start an import without specifying an end date. This will cause the import to just keep importing every day.
When you are ready to switch to Matomo, you can manually cancel the import and start tracking into Matomo (make sure you are ready to start tracking before you cancel the import, since if it takes a couple days for you to setup, those days won’t have data in Matomo). Then you can stop tracking into GA.
This approach could be useful if you are evaluating Matomo but are not ready to invest time in setting up tracking to your Matomo.
My import never continues
When you start an import the plugin will start importing in the background. Eventually, if you’re importing a large enough amount of data, it will be rate limited and will be forced to continue the next day. The continuation is done through a scheduled task.
In order for the scheduled task to run you first need to have cron archiving setup. This is where scheduled tasks are initiated.
Once you have cron archiving setup, use the TasksTimetable plugin to determine when the scheduled tasks will next run (the relevant tasks will have
Piwik\Plugins\GoogleAnalyticsImporter\Tasks in the name).
If these tasks never run, even if they are listed, then something is failing in the cron archiving command. The next step to debug is to check the output of the command.
My import runs for X minutes and then just stops
If you are using shared hosting it is possible that your hoster is simply terminating the process after a set amount of time. This isn’t something either Matomo or you can fix. You will either have to talk to your hoster or find another way to host Matomo.
If neither of those options work for you, you can try the following workarounds:
Try importing data through the CLI command instead of through the UI. When you do this, make sure the PHP executable you are using is the CLI php version instead of another (for example, php7-cli vs php7-fcgi). You can see which version it’s using by running
php --version. Look for output like
PHP 7.2.1 (cli). It’s possible your hoster will allow CLI PHP executions to run for longer.
If the process is reliably terminated after a certain amount of time, you can setup a cron job to restart the import. For example, if your import is terminated after 15 minutes, you can setup a cron to run every 20 minutes that will resume the import. To do this, start the import in the UI and make note of the ID of the newly created site. Then add a cron using the
googleanalyticsimporter:import-reportscommand with the
php /path/to/matomo/console googleanalyticsimporter:import-reports --idsite=<your Site ID>).
My import fails every time on the same day
If your import fails regularly for a specific day, you may have found a bug in the import process. In this case you should file a bug report at the github repository. To help us find the cause more quickly, please do the following things when filing your report:
- Start a new import for the specific day that fails and check the “Enable Verbose Logging” checkbox at the bottom of the form:
- When the import experiences the error again, find the log file on your server for the import (it will be named something like
/path/to/your/matomo/tmp/logs/gaimportlog.$idSite.$matomoHost.log). Email it to us at firstname.lastname@example.org (it’s probably a good idea not to post the contents with your bug report as it may contain information about your server).
- Cancel the import.
This will help us debug the issue you are experiencing, though we may still not be able to find a cause. In this case, if you are able to provide read only access to your Google Analytics account, we will be able to further debug the problem.
Not all data in Google Analytics is accessible through the API, please find below the list of data reports that will not show up in Matomo:
- The importer only imports aggregated report data, not the raw visit and action data. This means the Visitor Log,
Ecommerce Log and Segmentation features will not work for imported reports.
It also means that the Unique visitors metric and users metric for non-day periods (such as weeks and months periods) will not be available.
- Some reports in Matomo are not supported in Google Analytics, such as the “Search Keywords with No Results” and Contents reports. These reports will not show data after import.
- Some reports from Google Analytics are not yet imported into Matomo (such as Funnels reports). If you find any missing report in Matomo you expected to see imported, please let us know the details in this issue tracker.
- Google strips the search parameter from internal site search URLs, but shows those URLs in the page URLs reports. This means when we import that report, we can’t tell if one of those pages was actually an internal site search, so in imported reports site search page URLs will be included in the Page URLs and Page Titles reports.
- Google’s ecommerce conversion rate is different from Matomo’s. Google defines this as the number of transactions per session, where Matomo defines it as the percent of visits that have at least one order. So this metric cannot be imported.
- Exit and entrance rates in Google are different than in Matomo. Matomo defines the entrance/exit rate as the percent of times a page URL/page title was the first/last pageview in a visit. In Google Analytics, the rates are defined as the percent of all hits for which a page URL/title is the first/last pageview in a session. So the rates will look different in Matomo.
- Additionally, Google Analytics doesn’t always set the session count when logging pageviews (see their docs for more info). This means some sessions won’t be counted by Google Analytics, and the session count could be lower than it should be for some actions. In this case, the exit/entrance rate will be calculated as > 100%. This doesn’t affect Google Analytics, because the entrance/exit rate there is calculated using the total number of hits and not the number of sessions.
- Product reports are missing the product conversion rate and visits metric, since sessions cannot be queried with product dimensions through the Google Analytics API.
- The importer assumes you have setup GeoIp2. If you don’t, the data will be imported properly, but the reports will display many Unknown regions, until you install GeoIp2.