Guide: Transfer Matomo Goals as Conversions to Google Ads

Requirements

For the integration of the Matomo – Google Ads Conversion Importer, you need access to the following products

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.

Step-by-step guide ausblenden

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, a new dimension of type “Action” is created in Matomo.

To do this, please go to Matomo and navigate to:

> Websites > Custom Dimensions > Action Dimensions > Create new dimension

The screenshot shows how this dimension must be configured:

Set up Matomo Conversion Importer Dimension
Matomo Conversion Importer Dimension einstellen

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:

  • > Personal > Security > Authentication tokens
  • Enter a unique description there 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 2nd tab of the spreadsheet “Setup” where you will find all parameters. Column A contains the parameter name, column B is where the value is entered.

Parameter Comment
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.
Configure spreadsheet for conversion import
Configure spreadsheet for conversion import

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)
  • Initially ignore the yellow “Authorize” button
  • Press “Preview”
  • A new “Authorize” button appears. Press this and grant the necessary permissions. Tip: Google Ads users and spreadsheet editors should use the same account.
  • After the authorization process, press “Preview” again. If Matomo has already collected gclid values, these 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.
Navigate to the Google Ads scripts
Navigate to the Google Ads scripts
Copy the script to Google Ads
Copy the script to Google Ads
Authorize the script before the 2nd click on Preview
Authorize the script before the 2nd click on Preview

Testing GCLID accesses

Often, when installing the script, there are no gclid values in Matomo yet. In these cases, nothing appears in the list.

To simulate accesses, you should execute some goals in Matomo where you simulate the access with gclid. Perform a test call like https://mydomain.com/?gclid=thisisatest and complete a few goal intentions on the page. After a few minutes, press “Preview” again in the script. If everything is configured correctly, thisisatest, 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 are collecting data in the “Conversion Data” sheet, this data 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.

  1. In Google Ads, go to > Conversions > Uploads Navigate there in the tabs to Schedules
  2. There, please press the + Button
  3. Select “Google Sheet” as the source and link the corresponding sheet.
  4. Pay attention to the yellow notice. You need to click on “Share” in the top right of the Google Sheet and add the email address from the yellow warning as a “Viewer”.
  5. Set a retrieval time. This should be later than the execution time of the script, so that we always import fresh data.
Navigate to the Conversion Upload Schedules
Navigate to the Conversion Upload Schedules
Sharing the Google Spreadsheet
Sharing the Google Spreadsheet

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.

  1. Navigate in Google Ads to: Tools > Conversions
  2. Press the + button there to create a new conversion.
  3. Choose the “Import” option
  4. Enter a conversion name that exactly matches the conversion name in Matomo. For ecommerce transactions, please use “Matomo Transactions” as specified in the spreadsheet as ConversionName.
  5. You can make all other settings as usual.
Create conversions in Google Ads
Create conversions in Google Ads

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 that the following things are configured in chronological order with some “breathing room”. If this is not the case, it can take up to a day for the conversions to appear in the 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.

For verification, you should click on the errors in Google Ads under Tools > Conversions > Uploads for an upload. You can then see the cause of the error based on the error message. Not all errors indicate a malfunction of the script.

Control of completed uploads
Control of completed uploads
Control of individual imports within an upload
Control of individual imports within an upload