psychoscope-jspsych

This npm package overloads jspsych 7.3.4 with two novel behaviors.

Novel behavior 1: automatically post data to an endpoint

If a task using psychoscope-jspsych is loaded with a query parameter connection_url, it will post data there, as well as start and end messages. If no such query parameter is provided, this does not occur, and jsPsych behaves normally.

Here are the times in which the client will post to the connection_url:

1. On page load, the client will post a "START" event to the connection_url with body:

   {
     "event_code": "START",
     "event_timestamp": "<ISO8601-formatted UTC timestamp>"
   }

2. Whenever the jsPsych on_data_update callback is triggered (i.e. at the end of each jsPsych plugin trial), it will post a "REPORT" event containing the stringified data object to that endpoint, using body:

   {
     "event_code": "REPORT",
     "event_data": "<stringified trial object>",
     "event_timestamp": "<ISO8601-formatted UTC timestamp>"
   }

3. When the timeline on_finish callback is executed, the client will post a request with an empty body to the connection_url, with body:

   {
     "event_code": "END",
     "event_timestamp": "<ISO8601-formatted UTC timestamp>"
   }

See the src/server-communication/conn.ts file for a simple Express server which receives events under the protocol above.

The server may optionally send back JSON responses of the form:

type PostEventResponse = {
   message?: string,
   redirect_url?: string,
}

If message is provided, the client will log it to the console. If redirect_url is provided following the transmission of an END event, the client will redirect to that URL (see below).

Novel behavior 2: automatic redirection

Following the conclusion of the jsPsych timeline (and after the base on_timeline_finish handler concludes), the client will redirect if it receives a JSON response from the server with a redirect_url field (see above).

Building

To actually build the above jspsych.js file from source, cd to the psychoscope-jspsych directory and run:

1. npm install
2. npm run build

The resultant, built file will be located in psychoscope-jspsych/dist/psychoscope/jspsych/7.3.4/jspsych.js.

Local jest testing instructions

The jest test server-communication.test.js runs a simple client locally that automatically traverses the jsPsych timeline with timeline.simulate. This tests that a client using psychoscope-jspsych successfully follow the protocol outlined above.

1. cd psychoscope-jspsych, then install the package using npm install.
2. Run npm run test. This builds the package, then runs jest.