Introduction to integrations

If you haven't already checked out our basic study set-up guide, you should do so before exploring this advanced guide. Pavlovia also have a help center that provides all of the information required to help you set up your study. We encourage all of our researchers to review the information provided there before setting up their first study.

Pavlovia is a hosting platform for studies created in various software (including PsychoPy/PsychoJS, jsPsych and lab JS). This guide will focus on experiments created in PsychoPy, which is the main use-case for Pavlovia.

PsychoPy allows for complex experiments to be created using a combination of a Graphic User Interface (“Builder view”, which requires minimal code) alongside inserted “Code Components” if required for additional flexibility. Code can be added in python, JavaScript or both. The software is sensitive enough to run psychophysical paradigms, with many options for stimulus and response.

What types of studies can be run?

PsychoPy and Pavlovia are mostly used by researchers creating behavioral paradigms in psychology, cognitive science, psycholinguistics, economics and other areas of behavioral science. In particular, PsychoPy is useful for creating behavioral experiments where participants are required to react to stimuli (e.g. images, movies, text) via key presses. However the range of response options also include mouse/touch screen responses, microphone recording (and voice transcription), webcam recording and typed responses.

Recording Prolific IDs

Using URL Parameters (Recommended)

When you get the URL for your experiment, you can pass information from Prolific (e.g. Prolific ID) to your experiment via “URL parameters”. Your experiment will then store the passed information to the data file (and can also pass this information on to any other links you redirect to afterwards!).

To get the recommended URL parameters on Prolific, simply paste your URL into the provided box on the study set-up page and select ‘I’ll use URL parameters’. Parameters to record Prolific ID, study ID, and session ID should then be automatically applied:

Using a question

Alternatively, you can set your study up to automatically request Prolific IDs upon start-up. To do this you can add fields to your experiment settings in your PsychoPy experiment, which will specify the parameters expected on start up.

Redirecting participants upon completion

Using a URL (Recommended)

In PsychoPy, you can add a completion URL to your study by selecting ‘Settings → Online → Completed URL’. When participants complete your study, they will be redirected to Prolific with the specified completion code.

You can also include a URL for if participants hit ‘escape’ and exit the study early (’Incomplete URL’). You may wish to use our custom completion codes feature in conjunction with this additional URL to distinguish participants who exit the study early from participants who complete it.

Manual copy-pasting

If you don’t want to include a redirection URL, you can instead simply display the completion code on the final screen of your experiment and ask participants to copy and paste it into Prolific.

This may be of use if you want to have more than 2 completion codes. When a participant fulfills a condition for a certain completion code (e.g., not consenting, failing checks), you can redirect them within the study to the relevant code.

