kuserfeedback/docs/user-feedback-surveys.qdoc

0001 /*
0002     SPDX-FileCopyrightText: 2017 Volker Krause <vkrause@kde.org>
0003
0004     SPDX-License-Identifier: MIT
0005 */
0006
0007 /*!
0008     \page user-feedback-surveys.html
0009     \previouspage Telemetry
0010     \nextpage UserFeedback Manual
0011     \title Surveys
0012
0013     \section1 Overview
0014
0015     Surveys have the following properties:
0016     \list
0017         \li A name. This is purely used for making survey management easier, it's not shown
0018         to the user.
0019         \li A URL. This link is opened if a user chooses to participate in a survey.
0020         \li An active flag. Only active surveys are presented to users.
0021         \li A targeting expression. Only surveys where this expression evaluates to \c true
0022         for a specific user are presented. The targeting expression is optional, if it is
0023         not set, \c true is implied, ie. the survey is considered for all users.
0024         \li An internal globally unique id. This is used to ensure a user is not asked to take
0025         the same survey twice. Therefore you should not delete and recreate surveys unless
0026         you want to reset the unique id.
0027     \endlist
0028
0029     \section1 Targeting Expressions
0030
0031     Survey targeting expressions are boolean expressions with a C++-like syntax.
0032
0033     \section2 Data Types
0034
0035     Values and literals of the following types are supported:
0036
0037     \list
0038         \li Integers.
0039         \li Floats.
0040         \li Boolean. Literals are specified using the keywords \c true and \c false.
0041         \li Strings. Literals need to be put in double quotes, special characters in literals
0042         need to be escaped with backslashes as in C++.
0043     \endlist
0044
0045     \section2 Values
0046
0047     The value of a scalar data source is accessed my using the source name and the element name
0048     separated by a dot, as follows:
0049
0050     \code
0051     platform.os
0052     \endcode
0053
0054     Accessing the value of a list or map data source is done by adding the corresponding array
0055     index or map key in brackets:
0056
0057     \code
0058     screens[0].width
0059     \endcode
0060
0061     Additionally, the amount of entries in a list or map data source is available via \c .size:
0062
0063     \code
0064     screens.size
0065     \endcode
0066
0067     \section2 Comparisons
0068
0069     The following comparison operators are supported, comparisons can be done in any combination
0070     between values and literals.
0071
0072     \table
0073     \header
0074         \li Operator
0075         \li Semantic
0076     \row
0077         \li ==
0078         \li Equality
0079     \row
0080         \li !=
0081         \li Inequality
0082     \row
0083         \li >
0084         \li Greater than (not supported for boolean values)
0085     \row
0086         \li >=
0087         \li Greator or equal (not supported for boolean values)
0088     \row
0089         \li <
0090         \li Less than (not supported for boolean values)
0091     \row
0092         \li <=
0093         \li Less or equal (not supported for boolean values)
0094     \endtable
0095
0096     \section2 Boolean Expressions
0097
0098     Comparisons can be combined by logical AND (\c &&) and OR (\c ||) operators. Further, expression
0099     evaluation order can be controlled by parenthesis.
0100
0101     The following examples targets users with multi-screen setups on windows:
0102     \code
0103     screens.size >= 2 && platform.os == "windows"
0104     \endcode
0105 */