Matomo analytics

Purpose

A search can be performed through the API. If configured the API sends search information to Matomo. Matomo is an analytics solution. Search information consists of:

• The search text.
• An indicator whether the search included filters.
• The number of documents found.

The information is the base for reports and overviews in

• Matomo dashboards
• The Smartsite Manager, as overview widgets.

The purpose is to learn about the search behaviour of end users in order to improve the search solution.

Search information

Search information includes

• The net search text of the search specification. This is the text as typed by the end user, possibly modified by the search solution.
• An indicator whether the search included one or more filters, for example a date range filter or a terms filter. Applying filters typically reduces the number of documents found. Knowing whether filters were applied helps distinguishing between a low number of search results due to the terms used or due to the application of filters.
• The number of documents found. This includes 0: no documents found.

Matomo can register many kinds of requests. The Enterprise Search API (ES API) sends a Matomo Site Search request to the Matomo Tracking HTTP API.

Measurables and urls

The unit of measurement / analytics / reporting is a measurable. One website typically corresponds to one measurable. In Matomo there can be a measurable Contoso for the website of Contoso.

If analytics are desired include a url in the search specification as sent to the ES API, for example:

{
    ...,
    "analytics": {
        "url": "https://www.contoso.com"
    }
}

Notes:

• The url identifies the measurable to use. The configuration of the ES API includes mappings from urls to measurables.
• The url needs not to be an existing url, it only needs to match configured urls. It should be an exact match except for differences in casing.
• Multiple urls can be mapped to the same measurable, for example https://www.contoso.com and https://www.contosonews.com can both be mapped to measurable Contoso.
• No Site Search is registered if the url is omitted in the search specification, or if it does not match one of the configured urls. The ES API still performs the search itself.
• Once mapped the ES API builds a Site Search request and sends it to the correct measurable in Matomo. The request includes the url. Matomo perform a final check that the url matches one of the urls configured for the measurable, meaning that the above two urls must be configured in Matomo as well.

Suffix if the search includes filters

The search result count may be low or even 0 due to the search terms used, or due to filters applied, or due to a combination of both. If configured the ES API appends a suffix to the search text, for example " (*)", if the search specification included one or more filters. It for example appends the suffix if a date range filter was present, or a terms filter on some category.

If a suffix should be appended and the suffix itself is part of the ES API configuration. It is a suffix configuration per measurable.