psiturk.js API

Everything in the psiturk.js API is scoped under the psiturk namespace.

Creating the psiTurk object

To use the psiTurk library, a psiturk object must be created at the beginning of your experiment. It takes two key arguments uniqueId and adServerLoc. These two variables are first created in exp.html <file_desc/exp_html.html>. They tell psiTurk which unique number/code corresponds to the current participant (allowing updating of data as the task progresses) and the location of the ad where users should be sent when the task is complete.

// Create the psiturk object
var psiturk = PsiTurk(uniqueId, adServerLoc);

// Add some data and save
psiturk.addUnstructuredData('age', 24)

The following documents the javascript API.


taskdata is a Backbone model used to store all data generated by a participant and to sync it to the database.

taskdata has the following fields with these default values:

condition: 0
counterbalance: 0
assignmentId: 0
workerId: 0
hitId: 0,
useragent: ""
currenttrial: 0
data: ""
questiondata: {}
eventdata: []

These variables are either set during initialization or using the methods of the psiturk object. However, since taskdata is a Backbone model, you can always access their values directly using the Backbone `set <>`__ and `get <>`__ methods, which may be useful for debugging. For example:

psiturk.taskdata.set('condition', 2);


For each path in pagelist, this will request the html and store in the psiturk object. A given page can then be loaded later using psiturk.getPage(pagename).

Returns a Promise. See the example task.js for a full usage example.


// Preload a set of HTML files
async function example() {
  await psiturk.preloadPages(['instructions.html', 'block1.html', 'block2.html']);

  // Set the content of the body tag to one of the pages



Retrieve a stored HTML object that has been preloaded using psiturk.preloadPages.


Set the BODY content using an HTML object that has been preloaded using psiturk.preloadPages.


async function example() {
  psiturk.preloadPages(['instructions.html', 'block1.html', 'block2.html');


Cache each image in imagelist for use later.


Add a single line of data (a list with any number of entries and any type) to the psiturk object. Using this will not save this data to the server, for that you must still call psiturk.saveData().


// data comprised of some list of variables of varying types
data = ['output', condition, trialnumber, response, rt];

psiturk.recordUnstructuredData(field, value)

Add a (field, value) pair to the list of unstructured data in the task data object.


psiturk.recordUnstructuredData('age', 24);


Sync the current psiTurk task data to the database.

An optional argument callbacks can provide functions to run upon success or failure of the saving.

   success: function() {
      // function to run if the data is saved
   error: function() {
      // function to run if there was an error


This finishes the task by passing control of the experiment back to the Secure Ad Server <secure_ad_server.html>. When in debug mode this just cleans up the task. When running live on the sandbox or live site this passes control of the browser back to the Ad Server so that the subject can be marked as complete and the user’s browser will correctly finish the HIT on Amazon’s site.

psiturk.doInstructions(pages, callback)

psiTurk includes a basic method for showing a sequence of instructions. You are always free to write your own instructions code (and may need to). However, this provides a basic template for a pretty simple typical type of instructions composed of a sequence of multiple pages of text and graphics along with a “next” and (optionally) “previous” button.

The doInstructions() method takes two arguments. The first is a list of HTML pages that you would like to display. These should appear in the order you would like them to be displayed to participants. The instructions method uses the showPage() method to display the HTML of the page.

Prior to calling doInstructions() all the instruction pages you plan to display should be preloaded using the preloadPages() method.

Within each HTML page there should be a button or other HTML element with class equal to continue which the user can click to move to the next screen.

An Bootstrap example is:

<button type="button" id="next" value="next" class="btn btn-primary btn-lg continue">
    Next <span class="glyphicon glyphicon-arrow-right"></span>

In addition, if the HTML document includes an element with class previous it will, when clicked, go to the previous page. As a result you should not include a previous button on the first HTML page.

An example previous button using Bootstrap is:

<button type="button" id="next" value="next" class="btn btn-primary btn-lg previous">
    <span class="glyphicon glyphicon-arrow-left"></span> Previous

The final argument to the instructions object is the method to be called when the “continue” button on the last page of the instructions is called.


async function start_experiment(){
  psiturk = new PsiTurk(uniqueId, adServerLoc);

  var pages = [
  await psiTurk.preloadPages(pages); // preload the pages

  var instructionPages = [ // any file here should be preloaded first
      "instructions/instruct-3.html"]; // however, you can have as many as you like
                          function() { currentview = new StroopExperiment(); });

The last line in this example uses an anonymous function to launch the Stroop Experiment.


finishInstructions is used to change the participant’s status code to 2 in the database, indicating that they have begun the actual task.

In addition, this removes the beforeunload handler such that if people attempt to close (or reload) the page, they will get an alert asking them to confirm that they want to leave the experiment.

You do not have to use doInstructions() in order to call finishInstructions(). In the example above you would want to call psiturk.finishInstructions() in the StroopExperiment() class.


psiturk = new PsiTurk(uniqueId, adServerLoc);