Documentation

Per-question timers

Nearly 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 most survey instruments that have a respondent-facing page, including:

  • show_message, get_consent, show_image, play_video
  • text_question, text_highlighter_question, numeric_question, location_question
  • 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, authenticate_by_phone_number
  • 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.

A few instruments work differently. show_embedded_media takes a required duration parameter — the number of seconds the respondent must wait before continuing — instead of number_seconds. Multi-question helpers such as standard_screener, get_all_children_age_gender, and kid_picker_question do not accept a timer.

Choosing a value

A few rules of thumb:

  • For ad exposure that you intend to measure, match the length of the stimulus. If a static ad is shown with show_image, set number_seconds to the dwell time you need. For play_video, the video playback itself controls the exposure — its number_seconds adds a wait after the video finishes before the respondent can continue.
  • 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 the Survey Programming Cookbook) 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.