# Matomo

Matomo, formerly Piwik, is an open source web analytics platform. It can be used to derive valuable insights into your website’s visitors and marketing campaigns so as to optimize your strategy and online experience for your visitors.

RudderStack supports Matomo as a destination to which you can seamlessly send your event data.

Connection compatibility

Destination Information
  • Status: Generally Available
  • Supported sources: Web
  • Refer to it as Matomo in the Integrations object.
Connection Modes
Source Cloud mode Device mode Hybrid mode
Web not supported supported not supported
Supported Message Types
Source Identify Page Track Screen Group Alias Record AudienceList
Device mode
Web supported supported supported not supported not supported not supported not supported not supported

In the web device mode integration, that is, using JavaScript SDK as a source, RudderStack loads the Matomo native SDK from thehttps://cdn.matomo.cloud/ domain.

Based on your website’s content security policy, you might need to allowlist this domain to load the Matomo SDK successfully.

Get started

Once you have confirmed that the source platform supports sending events to Matomo, follow these steps:

  1. From your RudderStack dashboard, add a source. Then, from the list of destinations, select Matomo.
  2. Assign a name to the destination and click Continue.

Connection settings

To successfully setup Matomo as a destination, you will need to configure the following settings:

Refer to the FAQ section below for more information on finding the Server URL and Site Id.

Event settings

Matomo connection settings
Matomo connection settings
Matomo connection settings

You can specify multiple Goal Id’s for one Event Name and vice versa.
You can specify multiple Standard Events for one Event Name and vice versa.

Web device mode settings

Matomo connection settings

Identify

RudderStack sets the ID value in the cache to the userId or anonymousId present in the identify call.

A sample identify call is shown below:

javascript 
rudderanalytics.identify("1hKOmRA4GRlm");

The following table lists the RudderStack and Matomo property to set the userId in the identify call:

RudderStack property Matomo property Presence Matomo Method
userId/anonymousId userId Required _paq.push(["setUserId","user_id"])

Track

This destination does not strictly adhere to the RudderStack Ecommerce Event Spec.

The track method lets you capture user events along with the properties associated with them.

A sample track call is shown below:

javascript 
rudderanalytics.track("Order Completed",{
"category": "Orders",
"action": "Pass",
"value": 15
});

Generic events

RudderStack sends a generic track call which is a not a standard event or an ecommerce event as a Matomo trackEvent event.

The following table lists the property mappings between RudderStack and Matomo for trackEvent:

RudderStack property Matomo property Presence
properties.category category Required
properties.action action Required
event name Optional
properties.value value Optional

Standard events

For RudderStack to send an event as a standard Matomo event, you need to specify the event mapping under the Mapping to trigger the Matomo standard events for the respective Events setting in the RudderStack dashboard. For more information, refer to the Event settings section above.

RudderStack supports the following Matomo standard events:

RudderStack first verifies if an event is mapped to a standard Matomo event. If so, it sends the event to Matomo with some specific properties, as listed in the following sections.

These properties should be present in the events for RudderStack to successfully send them to Matomo.

Ping

Use this event to send a ping request.

The ping requests do not track new actions. Matomo ignores these requests if they’re sent after a standard visit length.

Track Content Impressions

Use this event to track a content impression using the specified values.

RudderStack maps the following event properties to the Matomo standard event properties:

RudderStack property Matomo property Description
properties.contentName contentName Represents a content block visible in the reports. One name can represent different content pieces.
properties.contentPiece contentPiece Actual displayed content, for example, path to a video, image, etc.
properties.contentTarget contentTarget URL of the landing page where the user was directed to after interacting with the block.

Track Content Impressions Within Node

Use this event to scan a given DOM node and its associated children for content blocks and track impressions for them, if not done already.

RudderStack maps the following event properties to the Matomo standard event properties:

RudderStack property Matomo property
properties.domId/ properties.dom_id domId

Track Content Interaction

Use this event to track a content interaction with the specified values.

RudderStack maps the following event properties to the Matomo standard event properties:

RudderStack property Matomo property
properties.contentInteraction contentInteraction
properties.contentName contentName
properties.contentPiece contentPiece
properties.contentTarget contentTarget

Track Content Interaction Node

Use this event to track the interaction with a given DOM node or a content block.

RudderStack maps the following event properties to the Matomo standard event properties:

RudderStack property Matomo property
properties.domId/ properties.dom_id domId
properties.contentInteraction contentInteraction

Use this event to log a click from your code.

RudderStack maps the following event properties to the Matomo standard event properties:

RudderStack property Matomo property Description
properties.url/ message.context.page.url url The full URL to be tracked as a click.
properties.linkType linkType Defines the link type. Can either be link for an outlink or download for the download link type.

Use this event to track an internal site search for a given keyword with an optional category and specifying the optional search results count in the page.

