Qt Insight Tracker Overview

Tracking Application Usage

You can use Qt Insight Tracker from your application code to track application usage with two event types: interactions and transitions.

Use transition events to track the current state of the UI. Transition events can be sent whenever your application changes UI views or states, or whenever there are other UI flow changes such as dialog and notification pop-ups.

From QML code, this can be done for example with:

onStateChanged: InsightTracker.transition(applicationFlow.state);

Use interaction events to track which part of UI users interact with. Interaction events automatically include the current state of the UI, as reported using the transition event. Individual UI elements can send the event with QML code:

function themeButton() {
    if (Colors.currentTheme == Colors.dark) {
        Colors.currentTheme = Colors.light
    } else {
        Colors.currentTheme = Colors.dark
    }

    InsightTracker.interaction("theme", "dark theme", Colors.currentTheme == Colors.dark);
}

Some additional information about the device (model, variant, screen resolution, and screen type) and the application (version, build, and Qt version) is sent automatically on the application start.

A UUID is generated on the first use of Qt Insight Tracker and used in all the events sent to the back-end server. It can identify all the events coming from one particular device but not individual users.

Automatic Event Tracking

Qt Insight Tracker can track any event handled by the Qt's event system. Tracking these event does not require any changes to the application, unlike the interaction and transition events. All valid event types in QEvent::Type can be used. Events are not tracked by default and you need to add events types that you want to track to the JSON configuration file.

Enabling Tracking

Qt Insight Tracker does not collect or send any data unless the application explicitly enables it through the API. The application must have user's concent before enabling the tracking.

Configuration

You can configure Qt Insight Tracker with a JSON configuration file and with C++ and QML APIs. The configuration file is read at startup and you can change the values from application code. You must make all configuration changes before enabling the tracking.

To configure Qt Insight Tracker using a configuration file, add the following JSON file:

{
    "server" : "collect-insight.qt.io",
    "token" : "00000000-0000-0000-0000-000000000000",
}

A token is used to match the data your application sends to your Qt Insight Organization and you can find your token from the Qt Insight Console.

To configure Qt Insight Tracker from your application, add the following to your QML code:

InsightConfiguration {
    token: "1234"
    syncInterval: 3600
}

or your C++ code:

QInsightTracker tracker;
tracker.configuration().syncInterval(3600);

For more details on the configuration file syntax and the API, see QInsightConfiguration.

Event Caching

By default, the tracked events are cached locally before being sent to the back-end server. The tracked info is then retained if network connectivity is not available or the application exits before the data has been sent. An SQLite database is used for caching, but the implementation allows adding other storage types later.

Event Filtering

Certain events can be filtered before they are sent to the back-end server. This can be done with categories which can be attached to the QML components using InsightCategory or used in the API calls.

Then you can configure the tracker with QInsightConfiguration::setCategories() to only track events with matching category.

Offline Usage

You can configure Qt Insight Tracker to work in an offline mode, which means that events are tracked normally to the local event cache but they are never sent to the back-end server. This is useful for devices that do not have network connectivity. To turn on offline mode, omit the sync interval from the configuration json or set all values to zero.

Qt Insight Tracker comes with a separate command-line utility (Qt Insight Uploader) that you can use to send the events to the back-end at a later time. You need to retrive the database file from the device and then run the insightuploader utility on your PC.