Matomo / Matomo Tag Manager

27min

Summary
Official websites
Site
URL
Website
﻿https://matomo.org/﻿
Documentation
﻿https://matomo.org/help/﻿
Developer integrations
Platform
URL
Android
﻿https://github.com/matomo-org/matomo-sdk-android﻿
iOS
﻿https://github.com/matomo-org/matomo-sdk-ios﻿
Web
﻿https://developer.matomo.org/guides/tracking-introduction﻿
PXP implements two of the options that can be implemented on the web. These are:
via Javascript Tracking Client*﻿
via Tag Manager*﻿*﻿
﻿(*) Available since PXP 3.8.0
﻿(*﻿*﻿)﻿ Available since PXP 3.8.2
Tracking service
Event support matrix
Overview of the supported events and their configuration.
﻿
Templates
Parameter
﻿Actions﻿
﻿category
action
name
value﻿
﻿not supported﻿
﻿Views﻿
﻿path
title﻿
﻿not supported﻿
﻿Purchases﻿* **﻿
﻿category
action
name
value
product_name
product_category﻿
﻿not supported﻿
﻿Attributes﻿
﻿id﻿
﻿not supported﻿
﻿(*) Purchases contains special handling regarding tracking behavior. More detailed information can be found below in the description of the event configuration for actions and views.
﻿(*﻿*﻿)﻿ ﻿Purchases are supported for native apps only
General structure in tracking_config.json
Tracking service key name in "tracking_config.json" is:
"matomo"
General structure
{
  
  "matomo": {
    "eventsEnabledByDefault": true,
    "viewsEnabledByDefault": true,
    "purchasesEnabledByDefault": true,
    "attributesEnabledByDefault": true,
    
    "events": {
      // your configured list of events
    },
    
    "views": {
      // your configured list of events
    },
    
    "purchases": {
      // your configured list of events
    },
    
    "attributes": {
      // your configured list of attributes
    } 
    
  }
  
}
{
  
  "matomo": {
    "eventsEnabledByDefault": true,
    "viewsEnabledByDefault": true,
    "purchasesEnabledByDefault": true,
    "attributesEnabledByDefault": true,
    
    "events": {
      // your configured list of events
    },
    
    "views": {
      // your configured list of events
    },
    
    "purchases": {
      // your configured list of events
    },
    
    "attributes": {
      // your configured list of attributes
    } 
    
  }
  
}
﻿
Event configuration
Actions
Matomo supports action events. 
Action event
Example
"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"
  }
}
﻿
Templates
Templatey key
Required
Template value
﻿category﻿
﻿yes﻿
The category of the event.
﻿action﻿
﻿yes﻿
The action of the event.
﻿name﻿
no
The name of the event.
﻿value﻿
no
Must be value that can be parsed as floating point number.
Views
Matomo supports view events. Depending by the using platform the configuration differs as follows:
Native Purple App
View event
Example 1
Example 2
"view_event_key": {
  "templates": {
    "path": "value of template",
    "title": "value of template"
  }
}
"view_event_key": {
  "templates": {
    "path": "value of template",
    "title": "value of template"
  }
}
﻿
Templates
Templatey key
Required
Template value
﻿path﻿
﻿yes﻿
Must be a path like in a website or a full valid URL.
﻿title﻿
﻿yes﻿
The title of the page.
Web integration
For web integration, the path template is omitted because it sets this value automatically.
View event
Example 1
Example 2
"view_event_key": {
  "templates": {
    "title": "value of template"
  }
}
"view_event_key": {
  "templates": {
    "title": "value of template"
  }
}
﻿
Templates
Templatey key
Required
Template value
﻿title﻿
no
The title of the page. This value overrides the default value. 
How the default value is created:
Titles for content on the web are generated using a complex algorithm involving several preprocessing software components. This results in the title-tag within the html document. Matomo in web uses its value as page title.
Purchases
Matomo supports purchase events in native apps only.
Purchase event
Example
"STOREFRONT_ISSUE_PURCHASED": {
  "templates": {
    "category": "storefront",
    "action": "issue_purchased",
    "name": "{{ISSUE_NAME}}",
    "product_name": "{{PRODUCT_ID}}",
    "product_category": "single_purchase"
  }
}
"STOREFRONT_ISSUE_PURCHASED": {
  "templates": {
    "category": "storefront",
    "action": "issue_purchased",
    "name": "{{ISSUE_NAME}}",
    "product_name": "{{PRODUCT_ID}}",
    "product_category": "single_purchase"
  }
}
﻿
Templates
Matomo offers a specific API to track purchases. Tracking purchase events takes place in two steps:
An event is sent with the value of the price
An additional order item is tracked
(1) Templates used for the event:
Templatey key
Required
Template value
﻿category﻿
﻿yes﻿
The category of the event.
﻿action﻿
﻿yes﻿
The action of the event.
﻿name﻿
no
The name of the event.
(2) Templates used for the order item:
Templatey key
Required
Template value
﻿product_name﻿
no
The name of the product.
﻿product_category﻿
no
The category of the product.
The order item is sent with some additional values:
API
Value
﻿productId﻿
The product id of the purchase.
﻿price﻿
The price of the product.
﻿transactionId﻿
The transaction id of the purchase if available.
﻿quantity﻿
1
Attributes
Matomo supports attributes via custom dimensions. Custom dimensions are distinguished into two different types.
"Visit dimensions" and
"Action dimensions"
Purple Attributes correspond to the "Visit dimensions". For more information please read the Matomo documentation.
Attribute
Example
"HAS_ACTIVE_SUBSCRIPTION": {
  "templates": {
    "id": "1"
  }
}
"HAS_ACTIVE_SUBSCRIPTION": {
  "templates": {
    "id": "1"
  }
}
﻿
Templates
Templatey key
Required
Template value
﻿id﻿
﻿yes﻿
The id of the attribute.
Must be value that can be parsed as integer number.
Additional supported functionality
Custom User ID
﻿https://matomo.org/faq/reports/set-up-user-id-tracking-in-matomo/﻿
This feature is not fully enabled as provided by Matomo.
Purple sets the user id in native apps only. The generated Purple-Device-Id is used for this.
URL Whitelisting 
﻿https://matomo.org/faq/how-to/faq_21077/﻿
Matomo offers the possibility to create a whitelist of URLs. This ensures that only events whose URL matches one of the whitelist URLs are recorded.
If you want to send data from both your native apps and your website to the same Matomo site and also want to enable the whitelist feature, please read on here:
﻿How to enable the whitelist feature in Matomo﻿ 
How to configure
Native Purple App
Any native Tracking Service is configured in the Purple Manager.﻿
Enable SDK
Settings location
"Your app" => "Consent/Push/Analytics" => "Analytics (General/iOS/Android/Web)"
Setting
Description
Enable Matomo
To enable the Matomo SDK in your app, activate this checkbox.
Matomo URL
The Matomo URL provided by Matomo. 
Matomo Site ID
The Matomo Site id provided by Matomo.
Apple privacy / ATT
Settings location
"Your app" => "Consent/Push/Analytics" => "Privacy"
Consent management
Settings location:
"Your app" => "Consent/Push/Analytics" => "Consent Management"
Setting
Description
Vendor-ID for Matomo
The Vendor-ID is provided by the consent management platform.
Web integration
Enable SDK
Matomo is not explicitly enabled. If a valid configuration of Matomo is present in the "experience.config.json", the SDK is integrated into the HTML document. This can be either done as Javascript Tracking Client or as Tag Manager. The corresponding configurations differ as follows:
Structure in experience.config.json
JavaScript Tracking Client
Tag Manager
{
  "purple": {
    "analytics": {
    
      "matomo": {
        "configuration": {
          "useTagManager": "Provided by Matomo",
          "containerSourceUrl": "Provided by Matomo"
        }        
      }
      
    }
  }
}
{
  "purple": {
    "analytics": {
    
      "matomo": {
        "configuration": {
          "useTagManager": "Provided by Matomo",
          "containerSourceUrl": "Provided by Matomo"
        }        
      }
      
    }
  }
}
﻿
When using the Tag Manager a further setup at Matomo Tag Manager Dashboard is needed. Please read on more here:
﻿Matomo Tag Manager Setup guide﻿﻿
Consent management
If you use one of the CMPs supported by Purple, you must specify the CMP-specific  vendor ID for Matomo, which you can get from your CMP frontend. Additionally, the IAB vendor ID for Matomo can also be added.
Structure in experience.config.json
Javascript Tracking Client with consent
Tag Manager with consent
{
  "purple": {
    "analytics": {
    
      "matomo": {
        "configuration": {
          "useTagManager": "Provided by Matomo",
          "containerSourceUrl": "Provided by Matomo"
        }        
        "consent": {
          "vendorId": "Provided by your CMP",
          "iabVendorId": ""
        }
      }
      
    }
  }
}
{
  "purple": {
    "analytics": {
    
      "matomo": {
        "configuration": {
          "useTagManager": "Provided by Matomo",
          "containerSourceUrl": "Provided by Matomo"
        }        
        "consent": {
          "vendorId": "Provided by your CMP",
          "iabVendorId": ""
        }
      }
      
    }
  }
}
﻿
﻿

