Extension:QuickSurveys

This extension is maintained by the Reading Web team.

**MediaWiki extensions manual**
QuickSurveys Release status: stable
Description	In article quick surveys or external surveys. Polling readers for opinion.
Author(s)	Jon Robson, Joaquin Hernandez, Rob Moen, Bahodir Mansurov, Sam Smith
Latest version	1.3.0
MediaWiki	1.26+
License	GNU General Public License 2.0 or later
Download	Download extension Git ^[?]: Download Git master browse repository (GitHub) commit history code review
Translate the QuickSurveys extension if it is available at translatewiki.net
Check usage and version matrix.

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.

DocumentationEdit

PrerequisitesEdit

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

InstallationEdit

Download and place the file(s) in a directory called QuickSurveys in your extensions/ folder.

Add the following code at the bottom of your LocalSettings.php:
```
wfLoadExtension( 'QuickSurveys' );
```
Run the update script which will automatically create the necessary database tables that this extension needs.
Done – Navigate to Special:Version on your wiki to verify that the extension is successfully installed.

To users running MediaWiki 1.24 or earlier:

The instructions above describe the new way of installing this extension using wfLoadExtension(). If you need to install this extension on these earlier versions (MediaWiki 1.24 and earlier), instead of wfLoadExtension( 'QuickSurveys' );, you need to use:

require_once "$IP/extensions/QuickSurveys/QuickSurveys.php";

ConfigurationEdit

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

{
	"@QuickSurveysRequireHttps": "Whether to require links to external surveys to be secure",
	"QuickSurveysRequireHttps": true,
	"QuickSurveysConfig": [
		{
		"@name": "survey name",
		"name": "internal example survey",
		"@type": "internal or external link survey",
		"type": "internal",
		"@question": "survey question message key",
		"question": "ext-quicksurveys-example-internal-survey-question",
		"@description": "The message key of the description of the survey. Displayed immediately below the survey question.",
		"description": "ext-quicksurveys-example-internal-survey-description",
		"@answers": "possible answer message keys for positive, neutral, and negative",
		"answers": [
			"ext-quicksurveys-example-internal-survey-answer-positive",
			"ext-quicksurveys-example-internal-survey-answer-neutral",
			"ext-quicksurveys-example-internal-survey-answer-negative"
		],
		"@freeformTextLabel": "label for the optional free form text",
		"freeformTextLabel": "ext-quicksurveys-example-internal-survey-freeform-text-label",
		"@audience": "who is the survey for? All fields are optional.",
		"audience": {
		    "minEdits": 2,
		    "maxEdits": 5,
		    "registrationStart": "2018-01-01",
		    "registrationEnd": "2018-01-31",
		    "countries": ["US", "UK"]
		},
		"@enabled": "whether the survey is enabled",
		"enabled": true,
		"@coverage": "percentage of users that will see the survey",
		"coverage": 0.5,
		"@platforms": "for each platform (desktop, mobile), which version of it is targeted (stable, beta)",
		"platforms": {
			"desktop": ["stable"],
			"mobile": ["stable", "beta"]
		}
		},
		{
		"name": "external example survey",
		"@type": "internal or external link survey",
		"type": "external",
		"@question": "survey question message key",
		"question": "ext-quicksurveys-example-external-survey-question",
		"@description": "the i18n key of the description of the survey",
		"description": "ext-quicksurveys-example-external-survey-description",
		"@link": "external link to the survey",
		"link": "ext-quicksurveys-example-external-survey-link",
		"@instanceTokenParameterName": "parameter to add to link",
		"instanceTokenParameterName": "parameterName",
		"@privacyPolicy": "The i18n key of the privacy policy text.",
		"privacyPolicy": "ext-quicksurveys-example-external-survey-privacy-policy",
		"@enabled": "whether the survey is enabled",
		"enabled": true,
		"@coverage": "percentage of users that will see the survey",
		"coverage": 0.5,
		"@platforms": "for each platform (desktop, mobile), which version of it is targeted (stable, beta)",
		"platforms": {
			"desktop": ["stable"],
			"mobile": ["stable", "beta"]
		}
		}
	]
}

Defining an audienceEdit

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

		'audience': {
		    'minEdits': 2,
		    'maxEdits': 5,
		    'registrationStart': '2018-01-01',
		    'registrationEnd': '2018-01-31',
		    'countries': [ 'US', 'UK' ]
		},

Adding message keysEdit

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 surveyEdit

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.

To load a random survey append ?quicksurvey=true to the URL;
To load an internal survey whose name is 'internal example survey' append ?quicksurvey=internal-survey-internal example survey to the URL;
To load an external survey whose name is 'external example survey' append ?quicksurvey=external-survey-external example survey to the URL.

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

Developer guideEdit

Getting installedEdit

Vagrant has a role! If not using Vagrant it's also easy:

wfLoadExtension( 'QuickSurveys' );

// Load LocalSettings.php so the browser tests work and you have some quick surveys defined!

include_once "$IP/extensions/QuickSurveys/tests/browser/LocalSettings.php";

Take a look at LocalSettings.php to see how a survey is defined. Don't worry too much about it.

Displaying a surveyEdit

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 surveyEdit

Much of this logic seems to reside on the client.

mw.config.get( 'wgEnabledQuickSurveys' )

tells you what surveys are available.

QAEdit

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

Gotchas:

The page must EXIST to have the survey code loaded - so be careful when using the MobileFrontend content provider.
window.Geo is provided by CentralNotice. To avoid setting up an extension run JSON.stringify( window.Geo ) in production and add window.Geo = <data>; to your code.

NotesEdit

Note that a survey won't show up:

on the Main Page;
on non-article page;
on non-existent article page;
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`.

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.