Display search metrics from TYPO3 extension ke_search in Matomo
- TYPO3 v10
- TYPO3 v11
Finally you have built a search function into your TYPO3 website with the extension ke_search. Users start searching. Wouldn't it be nice if you could see the search phrases used? Since version 3.6 the extensions ships with a dashboard widget which displays the search phrases over the last seven days. But that might not be enough:
- The owner of a website may want to monitor the search terms and their trend over time.
- Interesting are search terms for which there are no results. The website can be optimised for these phrases.
- An administrator would like to know the query time for the search over time in order to identify possible bottlenecks at an early stage.
Since I am using Matomo for tracking page views (and some other topics) of a website, it would be useful to have these metrics in this analysis tool as well. All three aspects mentioned above can be solved with Matomo — and you get a few more features on top. The tricky part is to get these metrics from the extension to Matomo.
Matomo also offers a report for search phrases without a result. This is possible with a query parameter that is added to the current URL and evaluated by Matomo. But for that a custom URL for Matomo has to be set before the trackPageView call which can be difficult depending how the Matomo snippet is embedded.
The ke_search extension also provides the query time of a result set, i.e. how long it takes to retrieve the results. This can be stored in Matomo using a custom dimension.
_paq.push(["trackSiteSearch", // Search keyword searched for "Banana", // Search category selected in your search engine. If you do not need this, set to false "Organic Food", // Number of results on the Search results page. Zero indicates a 'No Result Search Keyword'. // Set to false if you don't know 0 ]);
What is not mentioned in the documentation: There is a 4th argument available:
customData. If you provide a JSON with key/value pairs, this data will be added as query parameters to the resulting tracking call. This way we can also add the custom dimension for the query time (and some more if necessary).
This way, we don't have to configure the query parameters in Matomo, because we do everything ourselves. Only the search site feature for the website has to be activated in Matomo.
One way to pass the search metrics from the ke_search plugin to a PSR-14 event provided by the Matomo Integration extension is to use a transient cache. This cache stores the specified data in memory and is only valid in the same request — perfect for our use case.
Note: The following code examples are written for use in TYPO3 v11 and with PHP 8.1. However, they can be easily adapted for TYPO3 v10 and older PHP versions.
First we have to register the transient cache:
As we want to use dependency injection to provide the cache, we define our transient cache as a service:
To store the metrics in the transient cache, the "modifyResultList" hook of ke_search can be used. This hook provides all the necessary values:
modifyResultList() method, we do not modify the results, but store the metrics in the transient cache.
The cache is injected into the constructor. We need to define the
$cache argument for the constructor in Services.yaml as it is not autowirable. Additionally, the hook class must be declared public:
We also need to register our new hook within ke_search:
The Matomo integration extension provides a PSR-14 event to track the site search: TrackSiteSearchEvent. Let's create an event listener:
Since the code is pretty self-explanatory, one more note about the custom dimension: As Matomo displays each individual dimension value separately, we have to aggregate them beforehand via the
getQueryTimeRange() method to get analysable data.
The last thing we need to do is to register our event listener:
After processing all the steps above we are rewarded with an analysis of our site search metrics in Matomo:
Take a look at the Matomo Widgets extension, which provides dashboard widgets for Matomo in TYPO3 — also for displaying search phrases and custom dimensions.