Back to Qt.io
Contact Us Blog Download Qt
On this page

QInsightConfiguration Class

Configuration class for the Qt Insight Tracker. More...

Header: #include <QInsightConfiguration>
CMake: find_package(Qt6 REQUIRED COMPONENTS InsightTracker)
target_link_libraries(mytarget PRIVATE Qt6::InsightTracker)
qmake: QT += insighttracker
In QML: InsightConfiguration
Inherits: QObject

Properties

Public Functions

virtual QString appBuild() const = 0
virtual int batchSize() const = 0
virtual QStringList categories() = 0
virtual QString deviceModel() const = 0
virtual QString deviceScreenType() const = 0
virtual QString deviceVariant() const = 0
virtual QStringList events() = 0
virtual bool isValid() = 0
virtual QString platform() const = 0
virtual bool remoteConfig() const = 0
virtual int remoteConfigInterval() const = 0
virtual QString server() const = 0
virtual void setAppBuild(const QString &appBuild) = 0
virtual void setBatchSize(int batchSize) = 0
virtual void setCategories(const QStringList &categories) = 0
virtual void setDeviceModel(const QString &deviceModel) = 0
virtual void setDeviceScreenType(const QString &deviceScreenType) = 0
virtual void setDeviceVariant(const QString &deviceVariant) = 0
virtual void setEvents(const QStringList &events) = 0
virtual void setPlatform(const QString &platform) = 0
virtual void setRemoteConfig(bool enabled) = 0
virtual void setRemoteConfigInterval(int syncInterval) = 0
virtual void setServer(const QString &server) = 0
virtual void setStoragePath(const QString &storagePath) = 0
virtual void setStorageSize(int storageSize) = 0
virtual void setStorageType(const QString &storageType) = 0
virtual void setSyncInterval(int syncInterval) = 0
virtual void setToken(const QString &token) = 0
virtual void setUserId(const QString &userId) = 0
virtual QString storagePath() const = 0
virtual int storageSize() const = 0
virtual QString storageType() const = 0
virtual int syncInterval() const = 0
virtual QString token() const = 0
virtual QString userId() = 0

Signals

void appBuildChanged(const QString &appBuild)
void batchSizeChanged(int batchSize)
void categoriesChanged(const QStringList &categories)
void deviceModelChanged(const QString &deviceModel)
void deviceScreenTypeChanged(const QString &deviceScreenType)
void deviceVariantChanged(const QString &deviceVariant)
void eventsChanged(const QStringList &events)
void platformChanged(const QString &platform)
void remoteConfigChanged(bool enabled)
void remoteConfigIntervalChanged(int syncInterval)
void serverChanged(const QString &server)
void storagePathChanged(const QString &storagePath)
void storageSizeChanged(int storageSize)
void storageTypeChanged(const QString &storageType)
void syncIntervalChanged(int syncInterval)
void tokenChanged(const QString &token)
void userIdChanged(const QString &userId)

Detailed Description

Use QInsightConfiguration to configure the tracker. The tracker reads initial values from a configuration file (qtinsight.conf), which is searched from following the locations in a decending order:

  1. Application's resources file.
  2. Application's directory.
  3. Current working directory.
  4. System configuration directories as defined by QStandardPaths::GenericConfigLocation.

Use an environment variable QT_INSIGHT_CONFIG to override the used configuration file.

Example of a JSON configuration file:

{
    "server" : "collect-insight.qt.io",
    "token" : "00000000-0000-0000-0000-000000000000",
    "device_model" :  "model 1",
    "device_variant" : "a",
    "device_screen_type" : "NON_TOUCH",
    "platform" : "app",
    "app_build" : "1.2.3",
    "storage" : "SQLITE",
    "storage_path" : "",
    "storage_size" : 0,
    "sync" : {
        "interval" : {
            "seconds" : 0,
            "minutes" : 0,
            "hours" : 1,
            "days" : 0,
            "months" : 0
        },
        "max_batch_size" : 100
    },
    "config_sync" : {
        "enabled" : true
        "interval" : {
            "seconds" : 0,
            "minutes" : 0,
            "hours" : 0,
            "days" : 1,
            "months" : 0
        },
    },
    "categories" : [
        "debug"
    ],
    "events" : [
        "KeyPress",
        "KeyRelease",
        "MouseButtonPress",
        "MouseButtonRelease",
        "Quit",
        "Resize"
    ]
}

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.

