OSWeb
Info
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.
Linking To and From OSWeb
Most online experiment software including OSWeb (but also SONA, JATOS, Pavlovia, Qualtrics, Gorilla etc), have the ability to link to other online platforms / software and send/receive some information via the URL (so called query strings).
For example, you may want to send participants from SONA to an OSWeb task that is hosted on JATOS, and after that on to an exit survey in Qualtrics. In which case, you may want the SONA participant ID to be sent along so you can later match up the data from OSWeb and Qualtrics, and identify who needs to receive credits on SONA (or even better, have it done automatically).
Generally, such linking requires three steps (see also our general introduction to online testing video):
- set up to receive query strings from the preceding part
- if needed, store the values from the query strings in the data
- set up to send along query string to the next part
There are various way to accomplish this, below you can find instructions to some of the often used combinations
- From SONA to OSWeb (on JATOS)
- From LimeSurvey to OSWeb (on JATOS)
- From Qualtrics to OSWeb (on JATOS) to be added
Tips & Tricks
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 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;
document.getElementById('osweb_div').setAttribute("style",`background:${vars.background};`);
} catch (error) {
console.log("Error caught:");
console.error(error);
}
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.
An example experiment with this functionality is available on the SOLO Github organisation, download the file (zipped) here, NOTE: this snippet has not been validated/tested yet. Make sure to check whether it works as intended.
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, see here for information
Programmatic
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.
Alertify
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.
Prepare:
Run:
// 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;
runner._events._currentItem._complete();
};
// 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) => {
console.log(value);
vars.prompt_name = value;
complete();
},
() => {
// Handle cancel click:
console.log('Cancelled');
complete();
}).set('modal', true);
document.getElementById('osweb_div').prepend(document.querySelector('.alertify'));
An online demo can be viewed here, or download the OpenSesame experiment:
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 (i.e. a test version of JATOS that runs on your own computer) you can change a study and re-import (overwrite) it to the remote JATOS server (i.e. the https://jatos.services.universiteitleiden.nl/ server). As the procedure is a bit convoluted, there is step-by-step guide below, and a flowchart of the whole procedure here:
- Before anything else, it is a good idea to backup any data, results and metadata currently in your JATOS study, should anything go wrong. Go to your study in Jatos, and in the Study Results section, export all available data and files
- Export the current study as a .jzip file from the remote JATOS server by clicking ‘Export’ (See Figure 1).
- Start a local JATOS instance with the loader.bat file.
- Open the local JATOS in your browser (127.0.0.1:9000 in the url bar)
- In your local JATOS installation, import the .jzip file by clicking “Import Study”
- The JATOS study assets directory on your computer, located at the location shown on the JATOS homepage (See figure above), now also contains a directory with the assets of this study.
- Go to the ‘Properties’ of your study to find the directory name of this assets directory.
- Go to this folder on your computer and remove all files it contains. It typically contains 3 folders and 2 files.
- 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 or 7zip) to unzip this file. Go to the (only) directory within this unzipped file – it typically contains files similar to the (now removed) files in the jatos assets directory -- 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”
- Finally, import this new .jzip file on the remote JATOS (i.e. https://jatos.services.universiteitleiden.nl/) server by clicking “Import Study”. 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.