lab.js Integration

Overview

Open Lab integrates seamlessly with lab.js, a powerful tool for building interactive online experiments and surveys. This integration allows researchers to create complex tasks in the lab.js builder, export them as JSON files, and incorporate them into the Open Lab Study Builder. Once integrated, these tasks become part of your study flow, enabling participants to complete them via web browsers. lab.js supports a wide range of experiment types, from simple surveys to advanced cognitive tasks with randomization and branching.

To get started with lab.js, visit the official website at https://lab.js.org/ for tutorials and examples. In Open Lab, lab.js tasks are added as components in the Study Builder, where you can preview them, incorporate them into flows with randomization (e.g., between-subjects designs), and collect data securely. Data from lab.js tasks is stored encrypted and can be visualized in real-time dashboards.

There are two primary ways to bring a lab.js task into the Open Lab platform: (1) using the lab.js builder interface to create and directly export the task, which automatically creates a new task entry in Open Lab, or (2) exporting the task as a JSON file from lab.js and manually uploading it either when building a study or in the "My Tasks" area of Open Lab. Both methods ensure compatibility, but the direct export simplifies the workflow by handling the upload automatically.

Prerequisites

Before integrating lab.js with Open Lab:

• Have a lab.js account or use the free builder at https://lab.js.org/builder.
• Ensure your experiment is complete and tested in lab.js, including any media files or custom scripts.
• In Open Lab, create a study and navigate to the Study Builder, or go to the "My Tasks" section in the dashboard.
• Familiarize yourself with lab.js export options, as Open Lab requires the JSON format for tasks.

Method 1: Direct Export from lab.js Builder

The lab.js builder provides a direct export option to Open Lab, which streamlines the process by creating a new task entry in your Open Lab account without manual file handling. This method is ideal for quick integration and ensures the task is immediately available in your "My Tasks" list.

1. Open the lab.js builder and design your task or survey using components like screens, sequences, loops, and interactive elements such as response collection or conditional branching.
2. Test the experiment locally in your browser to verify functionality, timing, and data output.
3. In the builder's export menu, select the option to export directly to Open Lab. You'll need to authenticate with your Open Lab credentials if not already linked.
4. Provide a name and description for the task during export. lab.js will handle the upload, creating a new task in Open Lab's "My Tasks" section.
5. Once exported, the task appears in Open Lab, ready to be added to any study flow in the Study Builder.

This direct method saves time by automating the JSON export and upload, ensuring compatibility and reducing errors. After export, you can edit the task details in Open Lab if needed.

Method 2: Manual JSON Upload in Open Lab

If you prefer to handle the export manually or need to upload existing JSON files, you can do so directly in Open Lab. This method gives you flexibility to upload tasks either while building a study or in the dedicated "My Tasks" area for reuse across studies.

1. Create and test your experiment in the lab.js builder as described in Method 1.
2. Export the study as a JSON file from the lab.js export menu and save it to your computer.
3. In Open Lab, navigate to the Study Builder for a specific study or go to the "My Tasks" section in the researcher dashboard.
4. When adding a "Lab.js Task" component in the Study Builder, or creating a new task in "My Tasks," select the option to upload the JSON file.
5. Provide a name and description for the task, then submit. The task will be processed and added to your library or study flow.

This manual method is useful for importing pre-existing lab.js files or when direct export isn't available. Uploaded tasks can be previewed and edited in Open Lab.

How Your Data Reaches Open Lab

Open Lab attaches data transmission to your task for you. You do not need to add anything to your script to make saving work — upload the task and the platform handles the rest.

You do not need the “Data transmission” component

The lab.js builder offers a Data transmission (beta) component, and its description mentions Open Lab among the backends it supports. That component exists for studies you host yourself. On Open Lab it is redundant: the platform already transmits your data when the study ends, so including it sends the whole dataset twice for every participant.

Open Lab now stores only the more complete of the two, so an existing study that uses it is not losing anything. But it doubles the upload each participant makes, and there is no reason to keep it — if your task has one, you can delete it.

Your experiment must reach its end

The complete dataset is sent when the study ends. That means the last component has to have some way to finish. Any of these will do:

• a response — for example a button the participant clicks to continue
• a timeout, so the component ends on its own after a set duration
• a call to this.end() in a script attached to the component

A final screen with none of these never finishes. The study stays open on that screen, the complete dataset is never sent, and the participant is never marked as having completed the study. In the lab.js builder preview you can check this: when an experiment ends, a Download button slides in from the top. If it never appears, your experiment is not ending.

Partial data during the session, complete data at the end

While a participant works through your task, lab.js sends partial data to the server whenever there is a pause of a few seconds. These arrive as incremental datasets and each one carries only the rows recorded since the last send. When the study ends, the full dataset for the whole session is sent in one piece.

So if a study never ends, you are left with only the incremental pieces and the tail of the session is missing.