Some of the configuration items are directly linked to the Snowblow Tracker Protocol, which defines the allowed values. These include QInsightConfiguration::setPlatform() and QInsightConfiguration::setDeviceScreenType().

Use QInsightConfiguration::setStorageType() to configure the storage type, where SQLITE is the default value and uses SQLite database to store the events before they are sent to the back-end server. Caching is disabled if an unknown storage type is specified, SQLite support is not available in Qt, or value is explicitly set to an empty string. In that case the tracked data is lost if the back-end server isn't available.

Two additional storage types are supported: SQLITE-ZLIB and SQLITE-ZSTD. These provide sqlite storage but compress the event data to save disk space. Both zlib and zstd algorithms are used with a dictionary-based compression where the dictionary is created from the first collected events. In general, zstd offers faster compression with higher compression ratio, but requires more memory to train the dictionary.

Use QInsightConfiguration::setStoragePath() to configure the location of the storage. By default, the SQLite database is created in the application's directory.

Use QInsightConfiguration::setStorageSize() to limit the number of events that can be cached. When using SQLITE storage type, the oldest events are removed if storage size is exceeded. The default size (0) sets no limits to the storage size.

Use QInsightConfiguration::setSyncInterval() to configure how often the tracked events are sent to the back-end server. The API takes the value in seconds, while the json configuration file can be configured also with minutes, hours, days, and months. If sync interval is not set, events will never be sent to the backend and cached only in the local storage.

Use QInsightConfiguration::setBatchSize() to minimize the overhead when sending, reading and writing to the storage. When synchronizing the cached data to back-end server, at most QInsightConfiguration::batchSize() items will be fetched at once from the storage and sent to back-end server. This is more optimal than fetching the data one by one. The sent data will be removed from the storage also in batches. The process repeats until all data is sent. If one batch fails the synchronization stops as the following batches are likely to also fail.

Use QInsightConfiguration::setRemoteConfig and QInsightConfiguration::setRemoteConfigInterval() to enable the use of remote configurations and configure how often the remote configurations are synced from the back-end server. The API takes the value in seconds, while the json configuration file can be configured also with minutes, hours, days, and months. If QInsightConfiguration::setRemoteConfigInterval() is not set, the interval from QInsightConfiguration::SyncInterval() is used.

QInsightConfiguration::setCategories() allows filtering of tracked events based on the category used in the API calls for QInsightTracker::interaction() and QInsightTracker::transition() events or the attached property InsightCategory::category for the automatic QEvent::type events.

Use QInsightConfiguration::setEvents() to enable tracking of automatic events from Qt's event system. All valid event types in QEvent::Type can be used.

Property Documentation

appBuild : QString

This property holds the application build version.

Specifies the build version or identifier of the application. This helps track which version of the application generated the telemetry data.

Access functions:

virtual QString appBuild() const = 0
virtual void setAppBuild(const QString &appBuild) = 0

Notifier signal:

void appBuildChanged(const QString &appBuild)

batchSize : int

This property holds the batch size for synchronization.

Specifies the maximum number of events to fetch and send in a single batch when synchronizing with the back-end server. This minimizes overhead when reading, writing, and sending data.

The default value is 100.

Access functions:

virtual int batchSize() const = 0
virtual void setBatchSize(int batchSize) = 0

Notifier signal:

void batchSizeChanged(int batchSize)

categories : QStringList

This property holds the list of event categories to track.

