Matomo / Matomo Tag Manager

29 min

Summary

Official websites

Site	URL
Website	https://matomo.org/
Documentation	Matomo Help Centre https://matomo.org/help/ PXP implements two options that can be implemented on the web. These are: via Matomo Javascript Tracking Client https://developer.matomo.org/guides/tracking-javascript-guide via Matomo Tag Manager https://developer.matomo.org/guides/tagmanager/introduction

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 options that can be implemented on the web. These are: via Matomo Javascript Tracking Client* via Matomo 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	supported
Views	path name*** title	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

(***) The name template is used by Matomo Tag Manager only.

General structure in tracking_config.json

Tracking service key name in "tracking_config.json" is: "matomo"

{
  
  "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

Custom dimensions

Matomo supports custom dimensions. Custom dimensions are distinguished into two different types.

"Visit dimensions" used for Purple attributes and

"Action dimensions" used by action and view events.

Actions

Matomo supports action events.

"ISSUE_DOWNLOADED": {
  "templates": {
    "category": "app",
    "action": "issue_downloaded",
    "name": "{{ISSUE_NAME}}",
    "value": "1"
  },
  "parameters": {
    "1": "{{ISSUE_ID}}" // Assuming that a custom visit dimension is configured as "issue_id" at Matomo and has this id of "1".
  }
}

Templates

Template key	Required	Template value
trigger	no	The name of the trigger in Matomo Tag Manager.
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.

Parameters

Matomo supports parameters for action events in web only. Parameters must be configured as custom action dimension at Matomo.

Pameter name	Template value
The id of the custom action dimension. Must be a value that can be parsed as integer number.	The value of the parameter.

Views

Matomo supports view events.

Depending on the platform used, the configuration differs as follows:

Native Purple App

"view_event_key": {
  "templates": {
    "path": "value of template",
    "title": "value of template"
  }
}

Templates

Template 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 Matomo sets this value automatically.

"view_event_key": {
  "templates": {
    "trigger": "The name of the trigger in Matomo Tag Manager",   
    "name": "value of template",
    "title": "value of template"
  },
  "parameters": {
    "parameter_key_1": "value of parameter",

    // your configured list of parameters (supported via web only)
  }
}

Templates

Template key	Required	Template value
trigger	no	The name of the trigger in Matomo Tag Manager.
name	no	The name of the view. Used by Matomo Tag Manager only.
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.

Parameters

Matomo supports parameters for view events in web only. Parameters must be configured as custom action dimension at Matomo.

Pameter name	Template value
The id of the custom action dimension. Must be a value that can be parsed as integer number.	The value of the parameter.

Purchases

Matomo supports purchase events in native apps only.

"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:

Template 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:

Template 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.

"HAS_ACTIVE_SUBSCRIPTION": {
  "templates": {
    "id": "1"
  }
}

Templates

Template key	Required	Template value
id	yes	The id of the custom visit dimension. Must be a 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. i.e. https://yourmatomobasebath.com/matomo.php
Matomo Site ID	The Matomo Site id provided by Matomo.

Apple privacy / ATT

Settings location

"Your app" => "Consent/Push/Analytics" => "Privacy"

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

You can use the Purple Experience Builder to edit the "experience.config.json".

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 Matomo Javascript Tracking Client or as Matomo Tag Manager. The corresponding configurations differ as follows:

Structure in experience.config.json

{
  "purple": {
    "analytics": {
    
      "matomo": {
        "configuration": {
          "siteId": "Provided by Matomo",
          "endpointUrl": "Provided by Matomo",
          "scriptSourceUrl": "Provided by Matomo"
        }        
      }
      
    }
  }
}

Matomo Javascript Client

Setting	Description
siteId	The id of your site in Matomo.
endpointUrl	The endpoint url of your Matomo project.
scriptSourceUrl	The script source url of your Matomo project.

Matomo Tag Manager

Setting	Description
useTagManager	Enables the Matomo Tag Manager instead of Matomo Javascript Client
containerSourceUrl	The url of your Matomo container.

When using the Matomo Tag Manager a further setup at Matomo Tag Manager Dashboard is needed. Please read on more here:

Matomo Tag Manager Setup guide

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

{
  "purple": {
    "analytics": {
    
      "matomo": {
        "configuration": {
          "siteId": "Provided by Matomo",
          "endpointUrl": "Provided by Matomo",
          "scriptSourceUrl": "Provided by Matomo"
        },
        "consent": {
          "vendorId": "Provided by your CMP",
          "iabVendorId": ""
        }
      }
      
    }
  }
}

Consent

Setting	Description
vendorId	The vendor ID managed by your CMP.
iabVendorId	The vendor ID managed by IAB.

Matomo / Matomo Tag Manager

Summary

Official websites

Developer integrations

Tracking service

Event support matrix

General structure in tracking_config.json

Event configuration

Actions

Views

Purchases

Attributes

Additional supported functionality

Custom User ID

URL Whitelisting

How to configure

Native Purple App

Enable SDK

Apple privacy / ATT

Consent management

Web integration

Enable SDK

Consent management