When using manual completion codes, make sure to instruct your participants to complete your task once they have copied and pasted these codes (e.g., “Once you’ve copied the code, hit space to complete your submission”. This will ensure data is fully submitted back to your project.

Daisy-chaining with other software

PsychoPy can also be connected up fairly simply to other experimental software. This may be useful if you want to include a survey at the beginning or end of your study, or want to handle consent forms and demographics outside of PsychoPy.

To direct to another software from a PsychoPy experiment, you can include the relevant onward URL in the ‘Completed URL’ section. Similarly, the URL to a PsychoPy experiment can be included at the end of a different survey to direct to the experiment.

Credits and licenses

You can use Pavlovia either via an institutional license or a credit based system. This is the cost for use of the server, rather than the costs paid to your participants. Licenses and credits can be purchased from the Pavlovia store. If you are using a license, you do not need to assign credits to studies, and the below does not need considering.

If you are using a credit based system, it is important to understand how to assign credits to your study and how credits are reserved/consumed. When a participant starts your study, they will be assigned a credit. This credit will be used up either when they complete the study, or if they exit early and you choose to save incomplete responses. It’s up to you whether the credit will be consumed even if the participant doesn’t complete the study.

If you choose to allow incomplete responses to be saved, and the “Incomplete” redirect URL does not contain a Prolific completion code, this may lead to a mismatch between the number of spaces available on Prolific and the number of credits available on Pavlovia (i.e. participants have consumed credits despite not completing, so the space is still marked as “available” on Prolific). This could lead to participants starting the study on Prolific only to see a message that the study does not have sufficient credits. We highly recommend choosing not to save incomplete responses, or else making sure you have enough credits to cover additional participants.

Directing participants within your study (survey logic)

In PsychoPy, it’s possible to use small code snippets to direct participants within your survey. These snippets are short and easy to implement, meaning it’s possible to create studies with branches and conditions. For the purposes of integrating this software with Prolific, examples of common screening conditions will be given below.

Consent screening

In PsychoPy create three routines - one for your consent screen, one for the start of the study itself, and one for a goodbye message if the participant doesn’t consent.

Add loops around each of the outcome routines. This will allow the study to branch based on the participant’s response.

In the properties for each loop, set the ‘nReps’ to a named variable (e.g., TrialReps, NoConsentReps). This ensures that the number of times the routine will repeat is based on the value given to this variable. Attributing a value to the variable is done via a small code block on the consent routine.

On your consent routine, add a response input so participants can indicate whether they want to participate or not. This can be as simple as a keyboard input where ‘y’ = consent and ‘n’ = no consent.

The keypress will be recorded as ‘[NAME OF KEYBOARD INPUT].keys’ - in this case ‘consent_resp.keys’. For a consent form, we recommend reducing the number of allowed keys to just ‘y’ for consent and ‘n’ for non-consent.

Add a code block to the consent routine. The code block will set the value for the loop variables we added earlier, and so determine which loop the participant is sent to upon their keypress.

In the code snippet, you can define how each keypress affects each loop variable, so one response leads to one outcome and vice versa.

This code snippet tells the program to play the trial if the participant enters ‘y’, and to play the non-consent screen if the participant enters ‘n’.

Validating prescreeners

The setup for validating prescreeners is similar to the setup for getting consent. In this example, we will be defining separate variables for each prescreening validation question, and only allowing the participant to proceed to the study if they gave the correct answer to each.

In PsychoPy, create a routine for your study start, a goodbye message, and each of the prescreeners you want to validate. In this example, we’ll use three screening questions. There should also be loops around each of the outcome routines with the loop variables defined as described above.

In addition to these routines, we’ll need a routine that isn’t shown to participants, but is used to calculate the outcome based on the participant’s responses.

Like the consent screening above, each prescreening routine should include text asking participants the prescreening question, and a keyboard input so participants can respond. Each prescreening routine also needs to include a code block.

Within the code block for each prescreening question, we’ll need to define the variable for that prescreening question. If the participant provides the correct answer, that variable should be recorded as a 1, and if they provide the incorrect answer, the variable should be recorded as a 0.

After you’ve defined the variables for each of the prescreening questions, add a code snippet to the calculation routine. This code snippet will tell the program to play the trial only if the participant enters the correct answer to all questions, and to otherwise play the non-eligible goodbye screen.

Comprehension checks

In a fair comprehension check, the participant needs to be shown the question again if they fail the first time. If they fail twice in a row, they can be screened out, otherwise they should be allowed through.

In PsychoPy, set up a routine for your study start, and routine for your goodbye message, and two routines for the comprehension check. There should be loops around all routines except the first comprehension check, with the loop variables defined appropriately.

Set up each comprehension check routine to include text for the check, a keyboard response input, and a code snippet.

In the code snippet for the first comprehension check routine, we’ll need to define the loop variables such that a participant gets directed straight to the trial if they get the question right, and otherwise gets directed to the second comprehension check routine.

In the code snippet for the second comprehension check routine, we’ll need to define the loop variables such that a participant gets directed to the trial if they get the question right, and otherwise gets directed to the goodbye message.

Need further help?
Click here to contact us