Developer corner¶
Target group: Developers
Table of Contents
Objects¶
A data object is available for use in the PSR-14 events:
JavaScriptCode¶
The Brotkrueml\MatomoIntegration\Code\JavaScriptCode
object holds a piece
of arbitrary JavaScript code used in the BeforeTrackPageViewEvent,
AfterTrackPageViewEvent and AddToDataLayerEvent events. This
object is necessary to distinguish between a “normal” string and JavaScript code
for later embedding.
Example:
$javaScriptCode = new Brotkrueml\MatomoIntegration\Code\JavaScriptCode(
'/* some JavaScript code */'
);
The object provides the following method:
-
__toString():
string
¶
Returns the JavaScript code.
PSR-14 events¶
To enrich Matomo’s JavaScript tracking code with additional calls, PSR-14 events are available.
See also
You can find more information about PSR-14 events in the blog article PSR-14 Events in TYPO3 and the official TYPO3 documentation.
BeforeTrackPageViewEvent¶
This event can be used to add calls before the embedding of the
trackPageView
code.
This can be helpful when you want to adjust the document title or to add custom dimensions.
The event provides the following methods:
-
addJavaScriptCode(string
$code): void
¶
Adds a JavaScript code snippet.
-
addMatomoMethodCall(string
$method
,
...$parameters):
void
¶
Adds a Matomo method call for the given method and optional parameters.
The value can be of type: array
, bool
, int
,
float
, string
or
Brotkrueml\MatomoIntegration\Code\JavaScriptCode
.
Example¶
The given example results in the following code:
// ...
_paq.push(["setDocumentTitle", "Some Document Title"]);
_paq.push(["trackPageView"]);
// ...
or (for illustration of the usage of the
Brotkrueml\MatomoIntegration\Code\JavaScriptCode
object):
// ...
function getDocumentTitle { return "Some Document Title"; }
_paq.push(["setDocumentTitle", getDocumentTitle()]);
_paq.push(["trackPageView"]);
// ...
Create the event listener
<?php declare(strict_types=1); namespace YourVender\YourExtension\EventListener; use Brotkrueml\MatomoIntegration\Event\BeforeTrackPageViewEvent; final class SetDocumentTitleExample { public function __invoke(BeforeTrackPageViewEvent $event): void { // Set the document title $event->addMatomoMethodCall('setDocumentTitle', 'Some Document Title'); // OR: // Add some JavaScript code $event->addJavaScriptCode('function getDocumentTitle { return "Some Document Title"; }'); // Set the document title $event->addMatomoMethodCall('setDocumentTitle', new JavaScriptCode('getDocumentTitle()');]); } }
Register your event listener in
Configuration/Services.yaml
services: YourVendor\YourExtension\EventListener\SetDocumentTitleExample: tags: - name: event.listener identifier: 'setDocumentTitleExample' event: Brotkrueml\MatomoIntegration\Event\BeforeTrackPageViewEvent
EnrichTrackPageViewEvent¶
This event can be used to enrich the trackPageView
call with a page title
and/or a custom dimension only for the page view.
The event provides the following methods:
-
setPageTitle(string
$pageTitle): void
¶
Sets the page title.
-
addCustomDimension(int
$id
,
string
$value): void
¶
Adds a custom dimension with the given ID and value.
Example¶
The given example results in the following code:
// ...
_paq.push(["trackPageView", "Some Page Title", {"dimension3": "Some Custom Dimension Value"}]);
// ...
Create the event listener
<?php declare(strict_types=1); namespace YourVender\YourExtension\EventListener; use Brotkrueml\MatomoIntegration\Event\EnrichTrackPageViewEvent; final class SomeEnrichTrackPageViewExample { public function __invoke(EnrichTrackPageViewEvent $event): void { // You can set another page title $event->setPageTitle('Some Page Title'); // And/or you can set a custom dimension only for the track page view call $event->addCustomDimension(3, 'Some Custom Dimension Value'); } }
Register your event listener in
Configuration/Services.yaml
services: YourVendor\YourExtension\EventListener\SomeEnrichTrackPageViewExample: tags: - name: event.listener identifier: 'someEnrichTrackPageViewExample' event: Brotkrueml\MatomoIntegration\Event\EnrichTrackPageViewEvent
AfterTrackPageViewEvent¶
This event can be used to add calls after the embedding of the
trackPageView
code.
The event provides the following methods:
-
addJavaScriptCode(string
$code): void
¶
Adds a JavaScript code snippet.
-
addMatomoMethodCall(string
$method
,
...$parameters):
void
¶
Adds a Matomo method call for the given method and optional parameters.
The value can be of type: array
, bool
, int
,
float
, string
or
Brotkrueml\MatomoIntegration\Code\JavaScriptCode
.
Example¶
The given example results in the following code:
// ...
_paq.push(["trackPageView"]);
_paq.push(["enableHeartBeatTimer", 30]);
// ...
Create the event listener
<?php declare(strict_types=1); namespace YourVender\YourExtension\EventListener; use Brotkrueml\MatomoIntegration\Event\AfterTrackPageViewEvent; final class EnableHeartBeatTimerWithActiveSecondsExample { public function __invoke(AfterTrackPageViewEvent $event): void { $event->addMatomoMethodCall('enableHeartBeatTimer', 30); } }
Register your event listener in
Configuration/Services.yaml
services: YourVendor\YourExtension\EventListener\EnableHeartBeatTimerWithActiveSecondsExample: tags: - name: event.listener identifier: 'enableHeartBeatTimerWithActiveSecondsExample' event: Brotkrueml\MatomoIntegration\Event\BeforeTrackPageViewEvent
AddToDataLayerEvent¶
With this event you can add variables to the Matomo tag manager data layer.
The event provides the following method:
-
addVariable(string
$name
,
$value):
void
¶
Adds a variable with a name and value. The value can be of type:
string
, int
, float
or
Brotkrueml\MatomoIntegration\Code\JavaScriptCode
.
Example¶
The given example results in the following code:
var _mtm=window._mtm||[];
_mtm.push({"mtm.startTime": (new Date().getTime()), "event": "mtm.Start", "orderTotal": 4545.45, "orderCurrency": "EUR"});
// ...
The mtm.startTime
and event
variables are added always by default.
Create the event listener
<?php declare(strict_types=1); namespace YourVender\YourExtension\EventListener; use Brotkrueml\MatomoIntegration\Event\AddToDataLayerEvent; final class AddOrderDetailsToDataLayerExample { public function __invoke(AddToDataLayerEvent $event): void { $event->addVariable('orderTotal', 4545.45); $event->addVariable('orderCurrency', 'EUR'); } }
Register your event listener in
Configuration/Services.yaml
services: YourVendor\YourExtension\EventListener\AddOrderDetailsToDataLayerExample: tags: - name: event.listener identifier: 'addOrderDetailsToDataLayerExample' event: Brotkrueml\MatomoIntegration\Event\AddToDataLayerEvent