RudderStack maps the following event properties to the Matomo standard event properties:

RudderStack property Matomo property
properties.keyword/properties.search/message.context.page.search keyword
properties.category category
properties.resultsCount resultsCount

Ecommerce events

RudderStack supports and maps the following ecommerce events to the corresponding Matomo ecommerce events:

RudderStack Event Matomo Event
Product Viewed setEcommerceView
Product Added addEcommerceItem
Product Removed removeEcommerceItem
Order Completed trackEcommerceOrder
Cart Cleared clearEcommerceCart
Update Cart trackEcommerceCartUpdate

For the above-mentioned events, you can also send specific properties as mentioned in the following sections.

Product Viewed

RudderStack maps the Product Viewed event to [setEcommerceView](https://developer.matomo.org/api-reference/tracking-javascript#ecommerce:~:text=click%20here.-,setEcommerceView,-(%20productSKU%2C%20productName%2C%20categoryName). The following event properties are mapped to the Matomo properties:

RudderStack property Matomo property Presence
properties.sku/properties.product_id productSKU Required
properties.name productName Required
properties.category categoryName Required
properties.price (Multiplied by quantity) price Required
You can view the Product Viewed event in the Matomo dashboard only when it is followed by a page call.

Product Added

RudderStack maps the Product Added event name to [addEcommerceItem](https://developer.matomo.org/api-reference/tracking-javascript#ecommerce:~:text=category%20page%20view.-,addEcommerceItem,-(%20productSKU%2C%20%5BproductName%5D%2C%20%5BproductCategory). The following event properties are mapped to the Matomo properties:

RudderStack property Matomo property Presence
properties.sku/properties.product_id productSKU Required
properties.name productName Optional
properties.category categoryName Optional
properties.price (Multiplied by quantity) price Optional
properties.quantity quantity Optional
You can view the Product Added event in the Matomo dashboard only when it is followed by an Update Cart or Order Completed event.

Product Removed

RudderStack maps the Product Removed event name to removeEcommerceItem. The following event properties are mapped to the Matomo properties:

RudderStack property Matomo property Presence
properties.sku/properties.product_id productSKU Required
You can view the Product Removed event in the Matomo dashboard only when it is followed by an Update Cart or Order Completed event.

Order Completed

RudderStack maps the Order Completed event name to [trackEcommerceOrder](https://developer.matomo.org/api-reference/tracking-javascript#ecommerce:~:text=from%20the%20cart.-,trackEcommerceOrder,-(%20orderId%2C%20grandTotal%2C%20%5BsubTotal). The following event properties are mapped to the Matomo properties:

RudderStack property Matomo property Presence
properties.order_id/properties.orderId orderId Required
properties.total/properties.revenue grandTotal Required
properties.subtotal subtotal Optional
properties.tax tax Optional
properties.shipping shipping Optional
properties.discount discount Optional

grandTotal is not a default property in the Order Completed event and needs to be provided by the user. If not provided, RudderStack calculates it manually by iterating through the products array, as shown below:

grandTotal = products[0].price * products[0].quantity + …
grandTotal += tax + shipping;

Similarly, subtotal is calculated as the total value of all sales, excluding shipping and tax.

Update Cart

Although Update Cart is not a standard RudderStack Ecommerce Event, you can still send this event to update your cart and view the items that are currently present in it.

RudderStack also maps the Update Cart event name to trackEcommerceCartUpdate. The following event properties are mapped to the Matomo properties:

RudderStack property Matomo property Presence
properties.total/properties.revenue grandTotal Required

Page

The page call lets you record your website’s page views with any additional relevant information about the viewed page.

A sample page call is shown below:

javascript 
rudderanalytics.page("home","games");
RudderStack does not consider any parameters inside the page call and simply calls the trackPageView event for each page call.

Custom dimensions

Custom dimensions can be used to track any information related to any action or visitors.

You can send the custom dimensions to Matomo only through the track calls.

RudderStack provides customDimension field which can be used inside the integrations object, as shown below:

javascript 
{
  integrations: {
    Matomo: {
      customDimension: [{
          dimensionId: <dimension_ID>,
          dimensionValue: <dimension_value>
        },
        {
          dimensionId: 1,
          dimensionValue: ENTERPRISE
        }
      ]
    }
  }
}
Refer to the Matomo help guide to know about the data limitations for custom dimensions in Matomo.
RudderStack does not support sending custom variables to Matomo. Matomo recommends using custom dimensions instead. For more information, refer to this Matomo page.

FAQ

Where can I find the Server URL and Site Id?

To find the Matomo Server URL and Site Id:

  1. Log into your Matomo dashboard.
  2. Go to Settings > Website > Tracking Code.
  3. Under JavaScript Tracking Code section, you will find the below:
Matomo dashboard

Here, the server URL: https://rudderstacktest.matomo.cloud/ and site Id: 1