New Features

• Added the concept of extensions to the jsPsych architecture. Extensions are code modules that are designed to extend the functionality of any plugin. Eye tracking is an example of a feature best supported via an extension. The extension is responsible for gathering gaze data and adding the data to the trial. The advantage of using an extension is that the feature can then be added on top of any existing plugin. See the new extensions documentation for more information (#1123, #1516).
• Eye tracking is now available via an extension that utilizes the 3rd party WebGazer library. See the new eye tracking overview in the documentation, plus example experiments in the /examples folder (#1516).
• Three new plugins to support eye tracking. jspsych-webgazer-init-camera will initialize the camera for eye tracking, jspsych-webgazer-calibrate performs calibration, and jspsych-webgazer-validate performs validation and report data about the accuracy and sampling rate of the eye tracking (#1516).
• Added the virtual-chinrest plugin, an implementation of the procedure described by Li, Joo, Yeatman, and Reinecke (2020) for measuring the distance between the participant and the monitor. This plugin also merges in features from the resize plugin to allow for scaling of the display to known dimensions, e.g., ensuring that 200px = 2cm. Thanks @GEJ1 and @pjkohler! (#1442)
• New css_classes parameter available in all plugins. This allows you to add one or more custom CSS classes to the display element on that trial, which makes it easier to change style/formatting across trials. For more information, see the new Controlling Visual Appearance documentation page and the "css_classes_parameter.html" example file (#832, #1378)
• New save_trial_parameters parameter available in all plugins. This allows you to override the plugin's default trial data, by saving additional parameter values that are not normally saved, or not saving parameter values that normally are saved. For more information, see the parameters available in all plugins page and the "save_trial_parameters.html" example file (#823, #1555)
• jsPsych.version() returns the version of jspsych.js as a string (#1472).
• jsPsych.allTimelineVariables() returns all the timeline variables and their values at that moment in the experiment (#1237, #1493)
• It's now possible to use dynamic parameters (functions as parameters) in nested trial parameters. For instance, in the questions parameter in survey-* plugins, you can use a function for any of the individual parameters in each question object, like the prompt. See the updated documentation on dynamic parameters. (#988, #1497)
• The new preload plugin now handles all media preloading. This makes preloading more customizable, and it makes it easy to preload files at any point during an experiment. This plugin contains new options for things error messanges and handling file loading success/failure. For more details, see the preload plugin documentation. Thanks @javidalpe! (#1234, #1351).
• The freesort plugin now works on mobile devices, and includes a new column_spread_factor parameter to control the spread of image columns to the right and left sides of the sort area. Thanks @kurokida! (#1228, #1546)
• Added and updated documentation on the jsPsych website (#1374), including new pages about:
  • dynamic parameters
  • using and creating plugins
  • links to tutorial videos
  • integrating with Prolific
  • controlling the visual appearance of your experiment
• on_timeline_start and on_timeline_finish callbacks allow you to run arbitrary code at the start/end of at timeline node (including timeline variables, conditional/loop nodes, etc.). See the Timeline and Event-related callback functions pages for info and examples. (#585, #1512)

Changes

• Keys must be given as strings in trial parameters (e.g. choices: ['a']) and are saved as strings in the data (e.g. response: 'a'). Numeric keycodes are no longer accepted and numeric keycodes are no longer used in the data output. This change was made because numeric keycodes are deprecated and future browsers could drop support, so key responses are now recorded using the event's .key property. Key strings are also easier to work with and produce more readable data.
• Because .key based responses distinguish between upper and lower case input, a new flag was added to jsPsych.init called case_sensitive_responses. This setting is false by default, but you can set this flag to true if you want case sensitivity for your key choice parameters and participants' keyboard responses. This setting does not affect responses that are typed into text boxes. For a full summary of the changes related to this shift, see #1465 and the jsPsych.init documentation. (#396, #1465).
• We now recommend using jsPsych.pluginAPI.compareKeys to compare keys in all plugin and experiment code, rather than using something like if (response == 'j').... Using this compareKeys function will ensure that your key comparisons work appropriately based on the experiment's case_sensitive_responses setting. See the compareKeys documentation for more information.
• Media preloading is no longer done through jsPsych.init, so the preloading-related parameters in jsPsych.init are no longer supported (show_preload_progress_bar, preload_audio, preload_images, preload_video, max_load_time, max_preload_attempts). Please use the new preload plugin instead.
• jsPsych plugins can now store complex trial data as JavaScript objects and arrays, instead of JSON-encoded strings. This fixes problems with parsing jsPsych JSON data that were caused by nested JSON strings. This also means you no longer need to use JSON.parse during an experiment to access data that is stored in objects/arrays (e.g. responses to survey-* questions), and plugins should not use JSON.stringify when saving trial data. (#670, #1523)
• In an effort to standardize the response variable names across plugins, many data property names have been changed to response. Examples of data properties that have changed include key_press (*-keyboard-response trials), button_pressed (*-button-response trials), and responses (survey-* trials). In some cases, the data structure has changed so that response information can be stored in a single response property (e.g. maxdiff and serial-reaction-time-mouse plugins). These changes were made in order to reduce the number of different columns and empty cells that are generated when jsPsych data is stored in tabular format, such as CSV. For more information, see the documentation for specific plugins, and this list of all data property name/structure changes across plugins. (#638, #1529)
• You can now use the jsPsych.timelineVariable function without second the true argument. This function will determine whether or not it should return the timeline variable value immediately, based on the context in which it's called. Thanks @vijaymarupudi! (#883, #1376)
• jsPsych.pluginAPI.getAudioBuffer() will now attempt to load audio files that haven't been preloaded. This means that preloading audio files is no longer strictly necessary, though of course it is still highly recommended. In order to make this feature possible, getAudioBuffer() now returns a Promise and plugins that use this method have been updated. (#1527, #1543)

Bug Fixes

• Fixed problem that was causing the response_allowed_while_playing parameter not to work in the audio-button-response and video-button-response plugins when custom button_html was used. (#1380, #1384)
• Fixed bug in image-* plugins that was causing images not to be displayed when images were not preloaded and when render_on_canvas was true (the default). (#1305, #1375)
• Improved documentation and fixed various documentation errors. Thanks @pablobernabeu and @alexanderrobertson! (#1413, #1401, #672)
• The fullscreen plugin now checks to see if fullscreen mode is active before trying to exit fullscreen. Thanks @klanderson! (#1354)