Filters tracked events based on their category. Only events with categories in this list will be tracked. Categories are used in API calls to QInsightTracker::interaction() and QInsightTracker::transition(), or in the InsightCategory::category attached property for automatic QEvent tracking.

Access functions:

virtual QStringList categories() = 0
virtual void setCategories(const QStringList &categories) = 0

Notifier signal:

void categoriesChanged(const QStringList &categories)

deviceModel : QString

This property holds the device model identifier.

Specifies the model identifier for the device running the application. This helps differentiate telemetry data across different hardware models.

Access functions:

virtual QString deviceModel() const = 0
virtual void setDeviceModel(const QString &deviceModel) = 0

Notifier signal:

void deviceModelChanged(const QString &deviceModel)

deviceScreenType : QString

This property holds the device screen type.

Specifies the screen type of the device. Valid values are defined by the Snowplow Tracker Protocol, such as TOUCH or NON_TOUCH.

Access functions:

virtual QString deviceScreenType() const = 0
virtual void setDeviceScreenType(const QString &deviceScreenType) = 0

Notifier signal:

void deviceScreenTypeChanged(const QString &deviceScreenType)

deviceVariant : QString

This property holds the device variant identifier.

Specifies a variant identifier for the device, such as different configurations or SKUs of the same model.

Access functions:

virtual QString deviceVariant() const = 0
virtual void setDeviceVariant(const QString &deviceVariant) = 0

Notifier signal:

void deviceVariantChanged(const QString &deviceVariant)

event : QStringList

This property holds the list of Qt events to track automatically.

Specifies which Qt event types from the event system should be automatically tracked. Any valid QEvent::Type can be used, such as KeyPress, MouseButtonPress, or Quit.

Access functions:

virtual QStringList events() = 0
virtual void setEvents(const QStringList &events) = 0

Notifier signal:

void eventsChanged(const QStringList &events)

platform : QString

This property holds the platform identifier.

Specifies the platform on which the application is running. Valid values are defined by the Snowplow Tracker Protocol and include web, mob, pc, srv, app, tv, cnsl, and iot.

The default value is app.

Access functions:

virtual QString platform() const = 0
virtual void setPlatform(const QString &platform) = 0

Notifier signal:

void platformChanged(const QString &platform)

remoteConfig : bool

This property holds whether remote configuration is enabled.

Enables or disables the use of remote configurations from the back-end server. When enabled, configuration settings can be updated remotely without requiring an application update.

Access functions:

virtual bool remoteConfig() const = 0
virtual void setRemoteConfig(bool enabled) = 0

Notifier signal:

void remoteConfigChanged(bool enabled)

remoteConfigInterval : int

This property holds the remote configuration synchronization interval in seconds.

Specifies how often the remote configuration is synced from the back-end server, in seconds. If not set, the value from syncInterval is used.

Access functions:

virtual int remoteConfigInterval() const = 0
virtual void setRemoteConfigInterval(int syncInterval) = 0

Notifier signal:

void remoteConfigIntervalChanged(int syncInterval)

server : QString

This property holds the back-end server URL.

Specifies the URL of the Qt Insight back-end server where tracked events are sent. For example, collect-insight.qt.io.

Access functions:

virtual QString server() const = 0
virtual void setServer(const QString &server) = 0

Notifier signal:

void serverChanged(const QString &server)

storagePath : QString

This property holds the path where events are stored.

Specifies the directory where the SQLite database or other storage files are created. By default, the database is created in the application's directory.

Access functions:

virtual QString storagePath() const = 0
virtual void setStoragePath(const QString &storagePath) = 0

Notifier signal:

void storagePathChanged(const QString &storagePath)

storageSize : int

This property holds the maximum number of cached events.

Limits the number of events that can be cached. When using SQLite storage and this limit is exceeded, the oldest events are removed.

A value of 0 (default) sets no limits to the storage size.

Access functions:

