---
title: Matomo Tag Manager Setup guide
slug: experience/matomo-tag-manager-setup-guide
docTags:
createdAt: 2025-03-07T14:04:47.832Z
---
# Description
The prerequisite for successful tracking with the Matomo Tag Manager is that all desired action events, view events and attributes are configured in the "tracking\_config.json". You can find out how to do this in general [here](docId\:SxKxO_OEPT7crFZZOB9Nw).
Based on this configuration, PXP sends the corresponding data to Matomo Tag Manager using defined names for triggers and variables.
The configuration must be set up accordingly on Matomo's side. The full PXP support results in the following example structure which shows the full setup to support action-events, view-events and attributes.
**Complete structure used by this example **
:::ExpandableHeading
**Matomo Tag Manager structure in detail**
**Tags**
To connect PXP with Matomo Tag Manager, these tags are required based on this example:
**Trigger**
To connect PXP with Matomo Tag Manager, these triggers are required based on this example:
**Variables**
To connect PXP with Matomo Tag Manager these variables are required based on this example:
:::
# Events and Attributes
## Action events
### PXP
It starts with an action event configuration. The event "**ISSUE\_OPENED**" is used for the following example. Depending on whether parameters are to be used or not, the configuration differs as follows:
:::CodeblockTabs
Action event
```json
"ISSUE_OPENED": {
"templates": {
"category": "content",
"action": "issue_opened",
"name": "{{ISSUE_NAME}}",
"value": 1
}
}
```
Action event with parameters
```json
"ISSUE_OPENED": {
"templates": {
"trigger": "purple.issue_opened",
"category": "content",
"action": "issue_opened",
"name": "{{ISSUE_NAME}}",
"value": 1
},
"parameters": {
"3": "{{ISSUE_NAME}}"
}
}
```
:::
**Reduced code from PXP **
PXP web client pushes
- an "event" which is configured as "**Trigger**" and
- data which is configured as "**Variable (Data-Layer)**"
to Matomo Tag Manager.
The following source code shows a simplified representation of how PXP calls the Matomo Tag Manager API:
:::CodeblockTabs
PXP code for API call
```javascript
// code for action events
const eventData = {
'event': 'purple.action_event', // trigger
'purple': {
'action_event_action': ... , // variable
'action_event_category': ... , // variable
'action_event_name': ... , // variable
'action_event_value': ... // variable
}
};
window._mtm.push(eventData);
```
PXP code for API call with parameters
```javascript
// code for action events with parameters
const eventData = {
'event': event.templates?.trigger ?? 'purple.action_event', // trigger
'purple': {
'action_event_action': ... , // variable
'action_event_category': ... , // variable
'action_event_name': ... , // variable
'action_event_value': ... , // variable
'parameters': { ... } // all configured parameters
}
};
window._mtm.push(eventData);
```
:::
### Configuration in Matomo Tag Manager
:::::WorkflowBlock
::::WorkflowBlockItem
**Create required "Variables (Data-Layer)" to receive data**
The variable names defined by Purple are as follows:
:::BlockQuote
purple.action_event_category
purple.action_event_action
purple.action_event_name
purple.action_event_value
:::
:::ExpandableHeading
**Matomo Tag Manager example**
**Variable to receive category**
**Variable to receive action**
**Variable to receive name**
**Variable to receive value**
:::
::::
::::WorkflowBlockItem
**Create the required “Trigger” for PXP to push to.**
The trigger name defined by Purple is as follows:
:::BlockQuote
purple.action_event
:::
:::ExpandableHeading
**Matomo Tag Manager example**
**Trigger for Action-Event**
:::
::::
::::WorkflowBlockItem
**Create a “Tag” that will run when the trigger fires**
Create a tag which creates an action event using the variables from **Step 1 **and assign the trigger from **Step 2** to define when this tag executes.
:::ExpandableHeading
**Matomo Tag Manager example**
**Tag (Name)**
**Tag (Create event)**
**Tag (Use trigger)**
:::
::::
:::::
### Summary
Finally, this is how it works together:
## View events
### PXP
It starts with a view event configuration. The event "**STOREFRONT\_SEARCH**" is used for the following example.
:::CodeblockTabs
View event
```json
"STOREFRONT_SEARCH": {
"templates": {
"name": "{{VIEW}}",
"title": "Cool search"
}
}
```
View event with parameters
```json
"STOREFRONT_SEARCH": {
"templates": {
"name": "{{VIEW}}",
"title": "Cool search"
},
"parameters": {
"8": "view parameter example: {{FOO}}"
}
}
```
:::
**Reduced code from PXP **
PXP web client pushes
- an "event" which is configured as "**Trigger**" and
- data which is configured as "**Variable (Data-Layer)**"
to Matomo Tag Manager.
The following source code shows a simplified representation of how PXP calls the Matomo Tag Manager API:
:::CodeblockTabs
PXP code for API call
```javascript
// code for view events
const eventData = {
'event': 'purple.view_event', // trigger
'purple': {
'view_event_name': ... , // variable
'view_event_title': ... // variable
}
};
window._mtm.push(eventData);
```
PXP code for API call with parameters
```javascript
// code for view events
const eventData = {
'event': view.templates?.trigger ?? 'purple.view_event', // trigger
'purple': {
'view_event_name': ... , // variable
'view_event_title': ... , // variable
'parameters': { ... } // all configured parameters
}
};
window._mtm.push(eventData);
```
:::
### Configuration in Matomo Tag Manager
:::::WorkflowBlock
::::WorkflowBlockItem
**Create required "Variables (Data-Layer)" to receive data**
The variable names defined by Purple are as follows:
:::BlockQuote
:::
:::ExpandableHeading
**Matomo Tag Manager example**
**Variable to receive view title**
**Variable to receive view name**
:::
::::
::::WorkflowBlockItem
**Create the required “Trigger” for PXP to push to.**
The trigger name defined by Purple is as follows:
:::BlockQuote
:::
:::ExpandableHeading
**Matomo Tag Manager example**
**Trigger for View-Event**
:::
::::
::::WorkflowBlockItem
**Create a “Tag” that will run when the trigger fires**
Create a tag which creates an view event using the variables from **Step 1 **and assign the trigger from **Step 2** to define when this tag executes.
:::ExpandableHeading
**Matomo Tag Manager example**
**Tag (Name)**
**Tag (Create event)**
**Tag (Use trigger)**
:::
::::
:::::
### Summary
Finally, this is how it works together:
## Attributes
### PXP
It starts with an attribute configuration. The attribute "**HAS\_BOOKMARKS**" is used for the following example.
:::CodeblockTabs
Attribute
```json
"HAS_BOOKMARKS": {
"templates": {
"id": "1"
}
}
```
:::
**Reduced code from PXP **
PXP web client pushes data which is configured as "**Variable (Data-Layer)**" to Matomo.
The following source code shows a simplified representation of how PXP calls the Matomo Tag Manager API:
:::CodeblockTabs
PXP code for API call
```javascript
// code for custom dimensions
const index = ... // value is configured in tracking_config.json
const dataLayerName = `purple.custom_dimension_${index}`;
const customDimensionData = {
[`${dataLayerName}`]: ... // variable
};
window._mtm.push(customDimensionData);
```
:::
### Configuration in Matomo Tag Manager
:::::WorkflowBlock
::::WorkflowBlockItem
**Create custom visit dimensions**
Add your desired custom visit dimensions.
:::ExpandableHeading
**Matomo Tag Manager example**
**Custom visit dimensions**
:::
::::
::::WorkflowBlockItem
**Create required "Variables (Data-Layer)" to receive data**
The variable names defined by Purple are as follows:
:::BlockQuote
purple.custom_dimension_1
...
purple.custom_dimension_n
:::
Where "n" is an element of the integer positive numbers.
:::ExpandableHeading
**Matomo Tag Manager example**
**Custom dimension 1 used by "hasBookmarks"**
**Custom dimension 2 used by "userId"**
:::
::::
::::WorkflowBlockItem
**Map custom visit dimensions to Matomo site configuration**
Custom visit dimensions are mapped within the corresponding Matomo site configuration.
:::ExpandableHeading
**Matomo Tag Manager example**
**Matomo site configuration**
:::
::::
:::::
### Summary
Finally, this is how it works together:
