Terracotta jsPsych Integration Guide

Overview

Terracotta provides a flexible LTI (Learning Tools Interoperability) integration that allows jsPsych experiments to be embedded within learning management system (LMS) assignments. This guide explains how to create a jsPsych experiment that can be seamlessly integrated with Terracotta into the LMS. 

⚠️ Terracotta does not share students’ names or identities with custom web activities. Instead, Terracotta sends an anonymous identifier to jsPsych that can be used to connect jsPsych data to additional details about the student in Terracotta. If students will be asked to provide their name or any other personally identifiable information in the jsPsych experiment, make sure you have permission from your school. 

Responsibilities of the jsPsych Experiment

When a jsPsych experiment is integrated in Terracotta as an LMS assignment, your activity is responsible for supporting student learning and reliably returning students’ scores back to the LMS. The jsPsych experiment must comply with Terracotta’s Terms of Use, and the jsPsych activity is also responsible for presenting an interface that is accessible to diverse learners. Before integrating a jsPsych experiment, ensure the following:

• The designer of the experiment should be familiar with web accessibility standards, and the jsPsych plugin should be screened for any accessibility issues (e.g., using the free WAVE Evaluation Tool).

• When used for graded assessments, the correct answers should not be visible in the activity’s source code. If possible, utilize server-side scoring and validation.

• If the custom web activity utilizes generative AI, honor the EDSAFE AI Alliance’s SAFE Benchmarks. In particular, provide learners with the means to flag inappropriate content, and create a process for handling any such situations.

• All information collected by the jsPsych experiment is private and secure.

Configuration in Terracotta

To configure a jsPsych experiment in Terracotta, begin by creating a new experiment. Add a new assignment. For the treatment that will integrate with the jsPsych experiment, select External Integrations > Custom Web Activity, then you'll see the interface below: 

Open

In Box 1 (Launch to Custom Web Activity), provide the URL to the custom web activity. Once you provide the URL, you can preview your activity in a new tab. Indicate the maximum numeric score that students can earn in the web activity. Check the checkbox if the custom web activity is configured to allow students to view past submissions (this is an advanced feature; if you are unsure, leave this box unchecked). When Terracotta launches to your jsPsych experiment, it will append a set of launch parameters onto the URL you provided (listed below). 

In Box 2 (Return to Terracotta), you are provided with a return URL. Your jsPsych experiment should redirect users to this return URL, and Terracotta expects that jsPsych will append two URL parameters: (1) launch_token, and (2) score. If “score” is omitted, Terracotta will assume that the submission will receive the maximum score.  

Launch Parameters

The following variables are automatically provided to the custom web activity as URL parameters: 

• launch_token: A single-use token for launch validation and score return. The launch token is in UUIDv4 format.  

• anonymous_id: Anonymized student identifier. This ID matches Terracotta’s participant_id, however, depending on the configuration in Terracotta, students who access a custom web activity may not be consenting participants. Thus, we use the label anonymous_id to refer to students accessing custom web activities. 

• assignment_id: Unique identifier for the Canvas assignment 

• submission_id: Unique identifier for the current submission attempt 

• condition_name: Experimental condition name  

• experiment_id: Unique identifier for the experiment (specific to the course) 

• due_at: Assignment due date and time 

• remaining_attempts: Number of remaining submission attempts. If there are unlimited attempts available to the student, remaining_attempts = u.

Return to Terracotta

Terracotta expects that when a student completes the activity, they will be redirected to the URL:
     https://app.terracotta.education/integrations 
with two parameters appended to the URL: (1) launch_token, and (2) score. If “score” is omitted, Terracotta will assume that the submission will receive the maximum score.  

Terracotta will not accept a score for a launch token that has already been used.  

Best Practices

• Record Granular Data: Your custom web activity will be responsible for a legitimate academic exercise, and it should keep records of users’ interactions, responses, and submissions. By doing so, your custom web activity will help ensure the integrity of students’ coursework.  

• Check if the Launch Token has Previously Been Used: When configuring a custom web activity in Terracotta, there is a checkbox: Tool allows students to view past submissions. If this box is checked, Terracotta will assume that the tool is able to display a past submission to a student. In this situation, if the external webpage receives a launch token that has previously been used, this indicates that a student is attempting to review their responses from a past submission. Check if the launch token has previously been used, and that the anonymous_id and assignment_id of the current launch matches the anonymous_id and assignment_id of the past submission associated with the launch_token. If so, the external page should display the data from the past submission associated with the provided launch token, with no interactivity.  

  • NOTE: There is a reserved launch_token: "00000000-0000-4000-B000-000000000000". This launch token is issued by Terracotta when previewing a custom web activity. 

• Communicate When There are Limited Remaining Attempts: When the teacher has placed restrictions on the number of attempts that a student may submit in response to an assignment, it may be helpful for the custom web activity to communicate this to the student (e.g., if there is only 1 attempt remaining). If there are unlimited attempts available to the student, remaining_attempts = u. A custom web activity will never need to handle a situation where remaining_attempts = 0, because in this situation, Terracotta will not generate a launch_token and will not launch the student into an activity. 

• Respect Due Dates: Consider warning users when they are accessing the webpage after the due date. Submissions made after the due date will be delivered into Canvas, but will be flagged as late. 

• Score Calculation: The custom web activity is responsible for determining the student’s score on the activity, which should be returned to Terracotta as a URL parameter value with the name “score.” 

A Minimal Example

Here is a minimal example of a jsPsych experiment that will integrate with Terracotta:

https://github.com/terracotta-education/terracotta-external-integrations/blob/main/jspsych_example.html

This example implements a (very short!) visual n-back task, and upon completion, displays the results to the user, with a final button to send credit back to the LMS gradebook.

In the <head> of the HTML file, load the jsPsych library, the two plugins necessary for the experimental task (html-keyboard-response & html-button-response), and the jsPsych stylesheet.

The <body> of the HTML file should be empty, as is typical when using jsPsych.

Then, contained within <script></script> tags, collect the launch_token and the anonymous_id from URL parameters.

Initialize jsPsych. This also establishes that when the experiment is finished, jsPsych will redirect the user back to Terracotta, with the launch_token that was received in the URL parameters, and with score = 1.

Add the participant_id and the launch_token to the jsPsych data structure:

Setup the study by setting session variables:

Push instructions into the jsPsych timeline:

Create the n-back trial, and populate the timeline with a sequence of n-back trials.

Create a final trial that will display feedback to the participant

Finally, run the timeline