virtual int storageSize() const = 0
virtual void setStorageSize(int storageSize) = 0

Notifier signal:

void storageSizeChanged(int storageSize)

storageType : QString

This property holds the storage type for cached events.

Specifies how events are stored before being sent to the back-end server. Valid values are:

  • SQLITE - Uses SQLite database (default).
  • SQLITE-ZLIB - Uses SQLite with zlib compression.
  • SQLITE-ZSTD - Uses SQLite with zstd compression.
  • Empty string - Disables caching.

If caching is disabled, tracked data is lost if the back-end server isn't available.

The default value is SQLITE.

Access functions:

virtual QString storageType() const = 0
virtual void setStorageType(const QString &storageType) = 0

Notifier signal:

void storageTypeChanged(const QString &storageType)

syncInterval : int

This property holds the synchronization interval in seconds.

Specifies how often the tracked events are sent to the back-end server, in seconds. If sync interval is not set or is 0, events will never be sent automatically and will only be cached in local storage.

Access functions:

virtual int syncInterval() const = 0
virtual void setSyncInterval(int syncInterval) = 0

Notifier signal:

void syncIntervalChanged(int syncInterval)

token : QString

This property holds the authentication token.

The token is used to match the data your application sends to your Qt Insight Organization. You can find your token from the Qt Insight Console.

Access functions:

virtual QString token() const = 0
virtual void setToken(const QString &token) = 0

Notifier signal:

void tokenChanged(const QString &token)

userId : QString

This property holds the user identifier.

Specifies an identifier for the current user. This can be used to track usage patterns across sessions or devices for the same user.

Access functions:

virtual QString userId() = 0
virtual void setUserId(const QString &userId) = 0

Notifier signal:

void userIdChanged(const QString &userId)

[read-only] valid : const bool

This property holds whether the configuration is valid.

This property indicates if the tracker configuration is properly initialized and ready for use.

Access functions:

virtual bool isValid() = 0

Member Function Documentation

[pure virtual] QString QInsightConfiguration::appBuild() const

Returns current application's build version.

Note: Getter function for property appBuild.

See also setAppBuild().

[pure virtual] int QInsightConfiguration::batchSize() const

Returns current sync batch size.

Note: Getter function for property batchSize.

See also setBatchSize().

[pure virtual] QStringList QInsightConfiguration::categories()

Returns currently enabled categories.

Note: Getter function for property categories.

See also setCategories().

[pure virtual] QString QInsightConfiguration::deviceModel() const

Returns current device model.

Note: Getter function for property deviceModel.

See also setDeviceModel().

[pure virtual] QString QInsightConfiguration::deviceScreenType() const

Returns current screen type.

Note: Getter function for property deviceScreenType.

See also setDeviceScreenType().

[pure virtual] QString QInsightConfiguration::deviceVariant() const

Returns current device variant.

Note: Getter function for property deviceVariant.

See also setDeviceVariant().

[pure virtual] QStringList QInsightConfiguration::events()

Returns currently tracked events types.

Note: Getter function for property event.

See also setEvents().

[pure virtual] bool QInsightConfiguration::isValid()

Returns true if configuration is valid.

Note: Getter function for property valid.

[pure virtual] QString QInsightConfiguration::platform() const

Returns current platform.

Note: Getter function for property platform.

See also setPlatform().

[pure virtual] bool QInsightConfiguration::remoteConfig() const

Returns true if remote configuration sync is enabled.

Note: Getter function for property remoteConfig.

See also setRemoteConfig().

[pure virtual] int QInsightConfiguration::remoteConfigInterval() const

Returns current remote configuration sync interval in seconds.

Note: Getter function for property remoteConfigInterval.

See also setRemoteConfigInterval().

[pure virtual] QString QInsightConfiguration::server() const

Returns current back-end server address.

Note: Getter function for property server.

See also setServer().

[pure virtual] void QInsightConfiguration::setAppBuild(const QString &appBuild)

