focus namespace

This page documents the uil.focus namespace/module. This namespace contains some functions to help to see whether the participant is focussed on the experiment or is doing other stuff. It keeps track of whether the focus is at the current task, or the focus goes to another task for example.

classes in the focus module

class FocusStats(is_active, cum_active, cum_inactive, num_focus, num_focus_lost, num_shows, num_hides)

Get an aggregate structure that describes the statistics on how dedicated the pc was to the experiment vs other tasks. All durations are in seconds, as that is more intuitive than milliseconds.

TODO document what focus and shows/hides mean.

FocusStats.FocusStats.is_active: Whether the client is currently looking at the desired page

FocusStats.FocusStats.cum_active: The cumulative time that the participant is active

FocusStats.FocusStats.cum_inactive: The cumulative time that the participant is not active

FocusStats.FocusStats.num_focus: The number of time the browser focused on our tab

FocusStats.FocusStats.num_focus_lost: The number of times that our tab lost the focus

FocusStats.FocusStats.num_shows: The number of times that our tab is unhidden.

FocusStats.FocusStats.num_hides: The number of times that our tab is hidden.

functions in the focus module

registerUserFocus()

Registers capturing and losing focus inside an experiment.

When this function is called, the utils will keep track when the window/tab loses its focus/visibility. It will get be noticed when the user changes browser tabs (visibility) or changes programs (focus).

clearUserFocus()

Undo’s the actions of registerUserFocus()

If you need the statistics about the user focus, make sure you’ll obtain the before calling this function.

getStats()

Obtain the current statics about the user, losing and capturing the focus of the window. It might be a measure on how dedicated the user was vs how distracted the user was.

Returns:: FocusStats|undefined – The statistics since registerUserFocus()has been called or undefined when registerUserFocus hasn’t been called or clearUserFocus has been called.