Matomo Analytics server-side configuration
In this tutorial, you'll configure the Matomo Analytics tag developed by our partner Data Marketing School (opens in a new tab) and available in the Google Tag Manager Server-Side gallery.
You'll discover the configuration steps for sending various events to Matomo, such as page views, actions, goals, outlinks, site search and e-commerce events. We'll also explain how to configure custom dimensions and heartbeat requests.
But first, we'll start by importing the tag into your GTM Server-Side container.
Import Matomo Analytics tag
Search in gallery
On your GTM Server-Side container, go to Templates > Tag Templates > Search Gallery.
Add tag
Search the gallery for the Matomo Analytics tag from Data Marketing School.
Then click on Add to workspace in the top right-hand corner.
Configure the Matomo Analytics tag
Now that the Matomo Analytics tag is imported, it's available when you try to create a new tag.
Select the recently imported tag from the gallery.
To configure the tag, two pieces of information are required:
- The Site ID on which to send data](/find-matomo-site-id)
- The Auth Token enabling communication with the Tracking API](/find-matomo-auth-token)
Once you've retrieved the auth token and site ID, you can move on to the next step and start configuring the tag.
Tag presentation
If you've already set up server-side tags you're probably used to creating a single tag and triggering it on several events at the same time. This is the case, for example, with Addingwell's Meta Conversion API tag.
The Matomo Analytics tag works slightly differently: you'll need to create a new tag for each event you want to send to Matomo.
Client Type
Here you have to choose between the GA4 client and the Matomo client. If this is your very first server-side configuration you're most likely using the GA4 client.
Matomo Instance URL
If you're using Matomo Cloud, your instance URL will look like this: https://<your_subdomain>.matomo.cloud.
Auth Token
Enter here the auth token retrieved from your Matomo instance settings.
Site ID
Enter here the site ID retrieved from your Matomo instance settings.
If you have only one site on Matomo, it's very likely that the site identifier is 1. If you have several sites, enter the identifier of the site to which you want to send the data.
Event Type
The type of event you wish to send to Matomo.
Here you can choose between:
- Page View
- Actions
- E-commerce Tracking
- Content Tracking
- Heartbeat
We're going to detail all the configurations for each type of event.
Page views
In Matomo, page views are used to measure user activity on a website. They track the number of times a specific page has been viewed, helping to understand which pages are most popular, how long users spend on each page, and how they navigate from one page to the next.
To send page views to Matomo, you need to fill in the following fields:
Then trigger this tag when the client name is GA4 and the event name is page_view.
=> Check page view received data
Actions
In Matomo, an action represents any significant visitor interaction with your website. It's a broader concept than the simple page view, capturing a wide variety of interactions.
Types of actions in Matomo:
- Page views: every page visited by a user is counted as an action.
- Events: specific actions you want to track, such as clicking a button, playing a video, etc.
- Goals: achievement of a predefined goal, such as making a purchase, subscribing to a newsletter, sending a form, etc.
- Outlinks: where your users go after leaving your website.
- Downloads: your audience's interest in your downloadable content.
- Site search: identify your visitors' intentions.
Events
Events in Matomo are specific actions you want to track on your website. They enable you to get more details about what your visitors do between two page views (this could be a scroll, a button click, etc.).
In short, with events you can track any metrics you like, giving you more freedom. Events generally represent micro-conversions; prefer goals for macro-conversions.
For each event you wish to track, you must create a new tag, select Actions as Event Type and then Event as Action Type.
Event Category (Required)
The event category corresponds to the type of event you wish to track.
Event Action (Required)
The action taken by the user during this event.
Event Name (Optional)
The name of the event, you can put here, for example, the title of the element with which there was interaction.
Event Value (Optional)
Here you can enter the value associated with the event (if any).
You can then trigger this tag on the GA4 event of your choice.
Goals
Goals in Matomo are the larger actions (macro-conversions) that your visitors perform on your website, such as submitting a quote request form or purchasing a product.
For each goal you wish to track, you need to create a new tag, select Actions as Event Type and then Goal as Action Type.
Goal ID (Required)
You can find your Matomo Goal IDs by following this tutorial.
Goal Revenue (Optional)
The value associated with the goal (if any).
Links
Outlinks in Matomo let you know where your visitors go after they leave your website.
For each outlink or download you wish to track, you need to create a new tag, select Actions as Event Type and then Link as Action Type.
Link URL (Required)
The URL of the outlink or downloaded file.
Link Type (Required)
- Link: for an outlink
- Download: for a download
Download tracking in Matomo lets you measure the number of times your visitors download files from your website.
This allows you to study the performance of your downloadable content (PDFs, images, software, etc.).
=> Check outlinks and downloads received data
Site search
Site search enables you to analyze the terms your visitors use to find information on your website.
Among other things, this enables you to:
- understand the user's needs
- improve and personalize their experience
- identify gaps/holes in your content
For each search you wish to track, you need to create a new tag, select Actions as Event Type and then Site Search as Action Type.
Keyword (Required)
The keyword searched for on your website.
If you leave this field empty, the tag will default to the search_term parameter in the event data if available.
Category (Optional)
The search category (if any).
Number of results (Optional)
The number of search results.
=> Check site search received data
E-commerce
E-commerce tracking allows you to track your visitors' purchasing path.
What data can you track?
- Products viewed and added to cart: Which products and product categories are most attractive to your visitors?
- Conversion rate: What percentage of visitors make a purchase?
- Revenue per visit: What is the revenue generated by each visit?
- Traffic sources: Where do your customers come from (social networks, search engines, etc.)?
For each type of e-commerce event you wish to track, you must create a new tag, select E-commerce Tracking as Event Type.
Category views
Category views represent the number of times a specific product category has been viewed. It's an indicator that allows you to track your visitors' interest in different sections of your catalog.
Category (Required)
The category of products visited.
If you leave this field empty, the tag will default to the item_category parameter of the first product in the items array if available in the event data.
=> Check category views received data
Product views
Product views represent the number of times a specific product has been viewed. This indicator enables you to track your visitors' interest in different products in your catalog.
Category (Required)
The category of products visited.
If you leave this field empty, the tag will default to the item_category parameter of the first product in the items array if available in the event data.
Product SKU
The product identifier.
If you leave this field empty, the tag will default to the item_id parameter of the first product in the items array if it is available in the event data.
Product Name
The product name.
If you leave this field empty, the tag will default to the item_name parameter of the first product in the items array if it is available in the event data.
Product Price
The product price.
If you leave this field empty, the tag will default to the price parameter of the first product in the items array if it is available in the event data.
=> Check product view received data
Cart updates
Abandoned carts are a key indicator in e-commerce analysis. Matomo enables you to track these carts and understand why customers don't complete their purchases.
In Matomo, every cart update will be considered an abandoned cart as long as there is no order within the same visit.
Items
Table containing all items currently in the shopping cart.
If you leave this field empty, the tag will use the items parameter by default if it is available in the event data. This items array must contain at least the item_id key.
Here you can't trigger the tag on GA4's add_to_cart or remove_from_cart events because you need to provide an array containing the current state of the cart, not the products that need to be added or removed.
We advise you to edit your Data Layer and use a custom cart_update event.
window.dataLayer = window.dataLayer || [];
dataLayer.push({
event: "cart_update",
ecommerce: {
value: 2.99,
items: [{ // current cart contents
item_id: "123456",
item_name: "Red shoes",
item_category: "Shoes",
price: 2.99,
quantity: 1
}]
}
});Value
Current cart value.
If you leave this field empty, the tag will default to the value parameter if it is available in the event data.
=> Check cart update received data
Orders
In Matomo, orders represent the final action in a purchasing process: the transaction carried out by a customer.
Items (Required)
The items in the order.
If you leave this field empty, the tag will default to the items parameter if available in the event data.
Value
The amount of the order including VAT.
If you leave this field empty, the tag will default to the value parameter if available in the event data.
Order ID
The order ID.
If you leave this field empty, the tag will default to the transaction_id parameter if available in the event data.
Subtotal
The subtotal.
If you leave this field empty, this parameter will not be passed to Matomo.
Tax
The tax amount.
If you leave this field empty, the tag will default to the tax parameter if it is available in the event data.
Shipping
Shipping costs.
If you leave this field empty, the tag will default to the shipping parameter if it is available in the event data.
Discount
Discount.
If you leave this field empty, the tag will default to the discount parameter if it is available in the event data.
Contents
Content tracking lets you know how many times a specific ad or banner was displayed and viewed by your visitors, and how many times they actually clicked on these elements. By comparing impressions and clicks, you can calculate an interaction rate.
For each impression or interaction with the content you wish to track, you need to create a new tag, select Content Tracking as Event Type and then Content Impression or Content Interaction as Content Tracking Type.
To find out how to use content tracking, see this guide on Matomo (opens in a new tab).
Impressions
Content Name
The name of the content. Represents the content block that is being followed. A block may contain several sub-elements.
Content Piece
The content part. If the content contains several elements, the content part will refer to one of these elements.
Content Target
The content destination. The destination URL of the element that was displayed.
=> Check content impressions received data
Interactions
Content Interaction
The name of the interaction.
Content Name
The content name. Represents the content block that is being followed. A block may contain several sub-elements.
Content Piece
The content part. If the content contains several elements, the content part will refer to one of these elements.
Content Target
The content destination. The destination URL of the element that was clicked.
=> Check content interaction received data
Custom dimensions
Custom dimensions are attributes you define to categorize and segment your data more precisely. Before configuring a custom dimension in the Matomo tag, you must first have created it in the Matomo settings.
Here's a Matomo tutorial on how to create a custom dimension (opens in a new tab)
In Matomo, there are two types of custom dimensions:
- visit-type custom dimensions
- action-type custom dimensions
These are the visit-type dimensions we'll be configuring in our tag; action-type dimensions are configured from Matomo directly without touching your tracking.
For this example, here's the visit-type custom dimension I created in Matomo:
| Name | ID |
|---|---|
| User Type | 2 |
We're going to send a value for this custom dimension on all page views.
=> Check custom dimensions received data
Heartbeat requests
Heartbeat requests are sent periodically to measure more precisely the time spent on each page. It's a bit like the user_engagement event in GA4.
You can then trigger this tag on the GA4 user_engagement event.
=> Check heartbeat requests received data
Next Step
Once you've configured your tag, it's time to check that it's correctly sending data to Matomo.