Understanding Task Structure

This guide explains how behavioral tasks are structured and displayed during participant sessions. Understanding this structure helps you configure tasks effectively and write clear instructions for participants.

Overview

Every task follows a consistent structure with four types of instructions and optional practice trials. This standardized approach ensures participants have a clear, predictable experience across different task types.

Fullscreen Mode

Most tasks run in fullscreen to keep the participant focused and to prevent distractions from other browser windows or desktop elements. The participant's browser enters fullscreen when the task session begins, and exits fullscreen at the end of the session.

The ecological task is the only task that intentionally runs in a normal browser window rather than fullscreen. This is because the ecological task asks participants to interact with external applications or websites, which requires access to the regular browser interface. All other tasks use fullscreen.

Instruction Types

Tasks support four distinct instruction types, each displayed at a specific point during the task:

1. Main Instructions

What they are: The primary instructions for the task, explaining what participants will do.

When displayed: As a dedicated page before the task begins. This page includes:

• Camera preview (if recording is enabled)
• Screen share preview (if screen sharing is enabled)
• A "Start" button to begin the task

Configuration: In the study form, use the "Pre-task instructions" field (rich text editor).

Best practices:

• Explain the goal of the task
• Describe what participants will see
• Explain how to respond
• Keep instructions concise but complete

Example:

You will see color words displayed in different ink colors. Your task is to say the color of the ink, not the word itself.

For example, if you see the word "RED" written in blue ink, you should say "blue".

2. Practice Instructions

What they are: Instructions specific to the practice phase, preparing participants for practice trials.

When displayed: After main instructions, before practice trials begin. Displayed within the task area (not a dedicated page).

Configuration: In the study form, use the "Practice instructions" field.

When to use:

• When practice trials are enabled
• To explain that this is a practice round
• To describe the feedback that will be shown

Example:

Let's practice! You'll see a few example trials to help you get familiar with the task.

After each response, you'll see whether you were correct (✓) or incorrect (✗).

3. Trials Instructions

What they are: Instructions shown before the main (scored) trials begin.

When displayed: After practice trials complete, before main trials start. Displayed within the task area.

Configuration: In the study form, use the "Trials instructions" field.

Drawing and Copy-of-Cube tasks

The Drawing and Copy-of-Cube tasks are single-canvas tasks with no practice/main-trials split. For these two tasks, the trials instructions do not appear as a separate screen. They render instead as a persistent caption shown above the canvas throughout drawing.

When to use:

• When transitioning from practice to scored trials
• To remind participants that feedback will no longer be shown
• To indicate that responses now count

Example:

Practice complete! Now you'll begin the actual task.

Respond as quickly and accurately as you can. You won't see feedback after each trial.

4. Hint Instructions

What they are: Quick-reference help text available during the task.

When displayed: As a tooltip when hovering over the ? button in the top-right corner of the task area. Available throughout the task.

Configuration: In the study form, use the "During-task hint" field.

Best practices:

• Keep it brief (1-3 sentences)
• Summarize the key response rules
• Remind which buttons/keys to use

Example:

Say the color of the ink, not the word.

Task Flow Diagram

Here's how a typical task with practice trials flows:

┌───────────────────────────────────────────────────┐
│  MAIN INSTRUCTIONS PAGE                           │
│  ┌─────────────────────────────────────────────┐  │
│  │ Camera Preview  │  Screen Share Preview     │  │
│  └─────────────────────────────────────────────┘  │
│                                                   │
│  [Your main instructions here]                    │
│                                                   │
│               [ Start ]                           │
└───────────────────────────────────────────────────┘
                      │
                      ▼
┌───────────────────────────────────────────────────┐
│  PRACTICE INSTRUCTIONS                            │
│  (if practice is enabled)                         │
│                                                   │
│  [Your practice instructions here]                │
│                                                   │
│               [ Start Practice ]                  │
└───────────────────────────────────────────────────┘
                      │
                      ▼
┌───────────────────────────────────────────────────┐
│  PRACTICE TRIALS                          [?]     │
│                                                   │
│  • Stimulus displayed                             │
│  • Participant responds                           │
│  • Feedback shown (✓ or ✗)                        │
│  • Repeat for each practice trial                 │
└───────────────────────────────────────────────────┘
                      │
                      ▼
┌───────────────────────────────────────────────────┐
│  TRIALS INSTRUCTIONS                              │
│  (shown after practice completes)                 │
│                                                   │
│  [Your trials instructions here]                  │
│                                                   │
│               [ Start ]                           │
└───────────────────────────────────────────────────┘
                      │
                      ▼
