Migrate from Google Analytics 3 (Universal Analytics) 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=UA-siteid"></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 GA, you find custom dimensions in the Admin area.

Select the property you want to migrate and then go to Custom Definitions > Custom Dimensions.

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.

Tracking a value for a custom dimension in Matomo is pretty similar to how it’s done in GA. Instead of using ga('set', 'dimension1', dimensionValue); you use _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 ga(‘send’, ‘event’, …); in your website. GA uses the following format:

ga('send', 'event', [eventCategory], [eventAction], [eventLabel], [eventValue], [fieldsObject]);

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

If you have any sites that you want to track ecommerce for, you need to first make sure that you have ecommerce enabled on each desired site. In a GA property you have to go to Admin > View > Ecommerce Settings.

In Matomo you have to go to Administration (gear icon) > Measurables > Manage and find the site that you want to check.

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": [
    {
      "id": "0123456789",
      "name": "Ecommerce Analytics Book",
      "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": [
    {
      "id": "01234567890",
      "name": "Ecommerce Analytics Book",
      "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": [
    {
      "id": "01234567890",
      "name": "Ecommerce Analytics Book",
      "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.

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.