Tips & tricks
Batch and Group Session do not work on Windows without HTTPS
Batch and Group Sessions in JATOS rely on WebSockets. Occasionally (though rarely), a virus scanner on a Windows operating system may block unencrypted WebSockets. This issue is specific to Windows and certain antivirus programs; it does not typically occur on macOS or Linux.
If this happens, you will see an error message in your browser's console: Batch channel closed unexpectedly
. To resolve this, you have two options: either enable HTTPS on your JATOS server (which is recommended) or disable the problematic virus scanner on all participant's computers.
Run Studies Simultaneously in the Same Browser
While participants typically run only one study at a time, running multiple studies in parallel within the same browser can be an immensely useful feature during study development, especially when working with Batch Sessions or developing group studies.
You can run your study in up to 10 tabs simultaneously in the same browser, using any worker type you choose. All these "different" workers can interact with each other. If more than 10 studies run in parallel within the same browser, the oldest study will automatically finish. If you require more parallel workers, you can adjust the jatos.conf
field jatos.idCookies.limit
(available from v3.9.6 onwards).
Simple Load or Stress Test for Your Study
Before going "live" and distributing study codes to your participants, it's a good idea to test your experiment and JATOS server under load. This means checking how your study performs when multiple participants run it simultaneously.
First, obtain a General Multiple study link, as this type can be used repeatedly. Then, use the following command for either Linux or macOS (remember to replace the example URL with your actual study link). This command will open 10 browser tabs, with a 0.5 seconds pause between each, and each tab will run your study.
For Linux:
seq 10 | xargs -I{} -- sh -c 'xdg-open https://www.example.com/publix/q9umWwAIUZ6; sleep .5'
For macOS:
seq 10 | xargs -I{} -- sh -c 'open https://www.example.com/publix/q9umWwAIUZ6; sleep .5'
Imitate an MTurk Run
Testing studies posted on MTurk can be cumbersome, especially ensuring that confirmation codes are correctly displayed upon study completion. The standard method involves creating a study in MTurk's Sandbox. However, there's a simpler way to imitate an MTurk run without setting up anything in the sandbox.
Essentially, MTurk calls a JATOS study link, which is just a URL (e.g., http://my-jatos-server/publix/tmJ4Ls83sV0
, where tmJ4Ls83sV0
is your study code and should be replaced). Two additional query parameters in the URL, workerId
and assignmentId
, inform JATOS that the request originates from MTurk. While these are normally generated by MTurk, you can use any arbitrary string for their values during imitation.
Examples
To run the study with a specific study code (e.g.,
myStudyCode
) and imitate an MTurk worker on a local JATOS, use the following URL:http://localhost:9000/publix/myStudyCode?workerId=123456&assignmentId=abcdef
You can use any arbitrary values for
workerId
andassignmentId
(e.g.,workerId=123456
andassignmentId=abcdef
as shown). Remember to replacemyStudyCode
with your actual study code.To imitate a run from MTurk's Sandbox, additionally set
turkSubmitTo
to the value 'sandbox':http://localhost:9000/publix/myStudyCode?workerId=123456&assignmentId=abcdef&turkSubmitTo=sandbox
Lock Your Studies Before Running Them
Each study's toolbar features a button that toggles between 'Unlocked' and 'Locked' states. Locking a study prevents changes to its properties (or any of its components' properties), component order, and other settings.
Run a General Single Study More Than Once in the Same Browser
A General Single Run is designed to be completed only once in a given browser. While this feature helps prevent participants from doing the same study twice, it can be a hassle for study developers who need to test a General Single Run repeatedly.
Fortunately, there's an easy workaround: JATOS stores information about studies a worker has participated in for a General Single Run in a browser cookie. You can easily remove this cookie. Simply delete the cookie named JATOS_GENERALSINGLE_UUIDS
in your browser. This cookie can be found on any webpage hosted by a JATOS server. If it doesn't exist, you likely haven't performed a General Single run yet.
Abort Study and Keep Specific Data
If the jatos.abortStudy
function is called (typically after a worker clicks a "Cancel" button), all result data previously sent to JATOS during that study run will be deleted, including data from prior components. However, there are instances where you might need to save a small piece of information that should not be deleted, such as a worker's email address for payment purposes.
You have two methods to retain such data:
Using the built-in abort button with
jatos.addAbortButton
: Set themsg
parameter. This message will not be deleted along with other result data and can be seen in the 'Message' column on the Study Result page.E.g.:
jatos.addAbortButton({
msg: "Participant ID: 12345678",
});Using the
jatos.abortStudy
function directly: Pass your message via its parameter. This message will also be preserved and visible in the 'Message' column on the Study Result page.E.g.:
jatos.abortStudy("Participant ID: 12345678");
How to Let a Personal Single Worker Redo Their Study
A Personal Single Worker is designed to run their study only once. However, you might occasionally need to allow them to redo it (e.g., if they accidentally clicked "Cancel"). One option is to provide them with a new Personal Single Link. Alternatively, you can simply delete the worker's existing result from one of the results pages. Deleting the result will enable that specific Personal Single worker to redo the study.
Simulate Slow Network Conditions
While you typically develop studies on a local JATOS instance or a remote server with a robust internet connection, your participants might have slower internet connections or use mobile networks. All studies should account for this, especially those involving large files like images, audio, or video.
You can artificially throttle network speed using the Developer Tools in Firefox and Chrome. Select a slower connection preset, such as '3G', and test your study again. This works on any JATOS installation, whether local or remote.
Personal/General Single Links: Issues with Social Networks
Problem: Your study runs correctly when tested directly, but when Personal Single or General Single links are handed out via social networks like X/Twitter, Facebook, and Reddit, or chat tools like Slack and Google Hangouts, they stop working. Participants receive the message "A problem occurred: Study can be done only once," and in the JATOS results, the study run appears as 'STARTED' or 'DATA_RETRIEVED' but never 'FINISHED'.
Reason: Some social media and chat platforms automatically open links posted within them before your participant can click on them. They do this to generate previews (e.g., displaying a title and image for the link). While usually harmless, this becomes an issue for Personal/General Single links because these links are designed to work exactly once (if preview is not allowed). The platform's automated request "uses up" the link, causing a second request from the actual participant to receive the aforementioned error message.
Solutions:
- Use study links with confirmation: Choose the 'Confirm First' version of the study link. This link displays a "study entry" page before the actual study begins, and this entry page can be opened multiple times without invalidating the underlying single-use link.
- Allow preview: You can continue using Personal/General Single links and enable a preview link. This allows participants to open the first component of your study as many times as they wish. The single-use restriction then applies only to subsequent components.