┌───────────────────────────────────────────────────┐
│  MAIN TRIALS                              [?]     │
│                                                   │
│  • Stimulus displayed                             │
│  • Participant responds                           │
│  • No feedback shown                              │
│  • Repeat for each trial                          │
│                                                   │
└───────────────────────────────────────────────────┘
                      │
                      ▼
              Task Complete

Practice Trials

Practice trials help participants learn the task before their responses are scored.

Enabling Practice

Practice is controlled per task by a single "Enable practice trials" checkbox. When enabled (the default for most tasks), the practice phase runs before the main trials; when disabled, the task starts directly with the main trials. Each task stores this as its own <task>_practice_enabled parameter (for example stroop_practice_enabled).

When practice is enabled but no practice trials are configured, the task proceeds straight to the main trials.

Practice Features

• Immediate feedback: After each practice response, participants see whether they were correct (green checkmark) or incorrect (red X). Some tasks expose a per-task setting to turn this practice feedback off.
• Practice trials run in full: There is no in-task "skip practice" control. Practice runs through all of its configured trials, then the task moves on to the trials instructions and main trials.

Configuring Practice Trials

In the study form task configuration:

1. Enable practice: Check "Enable practice trials"
2. Practice trials: Configure the practice trial list (similar to main trials)
3. Practice instructions: Write instructions specific to the practice phase

Button Behavior

Standard Buttons

All tasks use consistent button styling:

Button	Purpose	When Visible
Start	Begin task or phase	Before task starts, before practice, before main trials
Next	Advance to next item	During self-paced tasks
Submit	Submit a response	For tasks requiring explicit submission
? (Hint)	Show hint instructions	Always visible during task

Moderation Modes

Button visibility depends on the moderation mode:

Button	Unmoderated	Moderated	Strictly Moderated
Start	✓ Visible	✓ Visible	Hidden (moderator controls)
Next	✓ Visible	✓ Visible	Hidden (moderator controls)
Submit	✓ Visible	✓ Visible	Hidden (moderator controls)
Hint (?)	✓ Visible	✓ Visible	✓ Visible

In strictly moderated mode, the moderator controls task progression through the moderation dashboard.

Customizing Button Text

You can customize button labels in the study's UI translation settings:

• Start: Used for all "Start" buttons
• Next: Used for all "Next" buttons
• Submit: Used for all "Submit" buttons
• Skip: Used for "Skip" buttons (e.g. skipping forward in the trail-making task)
• Show help: Aria label for the hint button (for accessibility)

The Hint Button

The hint button (?) appears in the top-right corner during task execution:

• Hover: Shows hint instructions as a tooltip
• Click: On touch devices, toggles the tooltip
• Content: Displays what you entered in "During-task hint"

Design tip: Keep hint content brief. It's meant as a quick reminder, not full instructions.

Tasks Without Practice

For tasks without practice trials, the flow simplifies to:

Main Instructions → Main Trials → Task Complete

The practice instructions and trials instructions fields are not used when practice is disabled.

Best Practices

Writing Effective Instructions

1. Main instructions: Be complete but concise. Explain the goal, stimuli, and response method.

2. Practice instructions: Keep brief. Mention this is practice and describe feedback.

3. Trials instructions: Short transition message. Note that feedback stops.

4. Hint instructions: One or two sentences maximum. Core response rules only.

Testing Your Instructions

Use the Preview feature in the study form to:

• Read through all instruction screens
• Check timing and flow
• Verify hint content appears correctly
• Test practice trial behavior

Common Mistakes

• Too much detail in hints: Hints should be quick reminders, not full instructions
• Missing transition instructions: If using practice, include trials instructions
• Inconsistent terminology: Use the same words across all instruction types
• No practice when needed: Complex tasks benefit from practice trials

Technical Notes

Instruction Parameters

All tasks use these standardized parameter names:

Instruction Type	Parameter Name	Description
Main	main_instructions	Pre-task instructions on dedicated page
Practice	practice_instructions	Instructions before practice trials
Trials	trials_instructions	Instructions before main/scored trials
Hint	hint_instructions	Quick-reference help via "?" button

Practice Configuration

Practice parameters are namespaced per task. The enable flag and the practice trial list carry the task's own prefix (shown below with <task>, for example stroop_practice_enabled), while the instruction fields use the shared standardized names.

Parameter	Type	Default	Description
<task>_practice_enabled	boolean	true	Whether the practice phase runs
<task>_practice_trials	array	[]	List of practice trial definitions
practice_instructions	string (HTML)	''	Instructions before practice

There is no practice_mode enum: practice is a single on/off flag per task, defaulting to on for most tasks. Practice feedback is shown by default; a few tasks expose a per-task <task>_show_feedback flag to disable it. The feedback display duration is a fixed per-task constant, not a configurable parameter.