Running a jsPsych Study on GitHub with DataPipe and Automatic Redirect to SONA or Prolific

📑 Table of Contents

• Purpose
• Step 1: Get Ready
• Step 2: Build Your jsPsych Experiment
• Step 3: Upload Files to GitHub
• Step 4: Turn On GitHub Pages
• Step 5: Create OSF Repository
• Step 6: Connect to DataPipe
• Step 7: Put Study on Prolific
• Step 8: Put Study on SONA
• Step 9: Set Up Redirect Links
• Step 10: Test the Study
• Step 11: Go Live!
• Final Checklist
• Suggestions
• Common Issues

🔎 Purpose

To set up and run an online psychology experiment using jsPsych hosted on GitHub Pages, saving data with DataPipe, and automatically sending participants back to Prolific or SONA for credit.

📝 Step-by-Step Guide

🔹 Step 1: Get Ready

You will need:

• A Github account.
• An OSF account.
• A DataPipe account.
• A SONA account (if using SONA). Apply to be added as a new user here.
• A Prolific account (if using Prolific).
• Your jsPsych experiment files.

🔹 Step 2: Build Your jsPsych Experiment

Your folder should include:

✔ Tip: Use the latest lab jsPsych Experiment Template.

🔹 Step 3: Upload Files to GitHub

1. Create a new repository → Name it (e.g., metacognition_study).
2. Upload your experiment files.
3. Commit changes.

🔹 Step 4: Turn On GitHub Pages

1. Go to your repo Settings → Pages.
2. Under Branch, select main and /root.
3. Click Save.
4. Copy the study link (e.g., https://yourusername.github.io/metacognition_study/).

🔹 Step 5: Create OSF repository

Data is stored automatically in a repository on OSF. You will need the repository ID to set up the data piping

1. Go to OSF and create a new project.
2. Got to your new project, in the URL you can find the OSF Project. For example,

https://osf.io/xyztnu/

The OSF Project would be xyztnu. Copy it for the next step.

🔹 Step 6: Connect to DataPipe

1. The first time you use DataPipe you will need to link it to OSF. Follow the instructions here under Link your OSF account to DataPipe
2. Go to DataPipe and create a new project.
3. The Title can be whatever you like.
4. Under Existing OSF Project copy the OSF Project code.
5. New OSF Data Component Name can be whatever you like (it will be the name of the folder where the data is stored)
6. Turn on Enable data collection? and Enable condition assignment? (even if only 1 condition)
7. Copy the Dataset ID.
8. In your index.html update:

const DataPipe_ID = "YOUR_DATAPIPE_ID";

🔹 Step 7: Putting the study on Prolific

1. Go to Prolific.
2. To be added to the lab team (and use the lab funds), let Kit know your Prolific username.
3. Create a new study
4. Study name and Study description come directly from the ethics documents.
5. Internal study name should used the format LastName-TASK-experiment-name.
6. Typically, you want to limit the study to only desktop devices.
7. Study URL was generated in Step 4. You should automatically append the Prolific ID to the URL by clicking Recroding Prolific IDs = URL parameters
8. Completion paths can be set to automatic approve & pay. Copy the completion code (e.g. CGJ91R8S for use in Step 9).
9. Set the length of time and pay people £6 per hour
10. Set the sample country and click Quota Sample to make sure you get a balanced sample between males and females.

🔹 Step 8: Putting the study on SONA

1. You can read the SONA handbook for detailed procedures.
2. Go to SONA.
3. Select Add new Study from the menu bar
4. Select Online External Study.
5. Study name, Brief Abstract, and Detailed Description come directly from the ethics documents (Teams > Ethics).
6. Duration and credits should match so 1 = 60 minutes
7. Human Res Ethics Com Approval Code should be set to the ethics protocol number (Teams > Ethics). For example, 2022/796.
8. Study URL was generated in Step 4. You should automatically append the SONA ID to the URL by appending ?SONAID=%SURVEY_CODE%

https://yourusername.github.io/metacognition_study/?SONAID=%SURVEY_CODE%

9. Active Study? = Yes; Automatic Credit Granting = Yes. Everything else can be left as it is.
10. You will need your SONA experiment ID and credit token for Step 9. You can find them both in the Completion URLs listed under Study Information. See highlighted section below:

11. You need to Request approval of a NEW SONA study get your study approved by the School's research staff. Complete the form here.
12. For the question asking you to copy and paste the description from ethics concerning SONApsych participants, you should copy from the ethics documents (Teams > Ethics > Application Form). For example, 2022/796 ethics docs read:
1) Sydney University Psychology Research (SONA) participant system. First year psychology (PSYC1001 and PSYC1002) complete SONA studies for course credit. 1) SONA system: We intend to recruit participants through the Sydney University Psychology Research (SONA) participant system, where first- and second-year psychology students sign up and participate in experiments in exchange for course credit. SONA operates in accordance with the School of Psychology’s guidelines on research participation.

🔹 Step 9: Set Up Redirect Links

In your index.html, declare:

const sona_experiment_id = "YOUR_SONA_ID";        // SONA experiment ID
const sona_credit_token = "YOUR_SONA_TOKEN";                // SONA credit token
const Prolific_redirect = "YOUR_PROLIFIC_COMPLETION_CODE";  // Prolific credit redirect code
const Prolific_failed_check = "YOUR_PROLIFIC_FAIL_CODE";   // Prolific attention check failure redirect code

If you are recruiting from both Prolific and SONA, fill in all 4 of the above tokens, or leave blank if not applicable.

The code automatically checks the participant’s URL:

const PROLIFIC_PID = jsPsych.data.getURLVariable('PROLIFIC_PID');
const SONAID = jsPsych.data.getURLVariable('SONAID');

The code will show the relevant PIS based on which of these IDs it detects, strore the source of the participant and their ID. Note, it assumes the participant is from Prolific if no ID is provided.

In your code you should also declare the task time (which should match Prolific or SONA)

    const task_time = 25;                      // Task duration in minutes

So that the same version of the study can be used to recruit both from SONA and Prolific, a transformation is applied to the task_time variable to round it up to the nearest 15 minutes. For example, if you enter 42 minutes, the SONA PIS will show 45 minutes, while the Prolific PIS will show 42 minutes.

✅ Your file should be ready to be uploaded to Github.

🔹 Step 10: Test the Study

1. Visit your GitHub Pages study link.
2. Add parameters to the URL to simulate real participants:
   • https://yourusername.github.io/metacognition_study/?PROLIFIC_PID=123ABC
   • https://yourusername.github.io/metacognition_study/?SONAID=S1234567
3. Run the study yourself.
4. Confirm:
   • Data saves to DataPipe.
   • Redirect works correctly.

🔹 Step 11: Go Live!

• Launch the study on SONA by adding slots or on Prolific by launching the study (or both).
• Monitor incoming data on your OSF repository.
• Data can be manually downloaded from OSF or automatically downloaded using our R package: MetaLab::combine_osf_csvs("YOUR_OSF_PROJECT_ID", folder = "../Data/")

✅ Final Checklist

📝 Suggestions

🚨 Common Issues