From Solowiki
Revision as of 15:24, 13 July 2020 by Anneloes (talk | contribs)
Jump to navigation Jump to search

OSWeb is a JavaScript-based online runtime for OpenSesame experiments and the JATOS hosting platform. It basically interprets an OpenSesame experiment and runs it in a web-browser using HTML5 and JavaScript, including some third-party libraries such as PIXI.js. Unfortunately, the OSWeb plugin does not feature extensive technical documentation, so most of the approaches described here are inferred from the source code and the generated JavaScript files. This document aims to offer tips and (experimental) quick-fix workarounds for common issues, for more official information and support, please refer to their official website and its very active forum. Always thoroughly test your task after implementing anything described here.

Note, this page was written for OpenSesame v3.3.2 and OSWeb v1.3.8.

Generating a JATOS Package

When generating a JATOS package using OSWeb, it creates a zip file with an info.jas file in the root, which contains all JATOS-specific metadata about the study. Inside a sub-folder, it adds the main web-page (index.html), which is what JATOS runs as the first and only component of the study (as defined in the .jas file). The same sub-folder also includes the .osexp file, which is a package containing the OpenSesame experiment and all files in the file pool. Additional resources necessary for loading, interpreting and running the experiment are located inside second-level sub-folders.

The JavaScript and JSON that OSWeb generates is purposely uglified (and stripped of comments), so you will need to prettify it to make sense of it (or refer to its the source code).

Full-Screen Experiments and Stimulus Sizing

OSWeb can be configured to run experiments in full-screen, but will by default stretch the scene to fit the screen, which may cause distortion. As a benefit, however, when OSWeb is configured to run in full-screen, it will detect when participants exit the full-screen mode, and prompts them to return to full-screen or about the experiment. This is in contrast to having users manually enter full-screen (by pressing F11), or programatically toggling the browser’s full-screen mode via JavaScript (requestFullscreen()), both of which will render OpenSesame unset to detect full-screen changes.

Note, when messing with the sizing and dimensions, always make sure that your, relative sizes and spacing, hit-tests, etc. still work.

Overriding the Scale-Mode

In OpenSesame, the full-screen mode can be enabled by ticking the checkbox in the OSWeb tab. This results in a full-screen flag being set to true in both the index.html and info.jas files. The latter will be user-editable in JATOS via the JSON input entry of the component properties, and will override the index.html setting. This allows users to enable or disable the full-screen in JATOS without having to regenerate the task in OpenSesame. By default, however, the full-screen will operate by stretching the scene so that it fits the participants screen, which may cause distortion. This scale mode called “exactFit”, and is unfortunately hard-coded in index.html (as the scaleMode property of the context object, which contains the basic parameters necessary for running the experiment in the browser).

It is possible, however, to programatically change the scaleMode during runtime by the code below to the Prepare tab of a JavaScript inline object, which should be the first object in the experiment. Note that when running in “noScale” mode, the actual scaling is still subject to the browser’s zoom level.

// The code below will fetch the scaleMode from the 
// the Batch Properties in JATOS--or, if unavailable,
// use the defaultScaleMode set below--to override
// the OSWeb scaleMode parameter.
// The scale modes are:
//   noScale  -> no scaling.
//   showAll  -> scales (w/o stretching).
//   exactFit -> scales/stretches to fill screen fully.
vars.curScaleMode = "NOT BROWSER";
try {
    const defaultScaleMode = "noScale";
    if (typeof jatos != "undefined") {
        var batchParams = jatos.batchJsonInput || {};
    } else {
        var batchParams = {};
    runner._scaleMode = batchParams.scaleMode || defaultScaleMode;
    vars.curScaleMode = runner._scaleMode;
} catch (error) {
    console.log("Error caught:");

The same demo task is linked below through general workers in three different batches, each of which sets a different scaleMode:

  • "noScale": does not scale the experiment.
  • "showAll": scales the experiment uniformly so that it fits the screen.
  • "exactFit": scales and, if necessary, distorts the experiment so that it fully fills the screen.

Download the alertify file linked below to see an implementation of the scale-mode override code.

True-Size Dimensioning

Even when running experiments without scaling, true-size dimensions cannot be guaranteed due to differing pixel densities, DPI and zoom settings, etc. As such, if your experiment requires that stimuli be of specific real-life sizes, a calibration procedure is required. This generally consists of having participants match a shape on the screen with a real-life object of know size, such as an ID card.

Code and examples for this section have yet to be developed. Please email labsupport@fsw.leidenuniv.nl if you are considering this approach.

Data Input

Version 1.3.8 of OSWeb does not have built-in support for forms. The easiest way to collect custom user information is probably to use Qualtrics in combination with OSWeb and JATOS, and redirect users from and/or to the Qualtrics survey before and/or after the OSWeb/JATOS study. This can also be done in a way that passes information between the sessions.


In OpenSesame, JavaScript inline objects, combined with some clever sketchpads, loops and sequences, can be used to collect simple user input; as described here for collecting a student number.


OSWeb includes the alertify library and uses it to display its prompts, warnings and errors. This library can also be used to easily collect input from the user by adding an JavaScipt inline object to OS with the code below.


vars.prompt_name = "NO_NAME";


// Create a variable to hold the current object's completion
// function, which we will disable, then manually retrigger 
// later in order to pause the sequence here.
var tempComplete = runner._events._currentItem._complete;
runner._events._currentItem._complete = () => {};
var complete = () => {
    runner._events._currentItem._complete = tempComplete;

// Create the prompt, and add it to the osweb_div so that
// its visible:
var ePrompt = alertify.prompt("Please enter your name:", "",
    // Handle OK click:
    (evt, value) => {
        vars.prompt_name = value;
    () => {
        // Handle cancel click:
    }).set('modal', true);

An online demo can be viewed here, or download the OpenSesame experiment: File:Alertify.zip

Updating the OSWeb component in an Online JATOS Study

JATOS doesn’t provide a direct option for updating a (OSWeb) component in an existing JATOS study whilst keeping all results, worker links and other settings. However, using a local JATOS installation you can change a study and re-import (overwrite) it to the remote JATOS server.

First export the current study as a .jzip file from the remote JATOS server by clicking ‘Export’ (See Figure 1). In your local JATOS installation, import the .jzip file by clicking “Import Study” (See Figure 1). The JATOS study assets directory on your computer, located at the location shown on the JATOS homepage (See Figure 2), now also contains a directory with the assets of this study. Go to the ‘Properties’ of your study (See Figure 1) to find the directory name of this assets directory (See Figure 3). Go to this folder on your computer and remove all files it contains. It typically contains 3 folders and 2 files (See Figure 4).

Export your updated OpenSesame task (like normally using the “Export as JATOS study” button in the OSWeb extension) as a .osexp.zip file. Use a file compression tool (e.g. WinRAR) to unzip this file. Go to the (only) directory within this unzipped file – it typically contains files similar to the files shown in Figure 4 -- and copy/paste all files to the emptied study assets directory.

Now, when you run your local JATOS study it runs the new version of your OpenSesame task. To update also your online JATOS task, export this study as a .jzip file by clicking “Export” (See Figure 1) and import this .jzip file on the remote server by clicking “Import Study” (See Figure 1). Click “Overwrite” in the pop-up that appears; this updates your OSWeb component in the study, but does not remove any results, worker links or other settings.