Documentation

Per-question timers

Every survey question on the MX8 Labs Research Platform accepts a number_seconds keyword argument. When set, the Next button is disabled for the first number_seconds seconds the question is on screen, forcing the respondent to spend at least that long before they can move on.

This is most useful when you need to guarantee a minimum exposure time for a piece of content — an ad, a long instruction, or a stimulus you want the respondent to read carefully — or when you want to reduce speeders on a high-effort question.

Basic usage

number_seconds is an int and defaults to 0 (no delay).

from survey import Survey

s = Survey(**globals())

s.show_message(
    "Please read the following advertisement carefully.",
    number_seconds=10,
)

s.rating_question(
    "How likely are you to consider this brand?",
    number_of_points=5,
    number_seconds=3,
)

In this example the respondent must spend at least ten seconds on the message and three seconds on the rating question before they can advance.

Where it works

number_seconds is available on every survey instrument that has a respondent-facing page, including:

  • show_message, show_image, play_video, show_embedded_media
  • text_question, text_highlighter_question, numeric_question, get_location
  • select_question, multi_select_question
  • grid_select_question, grid_multi_select_question, grid_rating_question, grid_numeric_question
  • rating_question, net_promoter_score_question, ranking_question
  • this_or_that_question, this_or_that_rating_question
  • conjoint_question, max_diff_question, kid_picker_question
  • terminate, terminate_if, complete

show_image is the exception to the default — it defaults to number_seconds=5 to give the respondent time to look at the image. Pass a different value to override.

Choosing a value

A few rules of thumb:

  • For ad or video exposure that you intend to measure, match the length of the stimulus. If a 15-second ad plays via play_video, set number_seconds=15 on the video step.
  • For comprehension or instructions, set a value that matches the reading time, typically 5 to 15 seconds. Longer than that and respondents start to disengage.
  • For reducing speeders, even a small delay of 2 to 3 seconds on the harder questions in your survey will catch respondents who are tabbing through without reading. Pair this with s.time_between(...) (see Creating Calculated Variables) to flag respondents whose overall pacing is suspicious.

What the respondent sees

The question renders normally; the Next button (or the option buttons in chat mode) is disabled until the timer expires. The respondent does not see a visible countdown — the timer is intentionally unobtrusive — so set generous values only when you actually need the dwell time.