Requirements
To integrate the Matomo – Google Ads Conversion Importer you need access to the following products
- Google Ads Account
- Google Spreadsheets
- Matomo Installation
- Matomo – Google Ads Conversion Importer
A paid script is required for this guide.
This guide is for customers of our script: Matomo – Google Ads Conversion Importer . If you don’t have the script, you can order it from us.
Activate Google Ads Account automatic tag marking
Google Ads’ automatic tag marking is the basis on which Matomo’s goal completions are passed on to Google Ads. This must be activated in the Google Ads account under Settings > Account settings > Automatic tag marking. Google has this detailed article on automatic tag marking.
When automatic tag marking is activated in Google Ads, Google automatically appends a query parameter to the destination URLs.
For example, https://webmasterei-prange.de/ becomes https://webmasterei-prange.de?gclid=213dkascjbsdcHBWDWDZG_=BDPSHJBC
At the time of writing this article, Google uses the query parameters gclid, wbraid, gbraid
Matomo Configuration
In this section, we’ll take care of all necessary configuration steps in Matomo.
Save GCLID as a dimension
Now that Google Ads is sending its click marking, we need to ensure that we can use it in Matomo.
For this purpose, a new dimension of the type “Action” is created in Matomo.
To do this, please go to Matomo and navigate to:
The screenshot shows how this dimension must be configured:
Set up Matomo Conversion Importer Dimension
From now on, the values of the query parameters will be stored in the dimensions. Unfortunately, a retrospective evaluation of previous data is not possible.
Create Matomo API Token
The data retrieval is then done by a Google Ads script. This requires API access to Matomo to fetch the corresponding data.
To do this, please go to Matomo and navigate to:
- Settings> Personal> Security> Authentication token
- Enter a unique description and click on “ Generate new token ”
- Copy the value now displayed into a file. You will need this later.
Configure Google Spreadsheet
Copy Spreadsheet Template
The conversions are taken from the Matomo API by our script, the attribution is calculated, and then we transfer the data to the Google Spreadsheet. The data is then imported from the Google Spreadsheet to Google Ads. So let’s take care of the spreadsheet.
- Open the spreadsheet: Open spreadsheet
- Create a copy of it under File > Make a copy
Enter values
Navigate to the second tab of the spreadsheet, “Setup,” where you’ll find all the parameters. Column A contains the parameter name, and column B contains the value.
| parameter | remark |
|---|---|
| matomo_url | Enter the Matomo URL without a slash. e.g., https://analytics.example.com |
| token_auth | Matomo API token, as configured in the previous step. |
| idSite | Value from Matomo, easiest to find in the Matomo URL. Usually, this value is 1 |
| gclid_dimension | Number of the dimension you previously created in Matomo. |
| reportDays | The period Matomo should search for conversions. If you have too many conversions for the sheet, you may need to adjust this value downwards. |
| date | deprecated field |
| conversionName | Name to which the Matomo ecommerce transaction is renamed. Required as a name in Google Ads and does not need to be adjusted. |
| activeConversionNames | Range from B9:B22 where various individual goal names can be inserted, which will be transferred to the spreadsheet. Attention! These names must be adopted 1:1 in Google Ads. |
Google Ads Script Installation
Now that data is being collected in Matomo and we have configured the spreadsheet, we only need to establish the connection between Matomo and the spreadsheet.
- Open the Google Ads interface
- Navigate to > Bulk Actions > Scripts
- Press the large + Button to create a new script.
- Name the script, e.g. “Matomo – Google Ads Conversion Importer” (see screenshot)
- Take the script as you received it from us and copy it into the spreadsheet.
- In line 6 of the script, please enter the URL of the spreadsheet that you copied earlier. (see screenshot)
- First, ignore the yellow “Authorize” button
- Press “Preview”
- A new “Authorize” button will appear. Click it and grant the necessary permissions. Tip: Google Ads users and spreadsheet editors should use the same account.
- After the authorization process, click “Preview” again. If Matomo has already collected gclid values, they should now appear in the spreadsheet.
- Press Save. You will return to the script overview.
- There you can set any time for when the conversion import should be made. A recommended time is between 4:00 and 6:00 in the morning.
Testing GCLID accesses
Often, no gclid values are present in Matomo when the script is installed. In these cases, nothing appears in the list.
To simulate traffic, you should run a few goals in Matomo, simulating access with gclid. Run a test call like https://meinedomain.de/?gclid=dasisteintest and complete a few goals on the page. After a few minutes, click “Preview” again in the script. If everything has been configured correctly, dasisteintest, the conversion name, the conversion time, the attributed credit, and the conversion value should now be listed in the spreadsheet on the “Conversion Data” sheet.
Importing Conversion Data to Google Ads
Now that we have collected data in the “Conversion Data” sheet, this data still needs to be integrated into Google Ads.
Considerations for Conversion Import
If you use multiple Google Ads accounts to advertise a site, you should consider whether it’s better to import conversion data on a Google Ads MCC (Manager Account) basis. This way, you only need one import routine.
- In Google Ads, go to Settings> Conversions> Uploads Navigate in the tabs to Schedules
- There, please press the + Button
- Select “Google Sheets” as the source and link the corresponding sheet.
- Pay attention to the yellow warning. You need to click “Share” in the top right corner of the Google Sheet and then grant the email address from the yellow warning as a “viewer.”
- Set a retrieval time. This should be later than the execution time of the script, so that we always import fresh data.
Create Matomo Conversion in Google Ads
In the last step, the conversions we import must also be present in Google Ads. The identifier here is the conversion name as used in the Google Spreadsheet. It is therefore important that the conversion name in Matomo matches the conversion name in Google Ads.
- In Google Ads, navigate to: Tools > Conversions
- Press the + button there to create a new conversion.
- Select the “Import” option
- Enter a conversion name that exactly matches the conversion name in Matomo. For e-commerce transactions, please use “Matomo Transactions” as specified in the spreadsheet as the conversion name.
- You can make all other settings as usual.
In the next step, the usual conversion settings can be made.
Attribution settings of the conversion in Google Ads
You must set the attribution settings to External Attribution, otherwise the conversion import will not work.
Timing of the import
The timing of the conversion import should be coordinated. Make sure the following things are configured in a chronological order with some leeway. If this isn’t the case, it can take up to a day for the conversions to appear in your account.
- Provision of data in Matomo (for logfile imports)
- Import by the script into the spreadsheet
- Upload of spreadsheet data to Google Ads
Control
If all steps have been carried out, the script should now transfer the conversion data from Matomo to Google Ads daily at the set time.
The conversion data should be visible in the Google Ads statistics about 4 hours after the import.
To check, you should go to Tools in Google Ads >Conversions> Click on the errors during an upload . The error message will then tell you what caused the error. Not all errors indicate a script malfunction.
