Skip to content

Completion Trial Template

Completion trials mark participants as completed for the entire experiment at its onset and therefore must be used at the end of an experiment. It displays a trial screen with optional stimulus content and a continue button (which can redirect to an external URL), but cannot collect responses.

The most common use case for a completion trial template is to display a "completion code" that participants need to enter on an external recruitment platform or to redirect them back to such a platform. When participants reach this trial, they can safely leave FindingFive even if they do not reach FindingFive's official "completed" page. This reduces cross-platform participation status mismatches and produces cleaner completion data.

Restrictions

  • No responses: The responses property cannot be used.
  • No follow-up responses: The follow_up_responses property cannot be used.
  • One trial per template: Only one stimulus set can be defined, generating at most one trial per template.
  • One template per participant: Each participant sees exactly one completion trial — you may define multiple templates for different participation groups or branches, but only one will be seen per participant.

Properties

type

  • Definition: The type of trial template
  • Possible values: For completion trial templates, must be specified as "completion"

1
2
3
4
"CompletionTrial": {
  "type": "completion",
  "stimuli": ["CompletionCodeStimulus"]
}
In this example, a final completion trial is displayed with a stimulus that presumably shows a completion code. The default continue button will be displayed, but participants will be marked as "completed" at the start of this trial.

stimuli

  • Definition: Optional stimuli to display on the completion screen. If specified, only one stimulus set can be defined (completion trials generate at most one trial).
  • Possible values: A single stimulus name or a single stimulus set (multiple stimuli to display on the same trial)
  • Default (by omission): no stimulus displayed

1
2
3
4
"CompletionTrial": {
  "type": "completion",
  "stimuli": [["ThankYouStimulus", "CompletionCodeStimulus"]]
}
In this example, we show the participants both a thank you message and the completion code on the same trial. Participants are marked completed at the onset of this trial, with a continue button displayed (but not required to click for their status to be marked as "completed").

continue_button

  • Definition: Controls the continue button. Completion trials additionally support a url property for redirecting participants.
  • Possible values: see the display, onset, text, and url sub-properties below.

"display"

  • Definition: Whether to always display the continue button or to allow FindingFive to automatically determine if it is displayed.
  • Possible values: "auto" or "always"
  • Default: "auto"

1
2
3
4
5
6
"CompletionTrial": {
  "type": "completion",
  "stimuli": [["ThankYouStimulus", "CompletionCodeStimulus"]],
  // since this is the default behavior, there's no need to manually specify it (listed here only for documentation purposes)
  "continue_button": {"display": "auto", "onset": "auto"}
}
In this example, FindingFive will automatically determine whether or not to display a continue button, and when to display it.

1
2
3
4
5
"CompletionTrial": {
  "type": "completion",
  "stimuli": [["ThankYouStimulus", "CompletionCodeStimulus"]],
  "continue_button": {"display": "always", "onset": "auto"}
}
In this example, FindingFive will always display a continue button, but will automatically decide when to display it.

"onset"

  • Definition: Whether to display the continue button from the beginning of the trial or to allow FindingFive to automatically determine when it is displayed.
  • Possible values: "auto" or "immediate"
  • Default: "auto"

1
2
3
4
5
6
"CompletionTrial": {
  "type": "completion",
  "stimuli": [["ThankYouStimulus", "CompletionCodeStimulus"]],
  // since this is the default behavior, there's no need to manually specify it (listed here only for documentation purposes)
  "continue_button": {"display": "auto", "onset": "auto"}
}
In this example, FindingFive will automatically determine whether a continue button should be displayed, and when to display it.

1
2
3
4
5
"CompletionTrial": {
  "type": "completion",
  "stimuli": [["ThankYouStimulus", "CompletionCodeStimulus"]],
  "continue_button": {"display": "auto", "onset": "immediate"}
}
In this example, FindingFive will decide whether to display a continue button, and if so, it will be visible from the onset of the trial.

"text"

  • Definition: Custom text to display on the continue button. If not specified, the button displays default text.
  • Possible values: A string of 50 characters or less
  • Default (by omission): "Continue" (may be translated to other languages depending on the user's browser setting)

1
2
3
4
5
"CompletionTrial": {
  "type": "completion",
  "stimuli": [["ThankYouStimulus", "CompletionCodeStimulus"]],
  "continue_button": {"text": "Click to continue"}
}
In this example, the continue button will display "Click to continue" instead of the default text.

"url"

  • Definition: A URL to redirect participants to when they click the continue button. Only available on completion trials.
  • Possible values: A URL string starting with https://
  • Default (by omission): The continue button advances to the final screen, without redirecting to an external website.
  • Note: If url is specified, text must also be provided.

1
2
3
4
5
6
7
8
"CompletionTrial": {
  "type": "completion",
  "stimuli": [["ThankYouStimulus", "CompletionCodeStimulus"]],
  "continue_button": {
    "text": "Continue to Survey",
    "url": "https://example.com/post-study-survey"
  }
}
In this example, the continue button will display "Continue to Survey" instead of the default text. When participants click on it, it will open the custom link in a new tab. Participants can still return to this trial and open the link again if they accidentally close the new tab.