Jump to content

Extensão:PesquisasRápidas

No rastreador: #QuickSurveys
From mediawiki.org
This page is a translated version of the page Extension:QuickSurveys and the translation is 1% complete.
Languages:
Manual de extensões do MediaWiki
QuickSurveys
Estado da versão: estável
Implementação Interface de usuário
Descrição In-article quick surveys or external surveys. Polling readers for opinion.
Autor(es) Jon Robson, Joaquin Hernandez, Rob Moen, Bahodir Mansurov, Sam Smith, Adam Wight
Última versão 1.4.0
MediaWiki 1.26
Licença Licença MIT
Download
Baixar extensão
Git [?]:
Parâmetros
  • $wgQuickSurveysConfig
Hooks usados
Para traduzir a extensão QuickSurveys, verifique sua disponibilidade no translatewiki.net
Função no Vagrant quicksurveys
Problemas Tarefas em aberto · Relatar um bug

The QuickSurveys extension displays in-article banners, through which users can be canvassed for their feedback.

Documentation and features

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

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

  • Baixe e mova a pasta extraída QuickSurveys ao seu diretório extensions/.
    Desenvolvedores e colaboradores de código, por outro lado, deverão instalar a extensão a partir do Git, usando:
    cd extensions/
git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/QuickSurveys
  • Adicione o seguinte código ao final do seu arquivo LocalSettings.php : 
    wfLoadExtension( 'QuickSurveys' );
  • Yes Concluído – Navegue à página Special:Version em sua wiki para verificar se a instalação da extensão foi bem sucedida.


Instalação com o Vagrant:

  • Se estiver usando o Vagrant , instale com vagrant roles enable quicksurveys --provision

Running surveys has a performance penalty

When running a survey, you will load Vue.js on page load which is a known performance penalty. For this reason when running a survey, please make sure it's lifespan is limited to exactly the amount of time it needs to run. Please ensure when you've enabled a survey that you have a task to disable the survey and that you don't forget to follow up.

Configuration

version < 1.43

Information for configuring older MediaWiki versions on an older revision of this page.

version 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',
		'mobile'
	],
];

$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

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:

  • userInGroup — which user groups the user must belong to. When multiple user groups are provided the user must belong to ALL of those groups. For example [ "sysop", "rollbacker"] requires the user to be a rollbacker AND a sysop. The wildcard star applies to all users. Default: [ "*" ]. This can also be used to target temporary users using ["temp"].
  • namespaces — the namespaces the survey can appear in. Please note that on certain pages surveys are not supported without the embedElementId option (see survey placement) Default: [ 0 ]
  • 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
  • userAgent — browsers that should see the quick survey.
'audience' => [
	'minEdits' => 2,
	'maxEdits' => 5,
	'registrationStart' => '2018-01-01',
	'registrationEnd' => '2018-01-31',
	'namespaces' => [ 0 ],
	'userInGroup' => [ 'sysop' ],
	'pageIds' => [ 1234, 9876 ],
	'countries' => [ 'US', 'UK' ],
	'firstEdit' => [ 'from' => '2018-01-01', 'to' => '2018-12-31' ],
	'lastEdit' => [ 'from' => '2018-01-01', 'to' => '2018-12-31' ],
	'userAgent' => [ 'Chrome', 'KaiOS' ],
	'anons' => false,
],
  • platforms — This mandatory, top-level survey configuration field allows filtering for mobile or desktop views. It is a flat array that can be empty or contain the strings 'mobile' and/or 'desktop'. Note, platform should not be confused with mobile devices it corresponds to the mobile experience. If you want to target mobile edits please use userAgent. Note, for projects which do not have a separate mobile site e.g. wikifunctions.org platform must always be desktop since the platform experience is the same regardless of device.

Configuring Questions

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.

Survey Placement

By default surveys are placed after the first lead paragraph, or before the first .mw-heading, infobox or .thumb element. If there is no lead paragraph, heading or infoboxes the survey will refuse to display without further configuration. This will happen on the majority of special pages, on Wikimedia projects that use custom markup that is visually different from Wikipedia and most custom namespaces. They are optimized for Wikipedias so on other projects may display inappropriately while T393436 is unresolved.

You can override the placement by providing an ID of where the survey should z

  • 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. You can use "embedElementId": "-" to ensure that the survey is not automatically appending to the page (see advanced surveys).
Survey embedded at a specific location

For running surveys on special pages the special page itself will need to provide a suitable area to run the survey. It is recommended that you add an element to the special page with the ID prefix mw-quicksurvey-container to keep this discoverable. Note the ID will need to be unique if you wish to exclude the survey from other special pages You can file a ticket against the appropriate special page using this Phabricator form.

Note, when using embedElementId or relying on the default survey placement, when running on non-Wikipedia you may also need to provide your own custom CSS to influence visual display.


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.

Running surveys outside Wikipedia

Following phab:T317841 QuickSurveys is enabled on all wikis. When using QuickSurveys outside Wikipedia it is important to bear in mind the guidance in the Survey Placement section.

Advanced surveys

If you have more advanced requirements that are not supported by the existing configuration you can enable a survey with embedElement set to "-". This ensures that the survey will not be automatically added to the page, as no HTML element will exist on the page with ID "-".

