Studies

A study defines the goals and ordered interview segments used for participants. This page covers creating, linking, activating, and troubleshooting a study in UserTold.

The Study Design Guide is the canonical home for the script schema, mode patterns, field reference, and complete examples.

Create a study

Open Studies and choose Create Study. Start with one research question, add specific goals, and build the shortest segment sequence that can answer it.

Use the three participant-facing modes deliberately:

  • talk conducts a conversation and follows up on participant answers.
  • speak delivers a scripted instruction or transition.
  • observe silently captures product use for later interpretation and debrief.

For a task-based study, a dependable sequence is an instruction, silent observation, a planned debrief, and a closing message. Validate the script and run it yourself before inviting participants.

Link the study to an intake so qualified participants enter the intended interview. When linked:

  • qualification routes the participant to this study;
  • the widget loads this study's active script;
  • the interview retains its intake response context.

Activate both the study and intake before testing the participant flow. If either is paused, a qualified participant cannot begin the intended interview.

Configure the embed context

Study settings can restrict the origins allowed to run the interview. When allowed_origins is non-empty, include every origin where the widget is embedded.

Scripted host actions remain deterministic segment-boundary steps. Navigation should stay on the current host origin. Observation remains silent; host actions and origin settings do not turn it into live coaching.

For the exact settings and segment fields, use the Study Design Guide. For production advancement and recovery behavior, use Study Runtime.

Test before inviting participants

Complete one interview through the same intake and embed your participants will use. Confirm that:

  1. qualification opens the intended study;
  2. instructions fit the product task;
  3. observe segments advance through a deterministic completion rule or time limit;
  4. a planned talk segment debriefs the observed task;
  5. the interview completes and produces a reviewable source record.

Troubleshooting

SymptomNext action
Script validation failsUse the canonical field reference and validator linked from the Study Design Guide.
A qualified participant cannot startConfirm the intake is linked to this study and both are active.
An observe segment never advancesAdd an appropriate deterministic completion rule and a time limit.
The debrief is genericPut a planned talk segment after observation and connect it to the task and study goals.
Evidence is thinInspect the transcript and timeline, then sharpen the task, goals, or planned debrief.
The widget reports an origin problemAdd the embed origin to the study settings, or leave the allowlist empty while testing.

Continue