Careful: seeing “full” data does not prove your experiment ended. If your task contains a Data transmission component, that component sends a full dataset of its own partway through — so a study that never reaches its end can still show full data in your data table and look perfectly healthy. The reliable check is your Participants page: if data is arriving but participants are not being marked Completed, your experiment is not ending.

Passing URL Parameters into a Task

You can pass values into a study from the outside — a between-subjects condition, a panel provider's respondent ID, a recruitment source — by appending query parameters to the study link. This is the usual way to hand a task information that Open Lab does not assign itself, such as a condition an external panel has already allocated. Distribute the study link with your own parameters appended, written exactly as you would expect:

https://app.open-lab.online/studies/A2ZVJ?Set=A

Reading a parameter inside the task

Open Lab makes every parameter from the study link available to your task as a lab.js parameter, under the same name you used in the link. A link ending ?Set=A is readable inside the task as this.parameters.Set, and in any place lab.js accepts a placeholder — a screen's content, a condition on a component, a loop template — as ${parameters.Set}. No script is required:

// Anywhere in the task — for example, a Script on before:prepare
const set = this.parameters.Set;   // 'A'

// Or, with no scripting at all, in any content field:
//   Welcome to condition ${parameters.Set}

This works the same way on every kind of study link, including invitation links, because the value is captured when the participant arrives rather than read back out of the address bar later.

The same mechanism carries the platform's own assignments, which use a reserved openlab_ prefix: openlab_condition from built-in branching (or openlab_condition_1, openlab_condition_2, and so on when you have several factors), and openlab_group_code from groups.

Two rules decide what wins when names collide. A link parameter overrides a parameter of the same name declared in the task itself, which is what lets you use the task's own value as a default and the link to change it. But the platform's own assignments always win over the link, and a link parameter whose name begins with openlab_ is ignored entirely — participants cannot put themselves in a condition or a group by editing the URL.

Reading the raw URL instead

You rarely need this now, but the parameters are also visible in the address bar, and older studies often read them there. The task runs directly in the participant's page — it is not embedded in an iframe — so window.location.search is readable in the ordinary way. One thing surprises people: on the way in, Open Lab adds an lp_ prefix (for "link parameter") to each name so your parameters cannot collide with its own. So you write ?Set=A in the link, but the address bar shows lp_Set — do not add the prefix yourself, or it will arrive as lp_lp_Set.

// Script component, event: before:prepare
const params = new URLSearchParams(window.location.search);
const set = params.get('lp_Set');   // 'A', or null if absent

Prefer this.parameters.Set where you can — it is shorter, it needs no prefix, and it does not depend on the address bar. That said, reading the URL works on every kind of study link. Invitation links carry a single-use invitationId, which Open Lab removes from the address bar once it has been redeemed so that a refresh or a forwarded link cannot redeem it a second time. Your own parameters are left in place.

If a script of yours produces no output at all — not even a console.log — the problem is almost never the parameters. It usually means the script is not attached to the component you think it is, or is on a different event. Confirm the script is saved on the task in the builder, and use the Study Builder's Test run to check it fires.

Where the values are stored

Link parameters reach your data whether or not the task ever refers to them. They are saved to the participant record under the same names you used in the link, and are available in three places:

• On the study's Participants page, click Columns and enable the parameter under Custom parameters. Open Lab lists one entry per parameter name it has seen, so a column only appears once at least one participant has arrived carrying it.
• In your data exports and reports, alongside the rest of the participant's data.
• In a Redirect component, where you can forward a value on to an external service — useful for returning a panel provider's respondent ID at the end of the study. In the Study Builder's redirect editor, choose the parameter as the source for an outgoing query parameter. For the full round trip with a specific provider, see Recruitment integrations — Sona, Prolific, CloudResearch, MTurk and lab recruitment systems.

If you only need a random split, you do not need URL parameters at all. The built-in condition randomization in the Study Builder assigns and balances participants for you and injects the result into this.parameters with no scripting. Reach for URL parameters when the assignment is made outside Open Lab; reach for built-in randomization when Open Lab should make it.

Advanced Features

Open Lab supports advanced lab.js features like randomization in between-subjects designs via branching components. Data from lab.js tasks is automatically collected and can be analyzed in real-time dashboards. For custom setups, ensure your lab.js experiment handles data saving correctly for Open Lab's backend.

Test run: After adding a lab.js task to a study, use the Study Builder's Test run feature (the beaker icon on a task) to auto-play the task and catch mechanical errors — failing to load, JavaScript errors, dead-ends, or no data — before inviting participants.

Tips: Use lab.js's data exchange configuration for seamless integration. If issues arise, check the lab.js documentation for troubleshooting export and compatibility details.

Next Steps

With lab.js integrated, explore the following sections to build and manage your studies on the Open Lab platform:

• Study Setup

  • Study Builder: Design study flows, upload lab.js JSON files for tasks and surveys.
  • Study Management: Learn how to create, edit, and publish studies.

• Data

  • Data Analysis: Build visualizations to analyze study data.