Extension:QuickSurveys

The QuickSurveys extension allows for showing in-article banners, in order to ask users so that we can gather opinions and feedback on different matters.

Documentation

 * Rationale
 * Deploying surveys
 * Documentation on metawiki

Prerequisites
QuickSurveys depends on EventLogging and won't work without it.

Configuration
Here is a configuration for two kinds of surveys: internal and external. The external surveys are required to point to an `https://` URL.

Defining an audience
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 should have
 * maxEdits: the maximum number of edits a user should have
 * anons: is the survey targeted to anons (true) or logged-in (false) only? If undefined, both groups will potentially be 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
 * 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
 * countries: a list of two letter country codes that are matched against window.Geo.country

Adding message keys
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
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 a random survey append  to the URL;
 * To load an internal survey whose name is 'internal example survey' append  to the URL;
 * To load an external survey whose name is 'external example survey' append  to the URL.

Note: The  parameter is not the literal survey name. It's the type and survey name. The leading  or   is stripped when looking up the survey name in the configuration. E.g.,  picks the survey named   not.

Getting installed
Vagrant has a role! If not using Vagrant it's also easy: Take a look at LocalSettings.php to see how a survey is defined. Don't worry too much about it.

Displaying a survey
Next thing is you'll want to see a random survey:

http://localhost:8888/w/index.php/Spain?quicksurvey=true

(Refresh a few times)

There are 2 types of surveys - internal survey (has buttons) or an external survey (has a link).

You can force an example of each using the following URLs:


 * http://localhost:8888/w/index.php/Spain?quicksurvey=internal-survey-internal%20example%20survey
 * http://localhost:8888/w/index.php/Spain?quicksurvey=external-survey-external example survey

Rules for displaying a survey
Much of this logic seems to reside on the client.

mw.config.get( 'wgEnabledQuickSurveys' )

tells you what surveys are available.

QA
I've setup reading web staging with QuickSurveys so we have a shared environment for testing.


 * https://reading-web-staging.wmflabs.org/wiki/Pharmacovigilance?quicksurvey=external-survey-internal%20example%20survey
 * https://reading-web-staging.wmflabs.org/wiki/Pharmacovigilance?quicksurvey=internal-survey-internal%20example%20survey

Notes and Gotchas

 * is provided by CentralNotice. To avoid setting up an extension run  in production and add   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!;
 * when the browser's "Do Not Track" feature is turned on;
 * on skin Minerva when the beta opt in panel is shown;
 * if a survey is an external one and points to non-https location when the config variable `wgQuickSurveysRequireHttps` is set to `true`.