Telemetry & Events
As a study runs, PsyCloud records a stream of structured events — the same stream you see in
the Preview Events dock and that powers Time Machine and
your exported data. Events use a versioned envelope (current schema 2.0.0).
The event envelope
Every event is wrapped in an envelope with consistent metadata:
timing—wallTime(ISO clock),perfNowMs(high-resolution monotonic time, used for accurate RT), andepochMs.sequence— a globally uniqueeventId, a monotonicsequenceNumber, and parent/cause links for hierarchical events.session— context attached to every event:sessionId,experimentId,subjectId(a study-scoped pseudonym, not PII), and the currenttrialNumber/blockNumber/phaseId/stepId.payload— the event-type-specific data.
Event types
There are ~31 core event types (plus custom_*), grouped by concern:
| Group | Events |
|---|---|
| Session lifecycle | session_start, session_resume, session_end, session_pause, session_wake |
| Experiment lifecycle | experiment_start, experiment_end, block_start, block_end, trial_start, trial_end |
| Structured time | phase_start, phase_end, step_start, step_end |
| Stimulus | stimulus_present, stimulus_update, stimulus_remove |
| Response | response (a single unified event — see below) |
| Quality signals | quality_attention_check, quality_bot_detection, quality_data_validation, quality_timing_anomaly |
| System | error, warning, checkpoint |
| Focus & network | focus_change, visibility_change, asset_load, network_status |
The response event
Responses are captured by one unified response event with a kind discriminator
(keypress | mouse | touch | timeout | form | custom). Its key fields:
responseTime—{ stimulusOnsetPerfNowMs, responsePerfNowMs, rtMs }(allperformance.now()milliseconds, for precise RT).collector— which component collected it (componentId,componentVersion,manifestHash, params).data— the response value(s) (key,value,choice, …).accuracy—{ isCorrect, correctResponse, actualResponse }when correctness is computed.nonResponse—truefor timeouts.
When you write authoring expressions, read the canonical fields
(outcome.correct, outcome.rtMs, outcome.timedOut, response.primary.*) rather than these raw
telemetry paths.
Reliable, offline-first
Events are buffered and persisted locally (IndexedDB) with per-event sync state, so capture survives flaky connectivity and syncs when the connection returns. Each stored event keeps its sync status and retry metadata — the basis of PsyCloud's reliability guarantees.
Next
Which components emit which events.