Use cases¶
Target group: Developers
Table of Contents
Page types as custom dimension¶
Depending on the URL structure, it is not easy to accumulate page views for one or more sections on a website. However, you can use an “action” custom dimension to measure these sections (such as “Blog”, “Jobs”, “Videos”).
In this use case, a page type is set for a specific page when a configured
section is available in the root line. The page type should only be available
for the trackPageView
call, so we implement an event listener based on the
EnrichTrackPageViewEvent event.
The given use case results in the following code when the current page id or a
parent page id is 167
:
// ...
_paq.push(["trackPageView", "", {"dimension2": "Blog"}]);
// ...
The event listener
The root line is available via the
TypoScriptFrontendController
class, so we inject it via the constructor into the event listener.To separate the configuration from the implementation, the ID of the custom dimension and the configuration of the page types are also injected.
The
$pageTypes
argument is a simple associative array with the page ID of the parent page of a section as the key and the value of the custom dimension as the value of the array.<?php declare(strict_types=1); namespace YourVender\YourExtension\EventListener; use Brotkrueml\MatomoIntegration\Event\EnrichTrackPageViewEvent; use TYPO3\CMS\Frontend\Controller\TypoScriptFrontendController; final class AddPageTypeToMatomoTracking { private TypoScriptFrontendController $typoScriptFrontendController; private int $customDimensionId; private array $pageTypes; public function __construct( TypoScriptFrontendController $typoScriptFrontendController, int $customDimensionId, array $pageTypes ) { $this->typoScriptFrontendController = $typoScriptFrontendController; $this->customDimensionId = $customDimensionId; $this->pageTypes = $pageTypes; } public function __invoke(EnrichTrackPageViewEvent $event): void { $pageIds = array_keys($this->pageTypes); $hits = array_filter( $this->typoScriptFrontendController->rootLine, static fn (array $page): bool => in_array($page['uid'], $pageIds) ); if ($hits === []) { return; } $pageType = $this->pageTypes[current($hits)['uid']]; $event->addCustomDimension($this->customDimensionId, $pageType); } }
Registration of the event listener in
Configuration/Services.yaml
We need to inject the custom dimension ID and the page types configuration into the event listener:
YourVender\YourExtension\EventListener\AddPageTypeToMatomoTracking: arguments: $customDimensionId: 2 $pageTypes: # key: parent page ID, value: value to set for the custom dimension 167: Blog 218: Jobs 112: Videos # ... and possibly some more types tags: - name: event.listener identifier: 'your-ext/addPageTypeToMatomoTracking' event: Brotkrueml\MatomoIntegration\Event\EnrichTrackPageViewEvent
Some more ideas how to determine the page type:
- Set the Matomo page type dependent on the TYPO3 page type.
- Use a separate field in the page properties to select the Matomo page type.
Colour scheme as custom dimension¶
If you provide your page with a light and a dark colour scheme, it might be interesting to see how many visitors prefer which colour scheme. This can be analysed in Matomo with a “visit” custom dimension.
In contrast to the use case above, where the custom dimension should only be used for tracking a page view, this custom dimension can be defined “globally” so we can use the BeforeTrackPageViewEvent event.
The given use case results in the following code:
// ...
_paq.push(["setCustomDimension", 1, window.matchMedia&&window.matchMedia("(prefers-color-scheme:dark)").matches?"dark":"light"]);
_paq.push(["trackPageView"]);
// ...
The event listener
The event provides an
addMatomoMethodCall()
method. With this method you can insert any JavaScript code, so be careful what you do. In this example, we use thewindow.matchMedia()
function to get the colour scheme currently in useAs in the use case above, the ID of the custom dimension is injected via dependency injection.
<?php declare(strict_types=1); namespace YourVendor\YourExtension\EventListener; use Brotkrueml\MatomoIntegration\Code\JavaScriptCode; use Brotkrueml\MatomoIntegration\Event\BeforeTrackPageViewEvent; final class AddColourSchemeToMatomoTracking { private int $customDimensionId; public function __construct(int $customDimensionId) { $this->customDimensionId = $customDimensionId; } public function __invoke(BeforeTrackPageViewEvent $event): void { $event->addMatomoMethodCall( 'setCustomDimension', $this->customDimensionId, new JavaScriptCode('window.matchMedia&&window.matchMedia("(prefers-color-scheme:dark)").matches?"dark":"light"') ); } }
Registration of the event listener in
Configuration/Services.yaml
YourVendor\YourExtension\EventListener\AddColourSchemeToMatomoTracking: arguments: $customDimensionId: 1 tags: - name: event.listener identifier: 'your-ext/addColourSchemeToMatomoTracking' event: Brotkrueml\MatomoIntegration\Event\BeforeTrackPageViewEvent