Radcloud Datahandler script

Datahandler Script

Introduction

The data handler script is designed to facilitate the upload of data to the Radcloud upload API endpoint. This script streamlines the process of transferring data from local systems to the remote server, ensuring that the data is accurately and efficiently uploaded to the intended API endpoint.

This page demonstrates the data handler script usage with an example.

Resources

The Data handler code is available in SocSci GitLab:  Data handler in GitLab

Packaged versions of the script can be downloaded with tag 'Generic' from the  datahandler GitLab package registry.

Implementation Examples

Example projects that show how you can integrate the data handler into your project:

•  JsPsych radcloud example: I want the simplest possible setup
•  JsPsych radcloud example: I want to use modern JavaScript tooling

Choose Your Own Setup

Download the datahandler script and make it part of your project. There are three different ways that you can add the Datahandler to your project. Which approach you choose will depend on what your goals are.

I Want the Simplest Possible Setup

You do not need to install anything to start using the datahandler. For most experiments, this approach will be sufficient.

1. Go to the following page:  /tsg/radcloud-datahandler
2. Copy the link of the version you want (latest or another pinned version).
3. Include the following line in your index.html file pointing to the socsci hosted URL.

<script src="https://www.socsci.ru.nl/tsg/radcloud-datahandler/1.5.7/datahandler.1.5.7.js"></script>

Call the function from JavaScript:

datahandler.saveData(radcloudApiKey, ppn, mydata);

Note: Example project:  JsPsych radcloud example: I want the simplest possible setup

I Want to Download the Script and Host It with My Experiment

This approach involves using scripts that you can download from Socsci GitLab.

1. Login to GitLab and go to:  tsg/radcloud-datahandler/-/packages
2. Get the latest version of the datahandler by downloading the file under 'datahandler - Generic'.
3. Add the script to your JavaScript project.
4. Include the following line in your index.html file pointing to the file:

<script src="datahandler.1.5.7.js"></script>

Call the function from JavaScript:

datahandler.saveData(radcloudApiKey, ppn, mydata);

Note: Example project:  JsPsych radcloud example

I Want to Use Modern JavaScript Tooling

Tooling like npm and import statements. You can install the datahandler from Socsci GitLab package registry. This approach allows you to integrate the datahandler into your favorite JavaScript frameworks.

echo @tsg:registry=https://gitlab.socsci.ru.nl/api/v4/projects/2989/packages/npm/ >> .npmrc
npm i @tsg/datahandler

Which installs the latest version of the datahandler. Follow up by adding the following import to your ES code:

import {saveData} from '@tsg/datahandler';
saveData(radcloudApiKey, ppn, mydata);

Note: Example project:  JsPsych radcloud example: I want to use modern JavaScript tooling

Save Data Parameters

The datahandler script accepts three parameters.

datahandler.saveData(radcloudApiKey, ppn, mydata);

1. api_key: String containing the API key from your Radcloud experiment.
2. ppn: The participant number as a string. If not supplied, the save will continue, and data will be added to your experiment under participant 0.
3. data: The JavaScript object containing the data.

Example JSON object:

let mydata = {
    "data": {
        "id": "801744",
        "experiment_id": "1176",
        "number": 2,
        "responseTime": null,
        "buttonResponse": null,
        "buttonPressed": 2,
        "stimulus": "stimuli/image/unlock.jpg"
    }
};

Response

A successful call to the upload endpoint will return the following response. It means your task is scheduled and will be processed soon.

Handling the Response in Your Code

datahandler.saveData(radcloudApiKey, mydata.ppn, mydata)
    .then(response => {
        if (!response.ok) {
            message = `Warning: failed saving data (${response.message})`;
        }
    });

JsPsych Radcloud Example

Git checkout project:  JsPsych radcloud example

Migrating from Radcloud-mini

1. Create a new experiment in Radcloud.
2. Copy the new experiment API key into your script.
3. Add the latest datahandler script to your experiment codebase.
4. Modify the calls from saveData( into datahandler.saveData(.
5. Check the response handling and ensure proper error checking.

Warning: Data migration from radcloud-mini to radcloud is not supported.

Support

If you have any questions, suggestions, or feedback, please feel free to reach out to us via email at tsg@ru.nl. We'd love to hear from you and are always open to improving this project based on your input.