Server

The Remote Server works alongside the simulator to manage participants and store study data. It provides two functions: authorization, which verifies participant identities before they can access your study, and data collection, which stores the data generated during each session.

This guide explains how the server works, describes the files it needs and the role of each one, and walks you through deploying it.

Server authorization

You can set up a simple authorization layer for the simulator. It ensures that only valid participants can run the study and that each participant receives a unique Subject ID.

Each participant identifies themselves to the server with a Participant ID (such as a Prolific ID or an mTurk Worker ID). The server responds with a unique Subject ID, which the simulator uses to track that participant during the session.

How authorization works

When the simulator starts, it sends the Participant ID to the server as the search field of a POST request.

1. The simulator (client) sends the Participant ID to the server.
2. The server checks whether this Participant ID has already been used:
   • If the Participant ID is new, the server records it and returns a Subject ID as JSON, for example {"subjectID": 0}.
   • If the Participant ID has already been used, the server rejects the request with HTTP status 409. If the Participant ID is missing, it returns 400.

note

• mTurkServer.php uses simple file storage and does not lock the files. If two requests arrive at almost exactly the same time, there is a small chance that both pass validation with the same Participant ID or receive the same Subject ID. This is unlikely, but possible.
• This authorization is intended as a lightweight safeguard, not a highly secure solution.

For information on configuring server authorization, see Server Authorization settings.

Data collection

The Remote Server also handles data collection. The simulator uploads collected data to the server's senddata.php file, which saves each upload as a file in the data/map00/ folder next to senddata.php (the simulator always sends map00 as the folder name). The file is named [userid]_[original file name].gz.

For details on the data format, storage location, and how to retrieve the data, see the Data Collection Guide.

Deployment

The files needed to deploy the Remote Server are included in the simulator repository, in the server folder at the root of the repository.

Contents of the server folder

File

Function

count.txt

Tracks the current Subject ID. Contains a single number that increases by one each time a new ID is issued.
Important: Reset this to 0 when you start a new study, so that IDs start from zero again.

mturkworkers.txt

Stores the list of used Participant IDs. The server checks this file to make sure IDs are not reused.
Important: Clear this file before a new study if participants from a previous study may take part again; otherwise, they are blocked.

mTurkServer.php

Handles authorization. Receives Participant IDs and responds with either an error message or a valid Subject ID.

senddata.php

Handles data collection. Receives data from the simulator and writes it to a new file on the server.

Start_local_server.cmd

Windows helper for local testing. Starts PHP's built-in web server in this script's folder without clearing existing data. Creates missing authorization files and checks that PHP is available. Use --reset separately to clear participant IDs and reset the counter without starting the server. See Local testing.

doxigen/

Doxygen configuration and generated HTML reference for the server scripts. It is not needed on the web server.

Local testing

Install PHP and make sure the php command is available in your terminal (check with php --version). The Windows helper is a command script, not a separate application.

From a terminal in the simulator's server folder, start it with:

.\Start_local_server.cmd

The script serves its own folder at http://localhost:8000, even when launched from another directory. Existing participant IDs, the counter, and uploaded data are preserved. If missing, mturkworkers.txt is created empty and count.txt is initialized to 0. Keep the terminal open while testing; press Ctrl+C to stop the server.

For local testing, use these simulator settings:

• Server Authorization > Server Address: http://localhost:8000/mTurkServer.php
• Data Collection > Server Address: http://localhost:8000/senddata.php

To clear authorization data, stop the server first, then run:

.\Start_local_server.cmd --reset

This clears all recorded Participant IDs and sets the Subject ID counter to 0, then exits without starting the server. It does not delete uploads under data/. Because Subject IDs are reused after a reset, archive earlier uploads or use a separate test copy to avoid mixing sessions or overwriting files with matching names.

On Windows, macOS, or Linux, you can also start PHP directly from the server folder:

php -S localhost:8000

This command does not initialize or reset authorization files; ensure mturkworkers.txt and count.txt already exist.

warning

PHP's built-in server is for local development, not public deployment. Use a separate copy of the server folder for testing so study data remains untouched. localhost refers to the computer running the simulator; these URLs are not remote participant endpoints.

Public deployment

To deploy the server:

1. Copy the contents of the server folder to a web server with PHP that is publicly reachable by URL.
2. Make sure the web server has read and write permissions for count.txt and mturkworkers.txt (file names are case-sensitive on most web servers), and permission to create the data/ folder next to senddata.php. Authorization and data collection do not work without these permissions.
3. In Project Settings > mobisim > Server Authorization, set the Server Address to the URL of mTurkServer.php on your server.
4. In Project Settings > mobisim > Data Collection, set the Server Address to the URL of senddata.php on your server.