Module: userSurvey

A module to facilitate surveys of study participants. See the documentation for setSurvey for additional details about usage.

User Experience

  • If the user has not been previously prompted for the survey, the survey will open in a new tab.
  • The study's browser action popup will contain either a page prompting the user to complete the survey (with options to open the survey or decline the survey), or a neutral page (if the user has already completed or declined the survey).
  • If the user has been previously prompted for the survey, and has not completed or declined the survey, the user will be reminded to complete the survey with a browser notification at a set interval.

Limitations

Note that this module is currently very limited: it only supports one survey at a time per study, with few options and a constrained design. We have not yet decided whether to build out this module or implement survey functionality in the Rally core add-on.

Source:

Methods

(static) endSurvey() → {Promise}

End the current survey. If there is a current survey, you must call this function before starting a new survey.

Source:
Returns:

A Promise that resolves when the survey has been ended.

Type
Promise

(static) getSurveyId() → {Promise.<string>}

Each study participant has a persistent survey ID, generated with the id module. The ID is automatically added as a parameter to the survey URL, enabling researchers to import survey data from an external platform and sync it with Rally data. This method returns the survey ID, generating it if it does not already exist.

Source:
Returns:
  • The participant's survey ID.
Type
Promise.<string>

(static) getSurveyName() → {Promise.<string>|Promise.<null>}

Gets the name of the current survey.

Source:
Returns:
  • The name of the current survey. Returns null if there is no current survey.
Type
Promise.<string> | Promise.<null>

(static) getSurveyStatus() → {Promise.<string>|Promise.<null>}

Gets the status of the current survey. Can be used if a subsequent survey depends on the status of the previous survey.

Source:
Returns:
  • The status of the current survey ("completed", "cancelled", or "active"), or null if there is no current survey.
Type
Promise.<string> | Promise.<null>

(static) setSurvey(options)

Prompt the user to respond to a survey. There can only be one current survey at a time.

Survey Behavior
  • If there is no current survey (i.e., if setSurvey was not previously called or endSurvey was called after setSurvey), this function creates a new current survey with the provided options, persists current survey details in storage, and configures survey UX.
  • If there is a current survey and options.surveyName matches the name of the current survey, this function continues the current survey with the details persisted in storage and configures survey UX.
  • If there is already a current survey and options.surveyName does not match the name of the current survey, throws an Error as there can only be one current survey at a time.
Single-Survey Studies

If your study involves a single survey, call setSurvey when you first want to prompt the user to complete the survey, then call setSurvey with an identical survey name on subsequent extension startups to continue the survey.

Multi-Survey Studies

If there is more than one survey in your study, you must call endSurvey for the current survey before calling setSurvey for the next survey.

Parameters:
Name Type Description
options Object

The options for the survey.

Properties
Name Type Attributes Description
surveyName string

A unique name for the survey within the study.
popupNoPromptMessage string

A message to present to the user when there is no survey to prompt.
popupPromptMessage string

A message to present to the user when there is a survey to prompt.
popupIcon string <optional>

A path to an icon file, relative to the study extension's root, to use for for the browser action popup. This property is optional as the popup does not need to display an icon.
reminderIcon string <optional>

A path to an icon file, relative to the study extension's root, to use for for reminding the user with a notification to complete the survey. This property is optional as the notification does not need to display an icon.
reminderInterval number

How often, in seconds, to wait before reminding the user with a notification to participate in the survey.
reminderMessage string

The message to use for reminding the user with a notification to complete the survey.
reminderTitle string

The title to use for reminding the user with a notification to complete the survey.
surveyCompletionUrl string

A URL that, when loaded, indicates the user has completed the survey.
surveyUrl string

The URL for the survey on an external platform (e.g., SurveyMonkey, Typeform, Qualtrics, etc.).
Source: