Matomo Qt SDK

C++ Qt SDK for the Matomo Tracking HTTP API.

Status: early development. The SDK exposes C++ and QML targets, sends Matomo Tracking HTTP API requests asynchronously and includes a runnable QML example. The public API may still evolve before the first stable release.

Project Context

This project was started to support Matomo integration in the kDrive desktop application on Linux.

The SDK itself is not kDrive-specific. It is designed to stay reusable by any Qt or QML application that needs to send tracking data to a Matomo instance. Product-specific event names, routes, identifiers and business metadata should be defined by the host application, not by this library.

Goals

• Provide a Qt-native SDK for Matomo tracking.
• Support both C++ and QML applications.
• Keep the core library independent from any product-specific taxonomy.
• Make privacy, consent, GDPR and Swiss FADP/nLPD-oriented integration explicit in the public API.
• Stay testable without requiring a live Matomo server.
• Remain easy to consume from a parent CMake project.

Scope

The repository builds the MatomoQt::Core target and can optionally build the MatomoQt::Qml module. The core target depends on:

• Qt6::Core
• Qt6::Network

The public API includes:

• tracking and privacy-oriented value types such as Tracker, TrackerConfig, PageView, Event, ConsentState, PrivacyMode, RequestResult, ConsentStore and ClientIdStore;
• RequestBuilder builds page view, event and ping requests for the Matomo Tracking HTTP API without sending them;
• RequestBuildOptions carries optional request context such as client ID, User-Agent, language and screen resolution;
• RequestBuildResult and TrackingRequest expose the build status and the generated URL;
• UserAgentBuilder can generate desktop User-Agent strings with DeviceDetector-compatible OS tokens.
• NetworkDispatcher sends built tracking URLs over HTTP with QNetworkAccessManager, timeout, circuit breaker and rand cache-busting; it never silently ignores SSL errors and never logs full tracking URLs.

Tracker orchestrates privacy checks, request building and asynchronous network dispatching. Tracking calls report local acceptance synchronously, while dispatchFinished() reports the eventual network result.

Non-Goals

This SDK does not aim to collect application-specific identifiers, file paths, file names, emails, usernames or other personally identifiable business data.

Automatic QML page introspection, ecommerce tracking, heatmaps, session recording and Matomo administration APIs are outside the initial scope.

Build

Requirements:

• CMake 3.16 or newer
• C++20 compiler
• Qt 6 with Core and Network

Configure and build:

cmake -S . -B build -DMATOMOQT_BUILD_TESTS=ON
cmake --build build
ctest --test-dir build --output-on-failure

Useful options:

-DMATOMOQT_BUILD_TESTS=ON
-DMATOMOQT_BUILD_QML=ON
-DMATOMOQT_BUILD_EXAMPLES=ON
-DMATOMOQT_INSTALL=ON
-DMATOMOQT_WARNINGS_AS_ERRORS=ON

CMake Consumption

As a subdirectory:

add_subdirectory(path/to/matomo-sdk-qt)
target_link_libraries(my_app PRIVATE MatomoQt::Core)

After installation:

find_package(MatomoQt CONFIG REQUIRED)
target_link_libraries(my_app PRIVATE MatomoQt::Core)

QML applications can link MatomoQt::Qml and import MatomoQt from QML.

Minimal C++ Example

#include <MatomoQt/PageView.h>
#include <MatomoQt/RequestBuilder.h>
#include <MatomoQt/UserAgentBuilder.h>
#include <MatomoQt/TrackerConfig.h>

#include <QtCore/QString>
#include <QtCore/QUrl>

MatomoQt::TrackerConfig config;
config.endpoint = QUrl(QStringLiteral("https://matomo.example.com/matomo.php"));
config.actionUrlBase = QUrl(QStringLiteral("app://desktop/"));
config.siteId = 1;

MatomoQt::RequestBuilder requestBuilder(config);
const auto userAgent = MatomoQt::UserAgentBuilder::buildDesktopUserAgent(
        MatomoQt::UserAgentBuilder::currentDesktopInfo(
                QStringLiteral("ExampleApp"),
                QStringLiteral("1.0.0")));

const auto requestResult = requestBuilder.buildPageView(
        {
                .path = QStringLiteral("preferences"),
                .actionName = QStringLiteral("Preferences"),
        },
        {
                .userAgent = userAgent,
                .language = QStringLiteral("fr-CH"),
                .screenResolution = QStringLiteral("1920x1080"),
        });

if (requestResult.accepted()) {
    const QUrl trackingUrl = requestResult.request.url;
    // The host application decides when and how to send the URL.
}

This builds the tracking URL only.

QML Example

A runnable QML example lives in examples/qml-basic. It shows a minimal MatomoTracker singleton wired to consent buttons and tracking calls; no tracking is sent before the user explicitly grants consent.

cmake -S . -B build -DMATOMOQT_BUILD_QML=ON -DMATOMOQT_BUILD_EXAMPLES=ON
cmake --build build
./build/examples/qml-basic/matomoqt-example-qml-basic

By default the example points at http://127.0.0.1:8080/matomo.php; edit examples/qml-basic/qml/Main.qml to point it at your own Matomo instance (e.g. a local Matomo docker-compose.yml for testing, or a real server) to see tracked hits.

MatomoTracker is exposed as a QML singleton, so you configure and call it directly by type name rather than instantiating it. The PrivacyMode, ConsentState, RequestStatus and DispatchStatus enums are exported as QML namespaces. Tracking methods report local acceptance immediately; use MatomoTracker.dispatchFinished for the eventual network result.

import QtQuick
import QtQuick.Controls
import MatomoQt

Button {
    text: qsTr("Grant consent and track")

    Component.onCompleted: {
        // MatomoTracker is a singleton — configure it directly.
        MatomoTracker.endpoint = "https://matomo.example.com/matomo.php"
        MatomoTracker.actionUrlBase = "app://my-app/"
        MatomoTracker.siteId = 1
        MatomoTracker.privacyMode = PrivacyMode.RequiresConsent
    }

    onClicked: {
        // Only after explicit user consent:
        MatomoTracker.grantConsent()
        MatomoTracker.trackPageView("/settings", "Settings")
        MatomoTracker.trackEvent("preferences", "click", "saveButton", 1)
    }
}

Privacy Model

The SDK is intended to provide GDPR and Swiss FADP/nLPD-oriented, privacy-ready primitives, not to make a host application compliant by itself. It should help applications make tracking explicit, consent-aware and testable.

The SDK should support:

• no tracking before explicit configuration;
• explicit consent and opt-out states;
• resettable client identifiers;
• minimal data collection by default;
• deterministic tests for privacy-sensitive behavior.

The host application remains responsible for its legal basis, user notice, consent or opt-out UX, Matomo server settings, retention policy and data subject workflows. Server-side Matomo configuration, such as IP anonymization, retention rules and visitor profile settings, is also part of the compliance story.

Roadmap

The next development areas are expected to focus on:

• Consent and opt-out behavior in the tracker flow.
• Network dispatch with deterministic tests.
• Manual QML tracking APIs.
• Small C++ and QML examples.
• Install-tree validation and package consumption.

This roadmap is intentionally high level and may change as the public API stabilizes.

License

Apache License 2.0. See LICENSE.