Warning, /libraries/kuserfeedback/README.md is written in an unsupported language. File is not indexed.

0001 # KUserFeedback
0003 Framework for collecting feedback from application users via telemetry and targeted surveys.
0005 ## Telemetry
0007 * Extensible set of data sources for telemetry.
0008 * Full control for the user on what data to contribute.
0010 ## Surveys
0012 * Distribute surveys and offer users to participate in them.
0013 * Survey targeting based on telemetry data.
0014 * Allow the user to configure how often they want to participate in surveys.
0016 ## Components
0018 This framework consists of the following components:
0019 * Libraries for use in applications.
0020 * QML bindings for the above.
0021 * A server application.
0022 * A management and analytics application.
0024 ## Integration
0025 To use this framework in your application, on a high level you have to do
0026 the following steps inside your program:
0027 * Create an instance of KUserFeedback::Provider for the entire lifetime of your
0028   application, and configure it as described in its documentation.
0029 * Add one or more data sources to the provider, choosing from the standard
0030   built-in ones, or by adding custom ones deriving from KUserFeedback::AbstractDataSource.
0031 * Add a way to notify your users about surveys, and to encourage them to contriubute
0032   in the first place, by hooking a suitable user interface up with the corresponding
0033   signals in UserFeedback::Provider. KUserFeedback::NotificationPopup provides a
0034   reference widget for this purpose.
0035 * Add a way for your users to configure what data to contribute, and how often
0036   to be bothered by surveys. KUserFeedback::FeedbackConfigDialog provides a
0037   reference implementation of a configuration dialog for this.
0039 ## Deployment
0040 For information on how to deploy the server parts, please see the
0041 [INSTALL](https://commits.kde.org/kuserfeedback?path=INSTALL) file.
0043 ## Usage Documentation
0044 Information on how to use KUserFeedback from a product manager point of view can
0045 be found in the user manual of UserFeedbackConsole. Start UserFeedbackConsole and
0046 press `F1` to get to the user manual.
0048 ## Frequently Asked Questions
0050 _Why does the telemetry data contain no unique user/installation/machine id?_
0052 KUserFeedback is designed to be compliant with [KDE Telemetry Policy](https://community.kde.org/Policies/Telemetry_Policy),
0053 which forbids the usage of unique identification.
0054 If you are using KUserFeedback outside of the scope of that policy, it's of course
0055 possible to add a custom data source generating and transmitting a unique id.
0057 _How can duplicated submissions be detected without unique identification?_
0059 KUserFeedback addresses this by using a fixed time interval for telemetry data submission.
0060 If for example Provider::submissionInterval is set to one week, aggregating data in one
0061 week intervals ensures that there's only at most one sample included from each installation.
0062 The other way around, setting Provider::submissionInterval at least as high as the average
0063 usage interval of your application ensures a substantial amount of installations have
0064 submitted a sample in this interval. A frequently used application such e.g. an email
0065 program can therefore get good results with a smaller value than e.g. a special purpose
0066 application.
0068 _How can developments of a user be tracked without unique identification?_
0070 If you want to observe how usage patterns change as your users gain more experience
0071 with the application, there are multiple ways to do that:
0072 - Include a UsageTimeSource, and correlate the relevant usage data with how long
0073   the application has been used.
0074 - It is possible to track arbitrary historic development using custom data sources
0075   via AbstractDataSource::reset. This method is called after each successful submission,
0076   allowing you to implement a "memory" for your data source, and e.g. submit differential
0077   rather than absolute values.