Set application's build version appBuild.

Note: Setter function for property appBuild.

See also appBuild().

[pure virtual] void QInsightConfiguration::setBatchSize(int batchSize)

Set sync batch size to batchSize. Defines how many events are sent to network in one go.

Note: Setter function for property batchSize.

See also batchSize().

[pure virtual] void QInsightConfiguration::setCategories(const QStringList &categories)

Set list of enabled categories to categories.

Note: Setter function for property categories.

See also categories().

[pure virtual] void QInsightConfiguration::setDeviceModel(const QString &deviceModel)

Set device model to deviceModel.

Note: Setter function for property deviceModel.

See also deviceModel().

[pure virtual] void QInsightConfiguration::setDeviceScreenType(const QString &deviceScreenType)

Set device screen type to deviceScreenType.

Note: Setter function for property deviceScreenType.

See also deviceScreenType().

[pure virtual] void QInsightConfiguration::setDeviceVariant(const QString &deviceVariant)

Set device variant to deviceVariant.

Note: Setter function for property deviceVariant.

See also deviceVariant().

[pure virtual] void QInsightConfiguration::setEvents(const QStringList &events)

Set list of tracked event types to events. All valid event types in QEvent::Type can be used.

Note: Setter function for property event.

See also events().

[pure virtual] void QInsightConfiguration::setPlatform(const QString &platform)

Set platform to platform

Note: Setter function for property platform.

See also platform().

[pure virtual] void QInsightConfiguration::setRemoteConfig(bool enabled)

Set remote configuration sync state to enabled.

Note: Setter function for property remoteConfig.

See also remoteConfig().

[pure virtual] void QInsightConfiguration::setRemoteConfigInterval(int syncInterval)

Set remote configuration sync interval to syncInterval seconds.

Note: Setter function for property remoteConfigInterval.

See also remoteConfigInterval().

[pure virtual] void QInsightConfiguration::setServer(const QString &server)

Set server address to server.

Note: Setter function for property server.

See also server().

[pure virtual] void QInsightConfiguration::setStoragePath(const QString &storagePath)

Set storage path to storagePath.

Note: Setter function for property storagePath.

See also storagePath().

[pure virtual] void QInsightConfiguration::setStorageSize(int storageSize)

Set storage size to storageSize.

Note: Setter function for property storageSize.

See also storageSize().

[pure virtual] void QInsightConfiguration::setStorageType(const QString &storageType)

Set storage type to storageType.

Note: Setter function for property storageType.

See also storageType().

[pure virtual] void QInsightConfiguration::setSyncInterval(int syncInterval)

Set sync interval to syncInterval seconds.

Note: Setter function for property syncInterval.

See also syncInterval().

[pure virtual] void QInsightConfiguration::setToken(const QString &token)

Set server token to token.

Note: Setter function for property token.

See also token().

[pure virtual] void QInsightConfiguration::setUserId(const QString &userId)

Set user identifier to userId. If userId is empty, a generated random UUID will be used.

Note: Setter function for property userId.

See also userId().

[pure virtual] QString QInsightConfiguration::storagePath() const

Returns current storage path.

Note: Getter function for property storagePath.

See also setStoragePath().

[pure virtual] int QInsightConfiguration::storageSize() const

Returns current storage size.

Note: Getter function for property storageSize.

See also setStorageSize().

[pure virtual] QString QInsightConfiguration::storageType() const

Returns current storage type.

Note: Getter function for property storageType.

See also setStorageType().

[pure virtual] int QInsightConfiguration::syncInterval() const

Returns current sync interval in seconds.

Note: Getter function for property syncInterval.

See also setSyncInterval().

[pure virtual] QString QInsightConfiguration::token() const

Returns current server token.

Note: Getter function for property token.

See also setToken().

[pure virtual] QString QInsightConfiguration::userId()

Returns current user identifier used in the tracked events.

Note: Getter function for property userId.

See also setUserId().

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.