Import Google Search keywords in Matomo

The Search Engine Keywords Performance premium feature enables Matomo to import search keyword data from Google Search Console. You can combine keyword data with Matomo analytics reports to analyse which queries drive impressions, clicks, and traffic to your website.

This premium feature is available in Matomo Cloud using Quick Connect. Read the Quick Connect guide for a faster and easier keywords import to Matomo Cloud. If using Matomo On-Premise, you can purchase the plugin on the Matomo Marketplace.

For On-Premise installations and Cloud instances with high-traffic websites, follow the steps below for the advanced Google OAuth Client Configuration.

Before you start

To use the Search Engine Keywords Performance, first set up Google Search Console and verify your website before completing the following steps covered in this guide:

1. Create the Google OAuth Client config to get your OAuth config.
2. If using Matomo for WordPress, go to WP Admin Dashboard > Matomo Analytics > Reporting to access the Matomo dashboard.
3. Once the Google OAuth Client is set up, login to Matomo as a Superuser.
4. Navigate to Administration > System > Search Performance.
5. Below Google Search Console, click Setup Configuration.
6. Upload the OAuth credentials.
7. In the Connect Google Account(s) section, click Start oAuth process.
8. Now you can configure your websites to import keywords in Websites (or Measurables) > Manage.

Create the Google OAuth Client Config

Continue with these setup steps for the Advanced Google OAuth client configuration.

You do not need to submit your application to Google for verification at any point in this process. If Google prompts you to submit the app and you cannot cancel or decline the request, it usually indicates a missed step or added information that triggered Google’s verification workflow. Review this guide carefully.

If at any time you need to make changes to the OAuth Configuration,download the new OAuth Client credentials and upload them to Matomo for the changes to work. Follow these steps to get your OAuth Client Config and use the Matomo Google Search Integration:

1. Create a project in Google Cloud Console

1. Sign in to the Google Cloud Console and open the project selector.
   
2. Click the New Project option.
3. Provide a project name (for example, SearchKeywords) and click Create.
4. A notification will appear. Click Select Project to open the new project.
5. After your project has been created, it will automatically open the project.

2. Enable the Google Search Console API

1. Open the main Google Cloud menu and go to Products – APIs & Services.
   
2. Click Library and search for ‘Google Search Console API’.
3. Select the API and on the product details page, click Enable.

3. Setup the OAuth consent screen

1. Open the Google Cloud menu and go to Products – APIs & Services > OAuth consent screen.
2. Click Get started to go through the project configuration wizard.
3. Enter the App Information (name and email) and click Next.
4. Select the Audience: Internal or External. If you create an External app, it will start in testing mode; if you create an Internal app, you do not need to submit the app for verification.
   
   • Internal apps do not have a 7 day expiry time and you only have to authorise Matomo once. Note that internal apps are only available to users that have purchased Google Workspace to run imports from Google Analytics.
   • External apps can be created by anyone. For most cases, we recommend creating a published, external app to ensure import works seamlessly. If you do not publish it, Google limits authorisation to seven days. After that, the authorisation expires and you must manually re-authorise Matomo every seven days until the import finishes.
5. Complete the required details and click Create.
6. Go to OAuth Overview > Audience to add Test users.
7. Click Publish App under Publishing Status.
8. In the popup, click Confirm to push to production.

4. Create the OAuth client

1. In the OAuth Overview, click Create OAuth Client.
2. Select Web Application as the Application Type.
3. Set a name for the application, for example Matomo at https://matomo.my-website.example.
4. 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/).
5. 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=SearchEngineKeywordsPerformance&action=processAuthCode added at the end.
   For example: https://matomo.my-website.com/index.php?module=SearchEngineKeywordsPerformance&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=SearchEngineKeywordsPerformance&action=processAuthCode
Note: The URL for Matomo does not have to have a subdomain, that is just an example.

1. Once you have entered the two URIs, click Create to finish creating the OAuth Client Credentials.
2. You will 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 client 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.

You might still get 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)

You’re all set! Your Google keywords will be imported in the new Matomo Search Keywords report.

If you experience issues connecting Google Search Console to Matomo, check the website has been verified in Google Search Console and the correct Google account was selected.

You can also review the troubleshooting FAQs for additional solutions to common connection and authentication issues.