Stimuli Timeline Definition

Session recording splits the whole stimuli timeline into three linked timelines, distinguished by whether the devices are recording data or not: pre-session, session, and post-session timeline.

In addition to these, there may also be a special pre-session step defined in the Session Definition for introducing participant into the experiment - Welcome Step.

Timeline playback and session data recording

When a session recording is open from session definition, it starts with welcome step, then follows with pre-session timeline playback, session timeline playback, and post-session timeline playback. Device data recording starts before the first step of the session timeline is displayed and ends after the last step of this timeline is completed.

The following diagram shows timelines playback and session recording events below on boundaries of timelines.

                 |       pre-session timeline steps        |                  session timeline steps                   |   post-session timeline steps    |

   - - - - - - - | ---------------  ----------------       | ---------------  ----------------  ----------------       |  ---------------  -------------  |
   .           . | | eye tracker |  |              |       | | eye tracker |  |              |  |              |       |  |             |  | fixation  |  |
   .  welcome  . | | calibration |  | instructions |  ...  | | validation  |  | instructions |  | show desktop |  ...  |  | questionary |  | filtering |  |
   .           . | |             |  |              |       | |             |  |              |  |              |       |  |             |  |           |  |
   - - - - - - - | ---------------  ----------------       | ---------------  ----------------  ----------------       |  ---------------  -------------  |
   
   ^             ^                                         ^                                                           ^                                  ^
session       session                                session running                                            session processing                     session
 open        preparing                            data recording starts                                        data recording stops                   completed

These rules apply for every session recording:

• Welcome step may be omitted (ignored), if specified.
• Pre-session timeline is optional and may be empty.
• Session timeline may be empty, but defaults to a single Show Desktop step.
• Post-session timeline is optional and may be empty.

Each timeline step is defined with its action and completion settings. Step may be completed with timeout, hotkey press, or on its own, e.g., the participant clicks on the button to continue from instructions, or confirms the eye tracker calibration.

Timeline step definition

• action : StepActionSettings object - defines step type with name and settings:
  • actionType : string (required) - name of the timeline step.
  • other settings specific to each timeline step, see below.
• completion : StepCompletionSettings object (optional) - defines how the current step can be completed:
  • duration : TimeSpan (optional) - timeout duration in hh:mm:ss format, e.g., for 10 minutes use "00:10:00"
  • hotkeys : string[] (optional) - array of keys enabled to complete the step, any of the following values:
    • Space, Enter, PageUp, PageDown, Left, Right, Up, Down, Tab, F1..F11
  • default: no completion settings, participant must advance to next step using the client application UI.

Step types

Currently, these steps are supported:

• Eye Tracker Calibration
• Eye Tracker Validation *
• Instructions *
• Questionary *
• Show Desktop
• Launch Program
• Close Program
• Fixation Filter

* These steps displays content to the participant and may be styled, see Content Step Styling for details.

Example

Show instructions to the participants for 30 seconds or until the F10 key is pressed:

{ 
    "action": {
        "actionType": "Instructions",
        "instructions": "Find and add green toy car to the shopping cart from the products list."
    },
    "completion": {
        "duration": "00:00:30",
        "hotkeys": [ "F10" ]
    }
}

See details of each step for more examples.

Step result

For every timeline step executed during the recording, result data are stored alongside the original step definition in the session recording data. In addition to common properties, each step may add its own specific properties to the result data object, see their description for more details.

• step : TimelineStep - original definition object of the executed step.
• startedAt : DateTime - local timestamp when the step execution started, i.e., when it was displayed to the participant.
• result : TimelineStepResult - result of the executed step
  • resultType : string - how the step was completed, any of the following values:
    • "Successful" - participant successfuly completed the step,
    • "Skipped" - step was skipped through the application UI,
    • "Failed" - step execution was interrupted, recording session was cancelled.
  • (optional) Result data specific to each timeline step, see Result section in definitions of each step, if any.