Matomo Tag Manager Setup guide

15min
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 here﻿. 
Based on this configuration, PXP sends the corresponding data to Matomo 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, in this example project, two custom dimensions:
﻿
Tags
To connect PXP with Matomo Tag Manager, both tags are required:
﻿
Trigger
To connect PXP with Matomo Tag Manager, both triggers are required:
﻿
Variables
To connect PXP with Matomo Tag Manager these variables are required:
﻿
Events and Attributes
Action events
PXP
It starts with an action event configuration. The event "ISSUE_DOWNLOADED" is used for the following example.
tracking_config.json
"ISSUE_DOWNLOADED": {
  "templates": {
    "category": "app",
    "action": "issue_downloaded",
    "name": "{{ISSUE_NAME}}",
    "value": "1"
  }
}
"ISSUE_DOWNLOADED": {
  "templates": {
    "category": "app",
    "action": "issue_downloaded",
    "name": "{{ISSUE_NAME}}",
    "value": "1"
  }
}
﻿
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.
The following source code shows a simplified representation of how PXP calls the Matomo Tag Manager API:
PXP code for API call
// code for action events
const eventData = {
    'event': 'purple.action_event',       // trigger
    'purple.action_event_category': ... , // variable
    'purple.action_event_action': ... ,   // variable
    'purple.action_event_name': ... ,     // variable
    'purple.action_event_value': ...      // variable
};
window._mtm.push(eventData);
// code for action events
const eventData = {
    'event': 'purple.action_event',       // trigger
    'purple.action_event_category': ... , // variable
    'purple.action_event_action': ... ,   // variable
    'purple.action_event_name': ... ,     // variable
    'purple.action_event_value': ...      // variable
};
window._mtm.push(eventData);
﻿
Configuration in Matomo Tag Manager
1
Create required "Variables (Data-Layer)" to receive data
The variable names defined by Purple are as follows: 
﻿purple.action_event_category
purple.action_event_action
purple.action_event_name
purple.action_event_value﻿
Variable to receive category
﻿
Variable to receive action
﻿
Variable to receive name
﻿
Variable to receive value
﻿
2
Create the required “Trigger” for PXP to push to.
The trigger name defined by Purple is as follows: 
﻿purple.action_event﻿
Trigger for Action-Event
﻿
3
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.
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_HOME" is used for the following example.
tracking_config.json
"STOREFRONT_HOME": {
  "templates": {
    "title": "any page title"
  }
}
"STOREFRONT_HOME": {
  "templates": {
    "title": "any page title"
  }
}
﻿
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.
The following source code shows a simplified representation of how PXP calls the Matomo Tag Manager API:
PXP code for API call
// code for view events
const eventData = {
    'event': 'purple.view_event',  // trigger
    'purple.view_event_title': ... // variable
};
window._mtm.push(eventData); 
// code for view events
const eventData = {
    'event': 'purple.view_event',  // trigger
    'purple.view_event_title': ... // variable
};
window._mtm.push(eventData); 
﻿
Configuration in Matomo Tag Manager
1
Create required "Variables (Data-Layer)" to receive data
The variable names defined by Purple are as follows: 
﻿﻿purple.view_event_title﻿﻿
Variable to receive view title
﻿
2
Create the required “Trigger” for PXP to push to.
The trigger name defined by Purple is as follows: 
﻿﻿purple.view_event﻿﻿
Trigger for View-Event
﻿
3
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.
Tag (Name)
﻿
Tag (Create event)
﻿
Tag (Use trigger)
﻿
Summary
﻿
Attributes
PXP
It starts with an attribute configuration. The attribute "HAS_BOOKMARKS" is used for the following example.
tracking_config.json
"HAS_BOOKMARKS": {
  "templates": {
    "id": "1"
  }
}
"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:
PXP code for API call
// 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);
// 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
1
Create custom visit dimensions
Add your desired custom visit dimensions.
Custom dimensions
﻿
2
Create required "Variables (Data-Layer)" to receive data
The variable names defined by Purple are as follows: 
﻿purple.custom_dimension_1
...
purple.custom_dimension_n﻿
Where "n" is an element of the integer positive numbers.
Custom dimension 1
﻿
Custom dimension 2
﻿
3
Map custom visit dimensions to Matomo site configuration
Custom visit dimensions are mapped within the corresponding Matomo site configuration.
Matomo site configuration
﻿
Summary
﻿
﻿
Matomo / Matomo Tag Manager
How to enable the whitelist feature in Matomo