Why Linking Platforms in Online Research is Important

Online studies often require the use of multiple platforms. For example, SONA may be used for participant recruitment and credit assignment, Qualtrics may be used for multiple surveys, and OpenSesame/JATOS may be used for an experimental task. One important problem for such studies is how to transmit important parameters between the different platforms. For example, it is often necessary to share and store a common participant identifier across all stages of the online study. In this tutorial, we will walk you through an example of how such linking between platforms can be accomplished using so-called query strings. 

The Basics

Most online experiment platforms have the capacity to receive and send information via the URL using so-called query strings. Query strings are added to the end of the URL and contain information about different parameters and their values.

In Figure 1, you can find examples of query strings. Query strings are initiated by a ?, followed by some variable_name, which in turn is followed by an = sign and its specific variable_value. The & sign can be appended to add further parameters.

 In general, linking different platforms in an online study requires three steps:

1. Receiving query strings from preceding part
2. If necessary, storing the query parameters in the data
3. Sending query strings to the next part

In the next section, we will demonstrate in detail how to link different online experiment platforms in such a way. Specifically, we will walk you through a typical sample experiment consisting of a) participant recruitment on SONA, b) information letter, informed consent, and screening on Qualtrics, c) an experimental task created in OpenSesame and hosted on JATOS, d) debriefing on Qualtrics, and e) automatic credit assignment on SONA (see Figure 2).

Tutorial: Linking Different Platforms in a Typical Online Study

0. Prerequistes

In this tutorial we assume that you are already familiar with the basics of creating studies on SONA, designing surveys on Qualtrics, and building online experimental tasks in OpenSesame and hosting them on JATOS. If you are not familiar with these steps, we recommend to take a look at the respective wiki pages.

1. SONA → Qualtrics

Entering the Study URL in SONA

When adding a new online study to SONA, we are asked to provide a Study URL in the Advanced Settings section (see Figure 3).

Here, we need to enter the URL of the first part of your experiment. This is where the participant will be redirected to when clicking the link to participate in our study in SONA.

In our example, the first part of the study is an information letter and a screening questionnaire on Qualtrics. Importantly, it is necessary to send the unique participant ID generated by SONA to the next platform. To do so, you need to add a query string to the end of the URL. To do so, we will add the string ?id=%SURVEY_CODE% to the end of the URL. The ? indicates that the query string begins, id is what we call the parameter, and %SURVEY_CODE% is the value of the id parameter. We set the id parameter to %SURVEY_CODE% because SONA will automatically replace this value with the unique participant ID of the respective participant (see Figure 4). 
 

→    

Now, when a participant clicks on the online study link on SONA, they will be redirected to the next Qualtrics survey and their unique SONA ID will be send as a query string in the URL.

Storing query parameters in Qualtrics

To make use of the parameters that were sent from SONA via the query string in the URL they need to be stored in our Qualtrics survey. To do so, we need to follow these steps (see Figure 5):

1. Go to Survey Flow
2. Add Set Embedded Data element and move it to the beginning of the survey
3. Click Add a New Field
4. Name the parameter the same as its name in the URL (for example “id”)
5. Leave the value as the default Value will be set from Panel or URL
6. Apply the changes

Next, we would like to check whether the query parameter has been imported successfully. For this, we add a Text/Graphic element to our Qualtrics survey and add the piped text referring to the imported parameter (Figure 6). Now, when testing our study with the sample link on SONA, see that the query parameter related to the SONA ID has been imported successfully (Figure 7).

2. Qualtrics → OpenSesame/JATOS

After reading the information letter and filling in the screening questionnaire, we want to redirect the participants to an OpenSesame experiment hosted on JATOS. For this, we need send information that is stored in the Qualtrics survey to the next platform using query strings.

Sending parameters from Qualtrics via query strings

After the participants have finished the initial Qualtrics survey, we want to redirect them and send information to an OpenSesame experimental task hosted on a JATOS server. In our example, we will limit ourselves to sending the unique SONA ID and another unique response ID generated by the Qualtrics survey. However, if needed any information from the Qualtrics survey (for example the response to a certain question) can be sent via query strings in the URL.

To send information through query parameters in Qualtrics, we again need to follow a couple of steps (see Figure 8):

