--- title: Matomo / Matomo Tag Manager slug: experience/matomo-matomo-tag-manager description: Learn how to integrate Matomo, a tracking service, into your website with this comprehensive document. Discover the official website, developer integrations, and the event support matrix. Explore the general structure in tracking_config.json and explore e docTags: createdAt: 2023-06-30T14:38:56.278Z --- # Summary ## Official websites | **Site** | **URL** | | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Website | [https://matomo.org/](https://matomo.org/) | | Documentation | Matomo Help Centre
[https://matomo.org/help/](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](https://developer.matomo.org/guides/tracking-javascript-guide) * via **Matomo Tag Manager** - [https://developer.matomo.org/guides/tagmanager/introduction](https://developer.matomo.org/guides/tagmanager/introduction) | ## Developer integrations | **Platform** | **URL** | | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Android | [https://github.com/matomo-org/matomo-sdk-android](https://github.com/matomo-org/matomo-sdk-android) | | iOS | [https://github.com/matomo-org/matomo-sdk-ios](https://github.com/matomo-org/matomo-sdk-ios) | | Web | [https://developer.matomo.org/guides/tracking-introduction](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 :::hint{type="info"} Tracking service key name in "*tracking\_config.json*" is: "**matomo**" ::: :::CodeblockTabs General structure ```json { "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 :::hint{type="info"} **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. :::CodeblockTabs Action event ```json "action_event_key": { "templates": { "trigger": "The name of the trigger in Matomo Tag Manager", "category": "value of template", "action": "value of template", "name": "value of template", "value": "value of template" }, "parameters": { "parameter_key_1": "value of parameter", // your configured list of parameters (supported via web only) } } ``` Example ```json "ISSUE_DOWNLOADED": { "templates": { "category": "app", "action": "issue_downloaded", "name": "{{ISSUE_NAME}}", "value": "1" } } ``` Example with parameters ```json "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** :::CodeblockTabs View event ```json "view_event_key": { "templates": { "path": "value of template", "title": "value of template" } } ``` Example 1 ```json "STOREFRONT_FEED": { "templates": { "path": "/storefront/feed", "title": "App/Feed" } } ``` Example 2 ```json "APP_MENU": { "templates": { "path": "/app_menu", "title": "App/Menu" } } ``` ::: **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. :::CodeblockTabs View event ```json "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) } } ``` Example Javascript Tracking Client ```json "STOREFRONT_FEED": { "templates": { "title": "App/Feed" } } ``` Example Matomo Tag Manager ```json "APP_MENU": { "templates": { "name": "app_menu", "title": "App/Menu" } } ``` ::: **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**. :::CodeblockTabs Purchase event ```json "purchase_event_key": { "templates": { "category": "value of template", "action": "value of template", "name": "value of template", "product_name": "value of template", "product_category": "value of template" } } ``` Example ```json "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: 1. An event is sent with the value of the price 2. 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. :::CodeblockTabs Attribute ```json "attribute_key": { "templates": { "id": "value of template" } } ``` Example ```json "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/](https://matomo.org/faq/reports/set-up-user-id-tracking-in-matomo/) This feature is **not** fully enabled as provided by Matomo. :::hint{type="warning"} 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/](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. :::hint{type="info"} 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](docId\:u-qV254gvCZ_zAX1ukxAv) ::: # How to configure ## Native Purple App Any native Tracking Service is configured in the **Purple Manager.** ### Enable SDK :::hint{type="info"} ***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 :::hint{type="info"} ***Settings location*** "**Your app**" => "**Consent/Push/Analytics**" => "**Privacy**" ::: ### Consent management :::hint{type="info"} **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 :::hint{type="info"} You can use the [Purple Experience Builder](docId\:KMuf0oag3Of3A46iUp5q4) 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** :::CodeblockTabs Matomo JavaScript Tracking Client ```json { "purple": { "analytics": { "matomo": { "configuration": { "siteId": "Provided by Matomo", "endpointUrl": "Provided by Matomo", "scriptSourceUrl": "Provided by Matomo" } } } } } ``` Matomo Tag Manager ```json { "purple": { "analytics": { "matomo": { "configuration": { "useTagManager": "Provided by Matomo", "containerSourceUrl": "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. | :::hint{type="info"} 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](docId\:RBdqewICZw3sxFpDaAdqP) ::: ### 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** :::CodeblockTabs Javascript Tracking Client with consent ```json { "purple": { "analytics": { "matomo": { "configuration": { "siteId": "Provided by Matomo", "endpointUrl": "Provided by Matomo", "scriptSourceUrl": "Provided by Matomo" }, "consent": { "vendorId": "Provided by your CMP", "iabVendorId": "" } } } } } ``` Tag Manager with consent ```json { "purple": { "analytics": { "matomo": { "configuration": { "useTagManager": "Provided by Matomo", "containerSourceUrl": "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. |