Eye Gaze (WebGazer)
The Eye Gaze analysis processes the gaze data collected during a participant's session and produces fixation events, heatmaps, and summary statistics that describe where the participant looked and for how long.
Overview
During a session the participant's webcam feed is used to estimate where they are looking on screen. These raw gaze estimates are collected continuously throughout the tasks and uploaded at the end of the session. The Eye Gaze analysis then processes those samples to identify fixations (moments where the gaze is stable on one region), build spatial heatmaps, and compute summary metrics.
The analysis runs automatically after the session is processed. No action is required from you to start it.
Requirements
The study must include the Eye Tracking Calibration task. Without a calibration step the gaze estimates are not reliable enough to be analysed.
What it produces
- Fixation events: each period of stable gaze is recorded as a fixation with a start time, end time, duration, and position (as a percentage of the screen width and height).
- Heatmaps: a 50-by-50 grid showing where samples accumulated, both in aggregate across all tasks and separately for each task.
- Summary statistics: per-task and aggregate metrics including sample count, estimated sampling rate, number of fixations, longest fixation duration, and the proportion of time spent fixating.
Where to find the results
Results appear in the Analysis tab of the participation page. The result panel shows:
- An aggregate summary with headline numbers (sample count, fixation count, proportion of time fixating).
- A per-task breakdown with the same metrics for each individual task.
- A heatmap visualisation for each task and in aggregate.
In the Timeline tab the gaze data appears as a density track showing sample concentration over time. Optional Gaze X and Gaze Y area-chart tracks (hidden by default) show the horizontal and vertical gaze position over time. Clicking on a segment of the gaze density track opens a details panel showing the number of samples in that segment along with the on-screen area the gaze covered (minimum, maximum, and average position).
If the gaze density track is not shown on the Timeline, a short message explains why:
- If the study does not include the Eye Tracking Calibration task, the message states that gaze data is not available for this study.
- If the analysis has not finished yet, the message states that the track will appear once the analysis completes.
- If the analysis did not finish successfully, the message states that the track will not appear automatically and suggests restarting the analysis from the Analysis tab.
- If the analysis completed but produced no usable gaze samples, the message states that no usable gaze data was recorded for this session.
On the Recordings tab, a gaze overlay can be toggled to show a moving dot indicating estimated gaze position as the recording plays back.
Exporting
From the participation download panel you can export analyses/eye_gaze.json — the full result file in JSON format. It contains:
| Section | Description |
|---|---|
samples | All validated gaze samples, each with a timestamp, screen X position (0–100%), screen Y position (0–100%), and the task index active at that moment |
fixations | Detected fixation events with start time, end time, duration, centre position, and task index |
heatmap | Aggregate and per-task 50-by-50 grids (sample counts per cell) |
summary | Aggregate and per-task metrics (see below) |
params | The dispersion and minimum duration thresholds used for this run |
Summary metric columns
| Field | Description |
|---|---|
sample_count | Number of valid gaze samples in this slice |
effective_hz | Estimated sampling rate (samples per second) |
fixation_count | Number of detected fixations |
longest_fixation_ms | Duration of the longest fixation in milliseconds |
pct_time_fixating | Proportion of sample-span time spent in fixations (0–1) |
mean_inter_fixation_ms | Average gap between consecutive fixations in milliseconds |
Timestamps in the export (recording_ms on samples, start_recording_ms / end_recording_ms on fixations) are in milliseconds relative to the recording start.
Configuration
Two parameters control how fixations are detected. You can adjust them per study in the study configuration panel:
- Dispersion threshold (default 2%): controls how tightly clustered successive gaze points must be to qualify as a fixation. Lower values require the gaze to be more stable before a fixation is declared.
- Minimum duration (default 100 ms): the shortest period of stable gaze that counts as a fixation. Shorter values will detect more brief fixations; longer values filter them out.
Accuracy considerations
- Webcam-based eye tracking is an approximation. Accuracy is typically within a few degrees of visual angle under good conditions (good lighting, stable head position, completed calibration).
- Results are most reliable when the participant completed the calibration task and remained reasonably still.
- Poor lighting, glasses reflections, or a low-quality webcam will reduce accuracy.
- The estimates describe where on the screen the participant was looking, not at what specific stimulus element.
Troubleshooting
The analysis shows "Failed" with a data not found message Gaze data was not collected or uploaded for this session. This usually means the participant's browser did not grant camera access, or the gaze collection was stopped before the session ended. The analysis cannot be run without the raw gaze file.
Very few fixations detected Try lowering the dispersion threshold or the minimum duration. If the sample count is also very low, the gaze collection may have been interrupted during the session.
The heatmap looks sparse or concentrated in one area This can indicate calibration issues or that the participant was not looking at the screen for most of the session. Review the recording alongside the gaze overlay to check.