$wgQuickSurveysConfig = [
	[
		"name" => "Empty search experiment survey",
		"type" => "external",
		'enabled' => true,
		// Can be added programatically.
		'embedElementId' => '-',
		'coverage' => 0.5,
		'namespaces' => [ 0, -1 ],
		"privacyPolicy" => "ext-quicksurveys-empty-search-experiment-privacy-policy",
		'platforms' => [
			'desktop',
			'mobile'
		],
		'audience' => [
			"namespaces" => [ 0, -1 ],
		],
		"questions" => [
			[
				"name" => "Empty search experiment question",
				"layout" => "single-answer",
				"link" => 'ext-quicksurveys-empty-search-experiment-link',
				"question" => "ext-quicksurveys-empty-search-experiment-question",
				"description" => null,
				"yesMsg" => "ext-quicksurveys-empty-search-experiment-yes",
				"noMsg" => "ext-quicksurveys-empty-search-experiment-no",
			],
		],
	],
];

require( 'ext.quicksurveys.lib' ).showSurvey

The showSurvey method takes three parameters:

  • <string> name - name of survey
  • <string> id - id of element to insert survey
  • <bool> force - whether to override the survey's audience and sampling. This should be used for debugging purposes only. Ensure your surveys have defined an appropriate sample rate and define audience as an empty array if you want to override the audience requirements locally.

The method will return a boolean based on whether the survey was added to the page or not. The result will be false under the following circumstances:

  • the survey does not exist
  • the user is not in the current sample (if force parameter was not used)
  • the user does not meet the audience criteria (if force parameter was not used)

Displaying a survey with advanced targeting requirements

With the survey defined, code can be written in gadgets, WikimediaEvents or WikimediaMessages to add additional conditions and to insert the survey into the page.

const isUsingDarkMode = mw.user.options.get('vector-theme') === 'night';
const itsMorning = (new Date()).getHours() < 12;
// Show survey to users using dark mode during the morning period.
const shouldShowSurvey = isUsingDarkMode && itsMorning;

if ( mw.loader.getState( 'ext.quicksurveys.init' ) !== 'registered' ) {
    mw.loader.using('ext.quicksurveys.lib').then( ( require ) => {
        if ( shouldShowSurvey ) {
            // Will show survey if the user is in sample in the element with ID 'foo'
            require( 'ext.quicksurveys.lib' ).showSurvey( 'name', 'foo' );
        }
    })
}

Providing custom CSS on watchlist

After identifying a suitable HTML element on the page with an associated ID, when adding a survey you may also need to provide styling to control where the survey appears on the page using custom styling provided by the mw.util.addCSS function.

mw.loader.using(['ext.quicksurveys.lib', 'mediawiki.util']).then((require)=> {
    mw.util.addCSS(`.ext-quick-survey-panel { margin: 20px 0 20px 50px; }`)
    require('ext.quicksurveys.lib').showSurvey('Empty search experiment survey', 'mw-watchlist-form')

} )

Combining surveys

You can define multiple surveys and chain them together provided they have identical sampling rates. This can be useful if you want to ask follow up questions.

if ( mw.loader.getState( 'ext.quicksurveys.init' ) !== 'registered' ) {
    mw.loader.using('ext.quicksurveys.lib').then( ( require ) => {
        const showSurvey = require( 'ext.quicksurveys.lib' ).showSurvey;
        mw.hook( 'ext.quicksurveys.dismiss' ).add( () => {
           // when survey is dismissed  show the next question.
            showSurvey( 'name-2', 'foo' );
        });
        // Will show survey if the user is in sample in the element with ID 'foo'
        showSurvey( 'name-1', 'foo' );
    })
}

If you want to see a patchdemo of this in action you can use this example code: https://gerrit.wikimedia.org/r/c/mediawiki/extensions/WikimediaMessages/+/1202339

Running A/B tests

It might be desirable to show one survey 50% of the time, and another survey the other 50% of the time. You can combine the API with XLab to achieve this by creating two surveys which disable survey placement (by using embedElementId = '-') and programmatically displaying them based on the assigned group.

 const exp = mw.xLab.getExperiment( EXPERIMENT_NAME );
 if ( exp ) {
    if ( exp.isAssignedGroup( 'treatment' ) ) {
        require( 'ext.quicksurveys.lib' ).showSurvey( 'survey-treatment', 'body-content' );
    } else {
        require( 'ext.quicksurveys.lib' ).showSurvey( 'survey-nontreatment', 'body-content' );
    }
}

Developer guide

Rules for displaying a survey

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

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

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

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

  • 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.

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 !;
  • if a survey is an external one and points to non-https location (broken). TODO: Pending T255291.

Live example surveys

Survey Deployment Notes

  • 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 
      i18n/wikimedia/en.json
      and documented in 
      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
  • 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 
      wmgUseQuickSurveys
      array in 
      wmf-config/InitialiseSettings.php
      .       If it is not, you will need to add it to 
      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.


Retrieved from "https://www.mediawiki.org/w/index.php?title=Extension:QuickSurveys/pt-br&oldid=8003415"