Wiki-admin at 09:36, 11 February 2025

2025-02-11T09:36:31Z

Wiki-admin: Created page with "== Datahandler Script == === Introduction === The data handler script is designed to facilitate the upload of data to the Radcloud upload API endpoint. This script streamline..."

2025-02-11T09:26:41Z

Created page with "== Datahandler Script == === Introduction === The data handler script is designed to facilitate the upload of data to the Radcloud upload API endpoint. This script streamline..."

New page

== 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: [https://gitlab.socsci.ru.nl/tsg/radcloud-datahandler Data handler in GitLab]

Packaged versions of the script can be downloaded with tag 'Generic' from the [https://gitlab.socsci.ru.nl/tsg/radcloud-datahandler/-/packages/ datahandler GitLab package registry].

=== Implementation Examples ===
Example projects that show how you can integrate the data handler into your project:
* [https://gitlab.socsci.ru.nl/tsg/jspsych-radcloud-simple-example JsPsych radcloud example: I want the simplest possible setup]
* [https://gitlab.socsci.ru.nl/tsg/jspsych-radcloud-esmodule 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.

# Go to the following page: [https://www.socsci.ru.nl/tsg/radcloud-datahandler/]
# Copy the link of the version you want (latest or another pinned version).
# Include the following line in your <code>index.html</code> file pointing to the socsci hosted URL.
<pre>
<script src="https://www.socsci.ru.nl/tsg/radcloud-datahandler/1.5.7/datahandler.1.5.7.js"></script>
</pre>
Call the function from JavaScript:
<pre>
datahandler.saveData(radcloudApiKey, ppn, mydata);
</pre>
'''Note:''' Example project: [https://gitlab.socsci.ru.nl/tsg/jspsych-radcloud-simple-example 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.

# Login to GitLab and go to: [https://gitlab.socsci.ru.nl/tsg/radcloud-datahandler/-/packages]
# Get the latest version of the datahandler by downloading the file under 'datahandler - Generic'.
# Add the script to your JavaScript project.
# Include the following line in your <code>index.html</code> file pointing to the file:
<pre>
<script src="datahandler.1.5.7.js"></script>
</pre>
Call the function from JavaScript:
<pre>
datahandler.saveData(radcloudApiKey, ppn, mydata);
</pre>
'''Note:''' Example project: [https://gitlab.socsci.ru.nl/tsg/jspsych-radcloud-example 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.
<pre>
echo @tsg:registry=https://gitlab.socsci.ru.nl/api/v4/projects/2989/packages/npm/ >> .npmrc
npm i @tsg/datahandler
</pre>
Which installs the latest version of the datahandler.
Follow up by adding the following import to your ES code:
<pre>
import {saveData} from '@tsg/datahandler';
saveData(radcloudApiKey, ppn, mydata);
</pre>
'''Note:''' Example project: [https://gitlab.socsci.ru.nl/tsg/jspsych-radcloud-esmodule JsPsych radcloud example: I want to use modern JavaScript tooling]

== Save Data Parameters ==
The datahandler script accepts three parameters.
<pre>
datahandler.saveData(radcloudApiKey, ppn, mydata);
</pre>
# '''api_key''': String containing the API key from your Radcloud experiment.
# '''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'''.
# '''data''': The JavaScript object containing the data.
Example JSON object:
<pre>
let mydata = {
"data": {
"id": "801744",
"experiment_id": "1176",
"number": 2,
"responseTime": null,
"buttonResponse": null,
"buttonPressed": 2,
"stimulus": "stimuli/image/unlock.jpg"
}
};
</pre>

== Response ==
A successful call to the upload endpoint will return the following response.
It means your task is scheduled and will be processed soon.
[[File:screenshot11111.png]]

=== Handling the Response in Your Code ===
<pre>
datahandler.saveData(radcloudApiKey, mydata.ppn, mydata)
.then(response => {
if (!response.ok) {
message = `Warning: failed saving data (${response.message})`;
}
});
</pre>

== JsPsych Radcloud Example ==
Git checkout project: [https://gitlab.socsci.ru.nl/tsg/jspsych-radcloud-example JsPsych radcloud example]

== Migrating from Radcloud-mini ==
# Create a new experiment in Radcloud.
# Copy the new experiment API key into your script.
# Add the latest datahandler script to your experiment codebase.
# Modify the calls from <code>saveData(</code> into <code>datahandler.saveData(</code>.
# 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.

@@ Line 95: / Line 95: @@
 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 ===

Radcloud Datahandler script - Revision history

Wiki-admin at 09:36, 11 February 2025

Wiki-admin: Created page with "== Datahandler Script == === Introduction === The data handler script is designed to facilitate the upload of data to the Radcloud upload API endpoint. This script streamline..."