Site	URL
Website	https://matomo.org/
Documentation	https://matomo.org/help/

Platform	URL
Android	https://github.com/matomo-org/matomo-sdk-android
iOS	https://github.com/matomo-org/matomo-sdk-ios
Web	https://developer.matomo.org/guides/tracking-introduction PXP implements two of the options that can be implemented on the web. These are: via Javascript Tracking Client* via Tag Manager**

	Templates	Parameter
Actions	category action name value	not supported
Views	path title	not supported
Purchases* **	category action name value product_name product_category	not supported
Attributes	id	not supported

Templatey key	Required	Template value
category	yes	The category of the event.
action	yes	The action of the event.
name	no	The name of the event.
value	no	Must be value that can be parsed as floating point number.

Templatey key	Required	Template value
path	yes	Must be a path like in a website or a full valid URL.
title	yes	The title of the page.

Templatey key	Required	Template value
title	no	The title of the page. This value overrides the default value. How the default value is created: Titles for content on the web are generated using a complex algorithm involving several preprocessing software components. This results in the title-tag within the html document. Matomo in web uses its value as page title.

Templatey key	Required	Template value
category	yes	The category of the event.
action	yes	The action of the event.
name	no	The name of the event.

Templatey key	Required	Template value
product_name	no	The name of the product.
product_category	no	The category of the product.

API	Value
productId	The product id of the purchase.
price	The price of the product.
transactionId	The transaction id of the purchase if available.
quantity	1

Templatey key	Required	Template value
id	yes	The id of the attribute. Must be value that can be parsed as integer number.

Setting	Description
Enable Matomo	To enable the Matomo SDK in your app, activate this checkbox.
Matomo URL	The Matomo URL provided by Matomo.
Matomo Site ID	The Matomo Site id provided by Matomo.

Setting	Description
Vendor-ID for Matomo	The Vendor-ID is provided by the consent management platform.

INFOnline (IVW)

Matomo Tag Manager Setup guide