Open Admin Panel

Run your first study

Three moving parts: set up the study procedure, integrate the logging library into your prototype, and connect your questionnaires. Here is the short version, with sample files to import.

1 · Set up a study

Open the Admin Panel and create a study. A setup wizard collects general information (name, dates, consent, planned number of participants), then lets you build the procedure interactively.

Create the study & procedure

Add steps to the procedure. Each step is one of: a text page (briefing / consent / thank-you), a questionnaire, a prototype condition, a pause, or a block that groups steps.

Counterbalance where needed

Put conditions inside a block and mark them for counterbalancing, and StudyAlign randomises their order across participants. That is how a within-subject A/B comparison is built.

Share participant links

Once the study is live, share the participant links. The Study Frontend guides each participant through the procedure, one controlled step at a time.

Skip the blank page. Import one of the ready-made study schemas below, then adjust the survey/prototype URLs, dates and copy to your needs. In the Admin Panel use Import Study and drop the file or paste its contents.

JSON Exploratory studySingle-group session: welcome → demographics → one condition → feedback JSON Comparative A/B studyWithin-subject: a counterbalanced block with Variant A & B

2 · Integrate the library into your prototype

Your prototype logs interactions through study-align-lib, published on npm. It reads the study, condition and participant parameters from the URL (study_id, condition_id, logger_key, participant_token), then logs native browser events (mouse, keyboard, touch) and custom data, either sent directly or buffered locally and flushed in bulk. Without a logger_key it logs to the browser console instead, so a prototype still runs standalone.

Install it once, then point it at your backend (the examples read the URL from VITE_STUDY_ALIGN_URL):

npm install study-align-lib

React prototypes

Wrap the library in a small useLogger hook that reads the URL parameters and returns your logging helpers, then pass log down to the components that record interactions:

// studyalign/useLogger.js
import StudyAlignLib from "study-align-lib";
// reads study_id / condition_id / logger_key / participant_token from the URL
// and returns { isReady, log, transmit, proceed }

// App.jsx
const { isReady, log, transmit, proceed } = useLogger(STUDY_ALIGN_URL);

useEffect(() => {
  if (isReady) log(LoggerEvents.USER_AGENT, navigator.userAgent);
}, [isReady, log]);

<QuillEditor log={log} />

// inside the editor component
editor.on("text-change", (delta, _old, source) =>
  log(LoggerEvents.EDITOR_TEXT_CHANGE, { delta, source })
);
button.onClick = (e) => log(LoggerEvents.MOUSE_CLICK, e, { meta: "data" });

Vanilla JavaScript prototypes

Import the same package (bundled with Vite or your tool of choice) and build a logger with a factory that mirrors the hook. Log directly, or buffer events and transmit them in chunks:

import { createLogger, LoggerEvents, TransmitterEvents } from "./logger";

const logger = createLogger(STUDY_ALIGN_URL);

// log a click directly
root.addEventListener("click", (e) => logger.log(LoggerEvents.MOUSE_CLICK, e));

// buffer keydowns locally, then flush them in bulk
root.addEventListener("keydown", (e) =>
  logger.log(LoggerEvents.BULK_KEY_DOWN, e, { text: editor.getText() })
);
await logger.transmit(TransmitterEvents.TRANSMIT_KEY_BULK);

// mark the condition done so the participant can proceed
logger.proceed();

Two full, runnable demos live in the app-examples repository: a React + Vite app and a vanilla JS + Vite app. Both wrap a Quill rich-text editor, log clicks, keystrokes and editor text and selection changes, and echo every interaction to the console so you can watch it live. Open an app through a StudyAlign study, or append the URL parameters by hand, to record to a backend.

3 · Make your surveys ready

Questionnaires are built right into StudyAlign. The native questionnaire builder lets you assemble a survey from single- and multiple-choice, rating, scale and free-text items, then embed it directly as a questionnaire step, no separate account or external service required.

To skip the blank page, start from a template of a standardized questionnaire and adapt the wording to your study:

SUS System Usability ScaleThe classic 10-item usability questionnaire
TLX NASA-TLXTask Load Index, perceived workload
UEQ UEQUser Experience Questionnaire
New Blank questionnaireAn empty scaffold to build your own from scratch

SoonReady-made Qualtrics templates for these questionnaires are coming soon.

Need something more sophisticated? For advanced surveys and questionnaires you can integrate Qualtrics: a callback lets the survey talk back to the StudyAlign API so responses are tied to the participant and condition. Verify items and scoring against the original instruments before running a real study.

Put it together

With the procedure set up, the library logging from your prototype, and your surveys connected, share the participant links and watch data land in the backend. Export your study schema when you publish, so others can reproduce it.

Open the Admin Panel Browse the code & examples