Guide to childlanglab

Workflow for hosting jspsych experiments with github pages

Purpose

To provide a workflow to host jspsych experiments simply via github pages and push data to our database

Procedure

Prerequisites

1. Program your experiment with jspsych
2. Add your experiment to an empty github repo (use pennchildlanglab for lab experiments)

Host on github pages

1. Go to Settings > Pages
2. Under Build and deployment source select Deploy from a branch
3. Under Build and deployment branch select main and /root
4. At the top you’ll see where your site is live (e.g. https://pennchildlanglab.github.io/penguin-lexical-decision/)

Push data to lab database

1. Add the following <script> tags to your html header

   /* add the call function jspsych plugin*/
    <script src="https://unpkg.com/@jspsych/plugin-call-function@1.1.3"></script>
   /* add the childlanglabClient to push to database */
    <script src="https://nyc3.digitaloceanspaces.com/experiments.childlanglab/childlanglabClient.js"></script>
   

2. Add the following jsPsych call function to your code

   var sendData = {
      type: jsPsychCallFunction,
      async: true,
      func: function (done) {
        let data = jsPsych.data.get().json();
        childlanglabClient.sendData(data);
        done("Sent data object to childlanglab-api")
       
      },
    };
   

3. In your jsPsych timeline, call the sendData function at the end of your experiment (but before your thanks screen and prolific redirect)

   /* create timeline */
     var timeline = [
       consent, 
       welcome,
       preload,
       instructions,
       sendData,   // add send data here 
       thanks
     ];
     /* start the experiment */
     jsPsych.run(timeline);
   

4. Add your experiment to the lab database
   • Under an existing experiment, you can add a + New Version to add a new version of your experiment
   • Or you can create a new experiment and then add + New Version once created
   • You add the path to your experiment (e.g. https://pennchildlanglab.github.io/penguin-lexical-decision/experiment.html) without URL variables
5. Use the Run experiment button on your experiment’s page in the database to run your experiment

FAQ

• I made changes but they aren’t showing up on my live site

  You need to make sure you commit your changes via the usual gihtub workflow

    git add .    
    git commit -m "description of my changes here"
    git push origin main
  

  And also note that changes can sometimes take a few minutes to publish to the web

• I clicked on my live site but I got a 404 error

  Your site will only be live at the live site listed if you have happened to name your experiment’s .html file index.html. Otherwise you’ll have to add the filename to the end of the live site’s url (e.g. https://pennchildlanglab.github.io/penguin-lexical-decision/experiment.html)

• Can I just call childlanglabClient.sendData(data) in my initJsPsych on_finish parameter?

  No, that won’t work. The Client needs a little time to send the data. Putting it in the timeline ensures the participant will wait to see the thanks screen before closing the window, allowing the data time to push to the database.

• Can I call sendData more than once, after every trial?

  No. Calling at the end of the experiment allows us to keep our costs down, so we aren’t making calls to our database every few seconds. When you preregister your experiment, you can say that we exclude participants who do not provide usable data (e.g. by not finishing the experiment).

• I’ve followed the guide but my data is still not pushing to the database

  Our database has some security features so only our lab members can push data. (1) you have to run the experiment using the Run experiment button on your expeirment’s page in the database (via ReTool), because our database requires very specific URL parameters generated there; (2) you have to run the experiment from a trusted url. One is our lab github organization (pennchildlanglab.github.io). To add your personal github org to trusted hosts, ask Katie via slack to add you.