Setting up a Google Analytics Import (GA3 / GA4)

Your Matomo instance needs access to a Google API to import your Google Analytics data. The API is the Google Analytics Reporting API and there are several options for how to setup access for Matomo.

One way to authorize Matomo to access your data is to set up a Google App – you do this by creating a Google OAuth Client Config. When you are creating this Config you can choose from two types of apps in the Google API Console: external or internal.

External apps

External apps can be created by anyone. In most cases, we recommend creating a published, external app to ensure import works seamlessly. If you don’t want to or cannot publish the app you can still proceed. However, for unpublished apps Google places a limit of 7 days from authorization, after which the authorization will expire. You will have to manually re-authorize Matomo every 7 days until your import is complete.

Internal apps

Internal apps do not have a 7 day expiry time. 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 have a Google Workspace subscription you can use an internal app to run imports from Google Analytics.

Creating Google OAuth Client Config

Important note: 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:

1. Sign in to the Google API Console

2. Click Select a project in the menu.
   

3. To create a new project click the “New Project” button in the overlay:
   

4. Give your new Project a useful name (for example Matomo GA Import).
   

5. After your project has been created, select it manually in the project list.
   

6. 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.

   
   
   

   
   
   

   

7. Do the same for the Google Analytics Reporting API.

8. Do the same for the Google Analytics Data API only if you want to migrate Google Analytics 4 data.

9. Do the same for the Google Analytics Admin API only if you want to migrate Google Analytics 4 data.

10. Next we need to setup the OAuth Consent Screen. Click on Menu icon next to the Google logo at the top and navigate to APIs & Services > OAuth Consent Screen in the left menu. If you have a Google Workspace account, select Internal. Otherwise, select External. Then click Create.
    
    
    
    

11. Choose a name for your app, then click Add Domain and add the top level domain of your matomo instance e.g. matomo.cloud

    

12. 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.

    

13. Click Save and Continue for both the Scopes and Test Users steps.

14. On the Summary step click Back to Dashboard

15. If you previously set the app type to “Internal” then you do not need to set the application status to “Published” here and can skip step 15 & 16
    On the dashboard, click Publish App under Publishing Status
    

16. Verify that the popup says “You do not need to submit your app for verification” and click Confirm
    

17. Go to the Credentials tab on the left menu

18. Click Create Credentials

19. Select OAuth Client ID

    

20. Select Web Application as the Application Type

21. Set a name for the application, for example Matomo at https://matomo.my-website.example

22. Click on Add URI under Authorized JavaScript origins and set it to your Matomo URL domain for example: 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.example in case of https://my-website.example/matomo/)

23. 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=processAuthCode added at the end. For example: https://matomo.my-website.com/index.php?module=GoogleAnalyticsImporter&action=processAuthCode
    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, http://mysite.com/wp-content/plugins/matomo/app/index.php?module=GoogleAnalyticsImporter&action=processAuthCode
    Note: that the URL for Matomo does not have to have a subdomain, that is just an example.

    

24. Once you have entered the two URIs, click Create to finish creating the OAuth Client Credentials

25. You will now be presented with the OAuth credentials that were just created. Click on DOWNLOAD JSON to download the OAuth credentials.
    (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.
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)”

Authorizing Matomo

Once you have downloaded your OAuth client credentials, you can authorize your Matomo to have access to your Google Analytics data:

1. Login as a Super User in Matomo and go to Administration.

2. 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.

3. Upload the OAuth client credentials you downloaded in How to set up Google OAuth Client config by clicking Upload and selecting the file.
   

4. Now, click Authorize and follow the prompts to give Matomo access to your Google Analytics data.
   

5. Click Continue and to authorise your app if prompted by Google.
   

Important note: If you selected External when configuring your Google project and haven’t published the App, 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.