Tracking Mouse Behavior on a Website AOI

Inside a Website Frame, both mouse events and gaze are recorded the same underlying way: neither can target anything except a Website AOI element, that's the only object a Website Frame can contain. This page covers building a Mouse Trigger event on a Website AOI, in full. For gaze, see the Website Frame Eye Tracking Walkthrough, that trigger's own event setup is already covered there in detail and isn't repeated here.

Why This Needs Setup Here, Unlike Elsewhere in Labvanced

Outside a Website Frame, mouse tracking mostly just works: a frame's continuous mouse-tracking property records cursor movement passively, with no trigger required. Inside a Website Frame's embedded page, that passive tracking never fires, the participant's browser doesn't deliver mouse movement to the parent page while the cursor is over an iframe, regardless of any Labvanced setting. A Mouse Trigger, backed by the Labvanced Web Bridge extension, is the only way to get any mouse data from inside the frame at all. If you don't build one, a Website AOI records nothing about mouse behavior, silently, the same way an unanchored AOI records nothing without you noticing.

The Three Targeting Modes

Add a Mouse Trigger event and, inside a Website Frame, its Targets: section offers three modes instead of a single target picker:

This is a richer choice than gaze gets on the same frame: the Eyetracking Gaze/Eyetracking Fixation triggers offer only two modes, Only trigger when looking at specific elements unchecked (fires continuously, untargeted, whenever new gaze data exists) or checked (limited to specific picked AOI targets). There's no gaze equivalent of Any AOI element.

If AOIs overlap, targeting mode changes what counts. For Click, PressDown, and PressUp with specific targets picked, Labvanced checks every AOI at the click point, not just the one visually on top, so your target still fires even if a different AOI is stacked above it there. Any element in website frame and Any AOI element modes, and Hover/Leave/Move regardless of mode, only ever consider the single topmost element at that point.

Building the Event

1. Add a new event, select Mouse Trigger.
2. Set Action: to the interaction you want: Click, PressDown, PressUp, Hover, Leave, or Move. For Click, PressDown, and PressUp, a Button: dropdown also appears, Left or Right, to restrict the trigger to one mouse button.
3. Choose a targeting mode from the table above. If you leave both checkboxes unchecked, click Add Target and select the Website AOI(s) you want.
4. Add a Set / Record Variable action to actually capture data, an event without one records nothing, the same as an AOI without an Eyetracking Gaze event attached. Set the variable's Format to Array. For Record Type, Final value keeps only the most recent occurrence and Time series keeps every one. Choosing Time series reveals a further Sampling method option: record all (allow repeated duplicates) or record changes only (no repeated duplicates).
5. In the value select menu, choose from the Trigger (Mouse) category, this is where the values specific to this event live, described in the next section.

Trigger: Mouse Trigger → Action: Move → Targets: Any AOI element
Action: Set / Record Variable → Format: Array, Record Type: Time series, Sampling method: record all (allow repeated duplicates) → value: Mouse [Name, Info, X, Y] Array from Trigger (Mouse)

This records the AOI's name and label alongside its page-relative X/Y on every mouse move over any registered AOI, without needing a separate event per AOI.

Choosing a Value, and the Coordinate Space That Comes With It

The Trigger (Mouse) category offers:

MouseX/MouseY (and the arrays built from them) do not mean the same thing across every interaction type:

• Click, PressDown, PressUp, Move report page-relative coordinates, the position on the embedded page's full scrollable area, including whatever the participant has scrolled past.
• Hover, Leave report element-relative coordinates instead, the position within the AOI itself, not the page.

Both are labeled identically (MouseX, MouseY) in the value picker, nothing in the interface distinguishes them beyond which interaction type the event is built on. Mixing data from a Hover event and a Move event into the same exported column will mix two different coordinate spaces without any warning. Decide up front which interaction type you actually need before wiring up the recording action.

Stimulus Name and Stimulus Info identify which AOI the event fired on, the same Stimulus Info label covered in Naming an AOI for Your Exported Data, useful once you're recording from more than one AOI or from Any AOI element mode. Element Text carries the AOI's visible text at the moment of the event.

Shared With Gaze: Page-Relative Coordinates Include Scroll

The page-relative coordinates described above (for Click, PressDown, PressUp, Move) include the iframe's internal scroll offset, not just what's currently visible in the viewport. Gaze coordinates recorded on a Website AOI work the same way. If you're combining mouse and gaze data from the same AOI during analysis, both use this same page-relative coordinate space, so they line up directly. You don't need to convert one to match the other.

Page Scroll Position Isn't a Separate Value

The main guide's tracked-data list mentions scroll position, but there's no standalone "current scroll position" value to record on its own. Scroll offset is only ever applied automatically inside the page-relative coordinates already described above (Click, PressDown, PressUp, Move), not exposed as its own recordable variable. If you need scroll behavior on a scrollable sub-region within an AOI specifically, that's a separate setting, Scrollable container on the AOI itself, covered in Tracking a Scrollable Sub-Region, and its resulting data is only available through the Eyetracking Gaze/Eyetracking Fixation trigger, not Mouse Trigger.

Troubleshooting

The event never fires. Confirm the Web Bridge extension is installed and active, nothing reaches a Mouse Trigger inside a Website Frame without it. If you're using specific targets, confirm the AOI you picked is actually anchored, an unanchored AOI (selectorFound false) won't fire targeted events even though the trigger itself is configured correctly.

It fires for the wrong elements, or too often. Check which targeting mode is selected. Any element in website frame fires everywhere, including outside any AOI, if that's not what you meant, switch to Any AOI element or pick specific targets instead.

Recorded coordinates look wrong or inconsistent. Check which interaction type the event uses. Hover/Leave coordinates are relative to the AOI, Click/PressDown/PressUp/Move are relative to the page, see Choosing a Value above.

Frequently Asked Questions

Further Reading