Extension:QuickSurveys
This extension is maintained by the Web team. |
Release status: stable |
|
---|---|
Implementation | User interface |
Description | In-article quick surveys or external surveys. Polling readers for opinion. |
Author(s) | Jon Robson, Joaquin Hernandez, Rob Moen, Bahodir Mansurov, Sam Smith, Adam Wight |
Latest version | 1.4.0 |
MediaWiki | 1.26 |
License | MIT License |
Download | |
|
|
Quarterly downloads | 10 (Ranked 130th) |
Translate the QuickSurveys extension if it is available at translatewiki.net | |
Vagrant role | quicksurveys |
Issues | Open tasks · Report a bug |
The QuickSurveys extension displays in-article banners, through which users can be canvassed for their feedback.
Documentation and features
[edit]As of 2024, QuickSurveys can:
- Target random readers
- Target readers of a specific page
- Target based on whether you're logged-in/logged-out
- Target based on edit bucket
- Target based on user agent
- Target based on first and last edit date (>= 1.43)
- Ask multiple-choice questions
- Collect one or more responses to questions ("pick the best answer" vs. "check all that apply")
- Optionally collect write-in responses to questions (>= 1.43)
- Ask questions that only show up if a certain answer is given for a previous question (>= 1.43)
- Offer a link to another page (e.g., to provide information about a longer survey)
- Embed one or more surveys at a customizable location on a specific page
Known problems:
- Some ad-blocking and no-script software blocks this extension.
- Setting up a survey requires support from a developer.
- Reading survey results requires support from analytics or a developer.
- No standard mechanism to target users in an arbitrary workflow or condition, for example by testing a mw.storage key.
Prerequisites
[edit]Until version 1.38, QuickSurveys depends on EventLogging and won't work without it. In 1.39 the installation of EventLogging is optional. It is required for internal surveys and for tracking survey impressions.
Installation
[edit]- Download and move the extracted
QuickSurveys
folder to yourextensions/
directory.
Developers and code contributors should install the extension from Git instead, using:cd extensions/
git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/QuickSurveys - Add the following code at the bottom of your LocalSettings.php file:
wfLoadExtension( 'QuickSurveys' );
Done – Navigate to Special:Version on your wiki to verify that the extension is successfully installed.
Vagrant installation:
- If using Vagrant , install with
vagrant roles enable quicksurveys --provision
Configuration
[edit]< 1.43
[edit]Information for configuring older MediaWiki versions on an older revision of this page.
1.43
[edit]This is planned functionality that is currently not available in master. Our aim is to add this in 1.43. |
Here are configurations for the two major types of survey: an "internal survey" which displays a question and a set of possible answers in the article itself, and an "external survey" which links to another platform (e.g. Google Forms).
const QS_ANSWERS_MULTI_CHOICE = [
[
'label' => 'ext-quicksurveys-example-internal-survey-answer-positive',
// Label for the optional free form text answer
'freeformTextLabel' => 'ext-quicksurveys-example-internal-survey-freeform-text-label',
],
[
'label' => 'ext-quicksurveys-example-internal-survey-answer-neutral',
// Label for the optional free form text answer
'freeformTextLabel' => 'ext-quicksurveys-example-internal-survey-freeform-text-label',
],
[
'label' => 'ext-quicksurveys-example-internal-survey-answer-negative',
// Label for the optional free form text answer
'freeformTextLabel' => 'ext-quicksurveys-example-internal-survey-freeform-text-label',
],
];
// Applies to all surveys
const QS_DEFAULTS = [
// Who is the survey for? All fields are optional.
'audience' => [
'minEdits' => 0,
'anons' => false,
'maxEdits' => 500,
'userAgent' => [ 'KaiOS', 'Chrome' ],
'registrationStart' => '2018-01-01',
'registrationEnd' => '2080-01-31',
// You must have CentralNotice extension installed in order to limit audience by country
// 'countries' => [ 'US', 'UK' ]
],
// The i18n key of the privacy policy text
'privacyPolicy' => 'ext-quicksurveys-example-external-survey-privacy-policy',
// Whether the survey is enabled
'enabled' => true,
// Percentage of users that will see the survey
'coverage' => 1,
// For each platform (desktop, mobile), which version of it is targeted
'platforms' => [
'desktop' => [ 'stable' ],
'mobile' => [ 'stable' ]
],
];
$wgQuickSurveysConfig = [
// Example of an internal survey
[
// Survey name
'name' => 'internal example survey',
// Internal or external link survey?
'type' => 'internal',
// A list of all questions in this survey. Internal surveys can have multiple questions.
'questions' => [
[
// Required field used for referencing question in other questions.
'name' => 'question-1',
// Survey question message key
'question' => 'ext-quicksurveys-example-internal-survey-question',
// The respondent can choose one answer from a list.
'layout' => 'single-answer',
// The message key of the description of the survey. Displayed immediately below the survey question.
//'description' => 'ext-quicksurveys-example-internal-survey-description',
// Possible answer message keys for positive, neutral, and negative.
'answers' => QS_ANSWERS_MULTI_CHOICE,
// Whether to shuffle the display of the answers.
'shuffleAnswersDisplay' => true,
],
],
] + QS_DEFAULTS,
[
// Survey name
'name' => 'internal multi answer example survey',
// Internal or external link survey?
'type' => 'internal',
// A list of all questions in this survey. Internal surveys can have multiple questions.
'questions' => [
[
// Required field used for referencing question in other questions.
'name' => 'question-1',
// Survey question message key
'question' => 'ext-quicksurveys-example-internal-survey-question',
// The respondent can choose multiple answers from a list.
'layout' => 'multiple-answer',
// The message key of the description of the survey. Displayed immediately below the survey question.
//'description' => 'ext-quicksurveys-example-internal-survey-description',
// Possible answer message keys for positive, neutral, and negative.
'answers' => QS_ANSWERS_MULTI_CHOICE,
// Whether to shuffle the display of the answers.
'shuffleAnswersDisplay' => true,
],
],
] + QS_DEFAULTS,
// Example of an external survey
[
'name' => 'external example survey',
// Internal or external link survey
'type' => 'external',
// A list of all questions in this survey. Internal surveys can have multiple questions.
'questions' => [
[
// Required field used for referencing question in other questions.
'name' => 'question-1',
// Survey question message key
'question' => 'ext-quicksurveys-example-external-survey-question',
// The i18n key of the description of the survey
'description' => 'ext-quicksurveys-example-external-survey-description',
// External link to the survey
'link' => 'ext-quicksurveys-example-external-survey-link',
// Parameter to add to external link
'instanceTokenParameterName' => 'parameterName',
// Yes answer message key
'yesMsg' => 'ext-quicksurveys-example-external-survey-yes',
// No answer message key
'noMsg' => 'ext-quicksurveys-example-external-survey-no',
],
],
] + QS_DEFAULTS,
// Example of an internal survey with multiple questions
[
'name' => 'multi-question internal survey',
'type' => 'internal',
'confirmMsg' => 'ext-quicksurveys-survey-test-confirm-msg',
'confirmDescription' => 'ext-quicksurveys-survey-test-confirm-description',
'questions' => [
// Question 1 - Simple "yes", "no" and write-in "not sure"
[
// Unique name identifier
'name' => 'question-1',
'layout' => 'single-answer',
'question' => 'ext-quicksurveys-my-question-1',
// Possible answers to the above question
'answers' => [
// These below only have label message keys
[ 'label' => 'ext-quicksurveys-answer-yes' ],
[ 'label' => 'ext-quicksurveys-answer-no' ],
[
'label' => 'ext-quicksurveys-answer-not-sure',
// Label for the optional free form text answer
'freeformTextLabel' => 'ext-quicksurveys-answer-not-sure-placeholder'
]
]
],
// Question 2 - Depends on question 1 and the answer needs to be 'yes'
[
'name' => 'question-2',
// List of dependencies, in this case only depends on question 1 AND answer 'yes'
'dependsOn' => [
[
// Simple dependency question - use name identifier
'question' => 'question-1',
// Simple dependency answer list - if user answered ANY
// answer in this list, then the criteria is satisfied.
'answerIsOneOf' => [ 'ext-quicksurveys-answer-yes' ]
]
],
'layout' => 'multiple-answer',
'question' => 'ext-quicksurveys-my-question-2',
'shuffleAnswersDisplay' => true,
'answers' => [
// Answers with message keys and optional free text
[ 'label' => 'ext-quicksurveys-my-question-2-answer-1' ],
[ 'label' => 'ext-quicksurveys-my-question-2-answer-2' ],
[ 'label' => 'ext-quicksurveys-my-question-2-answer-3' ],
[ 'label' => 'ext-quicksurveys-my-question-2-answer-4' ],
[ 'label' => 'ext-quicksurveys-my-question-2-answer-5' ],
[ 'label' => 'ext-quicksurveys-my-question-2-answer-6' ],
[
'label' => 'ext-quicksurveys-my-question-2-answer-7',
// Label for the optional free form text answer
'freeformTextLabel' => 'ext-quicksurveys-my-question-2-answer-7-free-text-placeholder'
],
[ 'label' => 'ext-quicksurveys-answer-i-prefer-not-to-say' ]
],
],
]
] + QS_DEFAULTS,
];
Defining an audience
[edit]It is possible to define audiences for a survey based edit count, whether a respondent is logged in, user registration date, and their country (based on IP).
The audience field is optional and can be omitted if you want the survey to show to everyone (as defined in coverage). You can also only include some of the parameters. For example, including just minEdits
will target users who have at least that many edits with no maximum.
Note, the audience is not included in sampling, so for example if coverage is 0.5, 50% of all users will be bucketed for the survey, but only the users in that 50% that match the audience will actually see the survey.
All audience keys are additive.
We will accept several keys:
- minEdits: the minimum number of edits a user must have. Default: no minimum
- maxEdits: the maximum number of edits a user must have. Default: no maximum
- anons: is the survey targeted to anons (true) or logged-in (false) only? Default: both anonymous and logged-in users are included.
- registrationStart: if the survey is targeted by registration date, user had to join on or after this date. Date is in format YYYY-MM-DD. Default: no limit
- registrationEnd: if the survey is targeted by registration date, user had to join before or on this date. Date is in format YYYY-MM-DD. Default: no limit
- countries: a list of two letter country codes that are matched against window.Geo.country. Default: no country filter
- pageIds: a list of article IDs, the survey can only be displayed on matching pages. Default: no page filter
- firstEdit: a date range consisting of 'from' and 'to' keys that specify the range the user's first edit needs to be within. Default: no limit
- lastEdit: a date range consisting of 'from' and 'to' keys that specify the range the user's last edit needs to be within. Default: no limit
'audience' => [
'minEdits' => 2,
'maxEdits' => 5,
'registrationStart' => '2018-01-01',
'registrationEnd' => '2018-01-31',
'pageIds' => [ 1234, 9876 ],
'countries' => [ 'US', 'UK' ],
'firstEdit' => [ 'from' => '2018-01-01', 'to' => '2018-12-31' ],
'lastEdit' => [ 'from' => '2018-01-01', 'to' => '2018-12-31' ]
],
- platforms - This mandatory, top-level survey configuration field allows filtering against $wgMFMode. For "desktop", the only matching value is "stable". For "mobile", the possible modes are "stable" or "beta", which is enabled when the MobileFrontend anonymous-user beta feature option is checked.
Survey layout
[edit]The following configuration fields control how the survey will be displayed:
- type: external - The survey is hosted on an external website, all we show is a link.
External survey - layout: single-answer - Choices are each presented as a button. Clicking a choice will immediately submit and dismiss the survey, unless a freeform text input is enabled.
Single-answer survey - layout: multiple-answer - Choices are each presented as a checkbox. Multiple choices can be selected. A freeform text input will not be provided.
Multiple-answer survey - freeformTextLabel - The respondent is prompted to enter freeform text, in addition to an optional choice of answer.
Survey with freeform text input enabled - shuffleAnswersDisplay - The answers will be randomized and displayed in a different order for each respondent. This helps average out a response bias caused by the order of answers. Defaults to true.
- embedElementId - When this field is present, the survey can only be injected into a page with a DOM element matching the configured value by ID. For example, a survey with
embedElementId: "survey-embed-point"
will be displayed on a page with HTML<div id="survey-embed-point"></div>
, immediately after that element.Survey embedded at a specific location
Adding message keys
[edit]Messages can be defined as part of an extension e.g. WikimediaMessages or by wiki page. For example the message "ext-quicksurveys-example-internal-survey-answer-positive" can be defined by editing the wiki page MediaWiki:ext-quicksurveys-example-internal-survey-answer-positive
For editing messages ensure you have the right permissions. You will need edit-interface right.
How to load a specific survey
[edit]You can bypass the sampling and load a survey using one of the methods below. Please note that the survey you want to load needs to be enabled and passed to the front end. See the "Notes and Gotchas" section if you are having trouble seeing a survey.
- To load any of the available surveys append
?quicksurvey=true
to the URL; - To load a survey whose name is 'survey name' append
?quicksurvey=survey name
to the URL.
Additionally, QuickSurveys has a JavaScript API that you can use to load a survey, e.g. the following loads a survey whose name is 'survey name':
mw.loader.using( 'ext.quicksurveys.init' )
.then( () => {
mw.extQuickSurveys.showSurvey( 'survey name' );
} );
Note well that this will work on any page.
Developer guide
[edit]Rules for displaying a survey
[edit]Much of this logic seems to reside on the client.
To see what surveys are available you'll need to inspect the source code of JavaScript of the ext.quicksurveys.lib module. For example on the beta cluster: https://en.wikipedia.beta.wmflabs.org/w/load.php?modules=ext.quicksurveys.lib&debug=true (look for resources/ext.quicksurveys.lib/surveyData.json)
Results
[edit]The initial impressions and responses are recorded in EventLogging. Initial impressions are in the QuickSurveyInitiation schema and responses are in QuickSurveysResponses. The surveyCodeName
field in both schemas corresponds to the survey's configured name
.
Troubleshooting
[edit]For local development using Docker, to see quick surveys rendered on an article page, the page must exist locally when using Content Provider. Once the local page is created, appending the appropriate query parameters to the url will make the quick survey visible.
Surveys are not showing
[edit]You can see which surveys are available by looking at the source of the ext.quicksurveys.lib module e.g. https://en.wikipedia.beta.wmflabs.org/w/load.php?modules=ext.quicksurveys.lib&debug=true&only=scripts
Available surveys will be listed in resources/ext.quicksurveys.lib/surveyData.json. If your survey is not shown then there is likely a problem with your configuration change. Inspect carefully for typos.
Notes and Gotchas
[edit]window.Geo
is provided by CentralNotice. To avoid setting up an extension runJSON.stringify( window.Geo )
in production and addwindow.Geo = <data>;
to your code.
Note that a survey won't show up when:
- on the Main Page;
- on non-article page;
- on non-existent article page. Be careful when using the MobileFrontend content provider!;
- on skin Minerva when the beta opt in panel is shown;
- (Broken: if a survey is an external one and points to non-https location. TODO: Pending task T255291.)
Live example surveys
[edit]- Beta cluster - Internal example survey
- Beta cluster - Internal example survey with description and freeform text
- Beta cluster - Internal multiple answer example survey
- Beta cluster - Internal multiple answer example survey with description and freeform text
- Beta cluster - External example survey
Survey Deployment Notes
[edit]- Useful information about deploying surveys to beta and production.
- Adding new survey messages (such as new questions) to WikiMediaMessages is an involved process:
- Messages need to be added to and documented in
i18n/wikimedia/en.json
i18n/wikimedia/qqq.json
- Time should be allowed for and efforts coordinated for those messages to be localized in translatewiki as appropriate/necessary for the community of a given project
- These messages translations must be pushed from translatewiki back to WikiMediaMessages and deployed to a project before those messages are available for display in a survey
- Messages need to be added to
- QA of surveys is an involved process, requiring editing of the media-wiki config repository.
- Patchdemo can't be used for checking new surveys because surveys are configuration, and patchdemo is not configurable. Patchdemo may only be used for QA of ui/code changes, not surveys themselves.
- The beta cluster is the only persistent environment available to QA survey content.
- Surveys being tested on beta with a high coverage should be limited to pageids, such as user sandboxes.
- Because beta inherits configuration from production, you should check to see if the extension is enabled on production by checking for the beta wikiname in the array in
wmgUseQuickSurveys
If it is not, you will need to add it towmf-config/InitialiseSettings.php
wmf-config/InitialiseSettings-labs.php
- Surveys are deployed to production as backports, since they are configuration changes:
- Please see the deployment calendar for details on backport windows.
- During the backport window deployment, you will need to verify the change was deployed successfully using a mwdebug host.
- Audience/coverage settings can greatly impact the ability of a survey to display without forcing them. For example, based on the audience/coverage settings you may have to create an account on the test project and have the necessary edit count to trigger a survey.
- Be prepared to discuss your phabricator ticket about coverage and audience since the display of the survey has an impact on the user experience. Deployers may decline any patch if they don't understand the impact. Bring a friend to your first deployment.
This extension is being used on one or more Wikimedia projects. This probably means that the extension is stable and works well enough to be used by such high-traffic websites. Look for this extension's name in Wikimedia's CommonSettings.php and InitialiseSettings.php configuration files to see where it's installed. A full list of the extensions installed on a particular wiki can be seen on the wiki's Special:Version page. |