1. Write down the link to next part of your study (in our example, an OpenSesame experiment hosted on JATOS) into a text editing application (e.g. Word)
2. Add the end of the URL, add the query parameters: ?id=${e://Field/id}&qualtrics_id=${e://Field/ResponseID}
   • ? indicates that a query string begins
   • id= ${e://Field/id} sets the id parameter to the stored SONA ID. The piped text of the parameter ensures that the value will be dynamically adjusted to the current participant.
   • & separates different parameters
   • qualtrics_id=${e://Field/ResponseID} sets the qualtrics_id parameter to the unique Qualtrics ID value associated with the current participant.
3. Additional parameters related to, for example, responses can be added by adding another parameter and the piped text of the specific response.
4. Copy the URL 
5. Open your Qualtrics survey and add an End of Survey element in Survey Flow tab
6. Click Customize
7. Select Redirect to a URL…
8. Paste the URL into the text box

3. OpenSesame/JATOS → Qualtrics

Next, we would like to store the query parameters in our JATOS-hosted OpenSesame experiment and upon completion send information from OpenSesame via query parameters to the next part of the study.

Storing query parameters in OpenSesame/JATOS

To import and store parameters and their values from the query string to OpenSesame, we need to add an inline_javascript element at the start of the experiment (see Figure 9).

In our example, we would like to store both the participant’s SONA ID and their Qualtrics response ID. To do so, we enter the following JavaScript code in the Prepare tab.

This code chunk does a couple of things.

In the first line, we check if the experiment is currently run using JATOS (window.jatos) and whether the query parameter of interest is defined (jatos.urlQueryParameters.id). If this is the case, we create an OpenSesame variable called sona_id and assign it the respective value from the query string (vars.sona_id = jatos.urlQueryParameters.id).

If we are not running the experiment using JATOS or if the query parameter is not defined, the variable is instead set to “-1”. This is repeated for all other query parameters that you want to import.

We then repeat this process for the Qualtrics response ID parameter.

To test whether the query parameters were imported correctly, we add a sketchpad item after the inline_javascript we just added. We select the Draw textline element and write references to both imported variables onto the sketchpad (see Figure 10).

Sending parameters from OpenSesame/JATOS via query strings

Next, we would like for OpenSesame to redirect the participant to the next part of the only study and to send some  information via the query string in the URL. In our example, the participant is redirected to Qualtrics for a debriefing. For this, we need to add another inline_javascript at the end of the experiment(see Figure 11).

In the Run tab, we add the following code.

The jatos.endStudyAndRedirect() function terminates the experiment and redirects the participant to the URL string entered as an argument in the brackets. In our example, we enter the URL of the Qualtrics debriefing, and add the SONA ID and the Qualtrics Response ID as query parameters, named id and qualtrics_id respectively. To ensure that the values of these parameters are adjusted dynamically, we use template literals. The URL string is enclosed by backticks (`) and query parameter values are referred to using the following syntax: ${vars.os_variable_name}. This way, the query parameter will take on the value of the variable stored in the OpenSesame experiment.

4. Qualtrics → SONA

Lastly, we want to store the information received in the query string from OpenSesame/JATOS in the Qualtrics debriefing and then redirect the participant to SONA to automatically receive their credits for the study. To store parameters from the query string in Qualtrics, we use the same process as outlined in Step 1.

To redirect the participant to the automatic SONA credit assignment, we again add an End of Study element to the survey. In the Redirect to a URL… box, we now enter the URL that will lead to automatic credit assignment on SONA. This URL can be found in the Study Information on SONA in a box titled Qualtrics Redirect to a URL (see Figure 12).

In our example, the URL is https://ul.sona-systems.com/webstudy_credit.aspx?experiment_id=3316
&credit_token=d2c338673ff94881bc18e6e3ccecdcd6&survey_code=${e://Field/id}. In order to identify the participant, SONA uses the survey_code query parameter highlighted in the URL. By default, SONA assumes that the unique SONA participant ID is stored in the Qualtrics survey as an embedded data point called id. If you chose a different name for the SONA participant ID, you will have to adjust the piped string in the URL accordingly.

5. Testing Your Online Study

Lastly, we want to test that all parts of our online study are indeed linked properly. To do so, we click the Sample Link with Embedded ID Code button on the SONA page of the experiment of our researcher account (see Figure 13).  

However, when using this testing method we will receive an error when we reach the automatic credit assignment in SONA. The reason for this is that the study was not completed through a participant account.

Thus, to check whether the credit assignment is working, we can alternatively create a timeslot with an invitation code. To do so, we go to the SONA page of our study and click the Change Study Information  button in the Study Menu. Next, we enter an Invitation Code so that no other SONA user accidently uses our timeslot. Then, we change the Study URL Display and the Can a participant sign up for this study more than once? options both to Yes. This is done to ensure easier testing of the online study (see Figure 14).

After creating a timeslot, you can log into your participant account and to test all parts of the online experiment, including automatic credit assignment.