Migrate from Google Analytics 4 to Matomo
Welcome to the data-compliant analytics world with Matomo! We are delighted that you have decided to migrate to our analytics tool, and we are here to help you every step of the way. In this guide, we will provide you with all the necessary information to ensure a seamless migration and get you started with Matomo. Should you have any questions or require additional assistance, our community forums and support team are always available to assist you.
Getting started
The first thing that you need to decide is whether you want to copy your existing tracking information from GA into Matomo, because this will determine whether you need to manually create a Matomo site for each GA property. When you use the plugin import a property from GA, a site will automatically be created to associate all of your visit data to.
Site creation
If you want to import your existing reports and custom dimensions from GA into Matomo, you can use the GA Importer plugin and it will automatically create your site for you. For more information, check out the guide.
If you’re not importing report data from GA, you’ll probably want to start by creating a Matomo measurable or site for each property you have in GA. Just as each GA property has its own tracking code, each Matomo measurable has one. To create a new site in Matomo, you can either:
Click on the All Websites menu item in the top navigation bar and click the Add a new website link at the bottom of the list of websites.
Go to Administration (gear icon) > Measurables > Manage and click the Add new measurable button.
There is a good FAQ that details site creation.
Tracking code setup
You’ll want to locate the Google tracking code in the header of your site and replace it with the install code for Matomo.
The GA tracking code will most likely look something like the following:
<!-- Global site tag (gtag.js) - Google Analytics --> <script async src="https://www.googletagmanager.com/gtag/js?id=G-measurementId"></script>
You’ll probably also want to remove the following from the header of your site:
<script>
window.dataLayer = window.dataLayer || [];
function gtag(){dataLayer.push(arguments);}
gtag('js', new Date());
gtag('config', 'G-measurementId');
</script>
The Matomo install code can be found under the Administration (gear icon) > Measurables > Tracking Code.
Most people use the JavaScript tracking code, but there are other options available as well, such as image tracking.
There is a more in depth guide regarding tracking data.
Custom Dimensions setup
If you have custom dimensions setup in GA, you will most likely want to migrate those over. If you use the GA Importer plugin, they should automatically be created. If not, you’ll probably want to create them manually.
In GA4, you find custom dimensions in the Configure navigation menu option.
Then select the Custom definitions menu option.
It’s important to keep in mind that both Google and Matomo limit the number of custom dimensions you can have and that Matomo doesn’t allow quite as many. By default, Matomo allows up to 5 visit custom dimensions and up to 5 action custom dimensions, but there is a way to allow more if necessary. Also, keep in mind that there isn’t currently a way to delete a custom dimension inside the Matomo application.
To create a custom dimension in Matomo, go to Administration > Measurables > Custom Dimensions.
GA4 uses event parameters as custom dimensions and doesn’t allow manually setting the dimension as part of the request, like GA3 did. Matomo works much like GA3, but instead of using ga('set', 'dimension1', dimensionValue); it uses _paq.push(['setCustomDimension', 1, 'dimensionValue']);
This code and other options are displayed when you edit an existing custom dimension.
Once you have created a custom dimension, it will become available in its respective area within the Matomo Dashboard; visit type in Visitors and action in the Behavior section. Also, they will become available in the Custom Reports section.
The process of creating a custom dimension is well documented in this FAQ. For more general information, there is a good custom dimensions guide available.
Events setup
Events are most convenient to set up using Matomo Tag Manager, but you can set them up using JavaScript code as well. If you’re currently using Google Tag Manager, you’ll most likely want to use Matomo Tag Manager. There’s a migration FAQ specific to migrating tags.
If you are using direct JavaScript tracking with GA, you’ll need to find all of the occurrences of gtag(‘event’, [event_name], …); in your website. GA4 uses the following format:
gtag('event', [event_name], {
'parameter_name1': 'parameter_value1',
'parameter_name2': 'parameter_value2',
...
});
You’ll need to replace that using the following format:
_paq.push(['trackEvent', [category], [action], [name], [value]]);
So, the main change is the function name and that Matomo passes all of the values inside of an array instead of as individual arguments.
There’s a FAQ that provides more information about both methods of tracking events. There’s also a more generalized event tracking guide.
Ecommerce tracking setup
In GA3, you had to enable ecommerce before you could start tracking those kind of events, but that’s enabled by default in GA4. Similar to GA3, in Matomo you have to explicitly enable ecommerce first. To do so, go to Administration (gear icon) > Measurables > Manage and find the site that you want to confirm has ecommerce is enabled.
If ecommerce is enabled, the card should have ECOMMERCE: Yes on it.
If not you need to enable it by clicking on the edit icon on the site card.
Once in edit mode, scroll down till you see the Ecommerce drop down and make sure that Ecommerce enabled is the selected option.
If you use a content management system or ecommerce platform, locate it in the list of integrations and follow the instructions specific to the one that you use. If you can’t find the right one or you prefer to manually integrate using JavaScript, that’s an option too. For example, if you’re tracking a product view in GA like this:
gtag('event', 'view_item', {
"items": [
{
"item_id": "0123456789",
"item_name": "Ecommerce Analytics Book",
"item_category": "Books",
"price": '9.99'
}
]
});
You would replace it with something like the following to track it in Matomo:
_paq.push(['setEcommerceView',
"0123456789", // (Required) productSKU
"Ecommerce Analytics Book", // (Optional) productName
"Books", // (Optional) categoryName
9.99 // (Optional) price
]);
You’re probably tracking when products are added to the cart using something like this:
gtag('event', 'add_to_cart', {
"items": [
{
"item_id": "01234567890",
"item_name": "Ecommerce Analytics Book",
"item_category": "Books",
"quantity": 1,
"price": '9.99'
}
]
});
You will want to replace that with Matomo code like this:
_paq.push(['addEcommerceItem', "01234567890", // (required) SKU: Product unique identifier "Ecommerce Analytics Book", // (optional) Product name "Books", // (optional) Product category 9.99, // (Recommended) Product Price 1 // (Optional - Defaults to 1) Quantity ]);
You’ll also want to replace the order that probably looks like:
gtag('event', 'purchase', {
"transaction_id": "000123",
"value": 10.99,
"tax": 1.5,
"shipping": 1,
"items": [
{
"item_id": "01234567890",
"item_name": "Ecommerce Analytics Book",
"item_category": "Books",
"quantity": 1,
"price": '9.99'
}
]
});
You can replace that with something like:
_paq.push(['trackEcommerceOrder',
"000123", // (Required) orderId
10.99, // (Required) grandTotal (revenue)
1.5, // (optional) tax
1 // (optional) shipping
]);
Note how GA has the collection of items while Matomo doesn’t, because Matomo automatically includes any products that were added to the order.
The ecommerce guide provides some good background about how Matomo handles ecommerce tracking.
Conversions and goals
GA3 had goals, but GA4 uses conversion events instead of goals. Matomo is more like GA3 in that it uses goals to track conversions. You can set those up by selecting the Goals option from the main navigation bar on the left:
You can then select the Manage Goals option:
From there, you can setup your goals much like you would in GA3. There’s also quite a bit of information in the Goals topic guide if you need more guidance.
If you use Matomo Tag Manager (MTM), you can use a Matomo event tag to manually trigger a goal. If you don’t use MTM but still want a way to more directly trigger a goal, you can use the JavaScript API to do so, using the following format:
_paq.push(['trackGoal', idGoal, [customRevenue]]);
For more information about that, you can check the developer documentation.
Finishing up
Those are the basics, but there’s a lot more that you can learn and do when dealing with Matomo. A good place to start is the Getting started guide.