Skip to content

browser-check

Current version: 1.0.3. See version history.

This plugin measures and records various features of the participant's browser and can end the experiment if defined inclusion criteria are not met.

The plugin currently can record the following features:

  • The width and height of the browser window in pixels.
  • The type of browser used (e.g., Chrome, Firefox, Edge, etc.) and the version number of the browser.*
  • Whether the participant is using a mobile device.*
  • The operating system.*
  • Support for the WebAudio API.
  • Support for the Fullscreen API, e.g., through the fullscreen plugin.
  • The display refresh rate in frames per second.
  • Whether the device has a webcam and microphone. Note that this only reveals whether a webcam/microphone exists. The participant still needs to grant permission in order for the experiment to use these devices.

Warning

Features with an * are recorded by parsing the user agent string. This method is accurate most of the time, but is not guaranteed to be correct. The plugin uses the detect-browser package to perform user agent parsing. You can find a list of supported browsers and OSes in the source file.

The plugin begins by measuring the set of features requested. An inclusion function is evaluated to see if the paricipant passes the inclusion criteria. If they do, then the trial ends and the experiment continues. If they do not, then the experiment ends immediately. If a minimum width and/or minimum height is desired, the plugin will optionally display a message to participants whose browser windows are too small to give them an opportunity to make the window larger if possible. See the examples below for more guidance.

Parameters

In addition to the parameters available in all plugins, this plugin accepts the following parameters. Parameters with a default value of undefined must be specified. Other parameters can be left unspecified if the default value is acceptable.

Parameter Type Default Value Description
features array of strings ["width", "height", "webaudio", "browser", "browser_version", "mobile", "os", "fullscreen", "vsync_rate", "webcam", "microphone"] The list of browser features to record. The default value includes all of the available options.
skip_features array of strings [] Any features listed here will be skipped, even if they appear in features. Use this when you want to run most of the defaults.
vsync_frame_count int 60 The number of frames to sample when measuring the display refresh rate ("vsync_rate"). Increasing the number will potenially improve the stability of the estimate at the cost of increasing the amount of time the plugin takes during this test. On most devices, 60 frames takes about 1 second to measure.
allow_window_resize bool true Whether to allow the participant to resize the browser window if the window is smaller than minimum_width and/or minimum_height. If false, then the minimum_width and minimum_height parameters are ignored and you can validate the size in the inclusion_function.
minimum_height int 0 If allow_window_resize is true, then this is the minimum height of the window (in pixels) that must be met before continuing.
minimum_width int 0 If allow_window_resize is true, then this is the minimum width of the window (in pixels) that must be met before continuing.
window_resize_message string see description The message that will be displayed during the interactive resize when allow_window_resize is true and the window is too small. If the message contains HTML elements with the special IDs browser-check-min-width, browser-check-min-height, browser-check-actual-height, and/or browser-check-actual-width, then the contents of those elements will be dynamically updated to reflect the minimum_width, minimum_height and measured width and height of the browser. The default message is: <p>Your browser window is too small to complete this experiment. Please maximize the size of your browser window. If your browser window is already maximized, you will not be able to complete this experiment.</p><p>The minimum window width is <span id="browser-check-min-width"></span> px.</p><p>Your current window width is <span id="browser-check-actual-width"></span> px.</p><p>The minimum window height is <span id="browser-check-min-height"></span> px.</p><p>Your current window height is <span id="browser-check-actual-height"></span> px.</p>.
resize_fail_button_text string "I cannot make the window any larger" During the interactive resize, a button with this text will be displayed below the window_resize_message for the participant to click if the window cannot meet the minimum size needed. When the button is clicked, the experiment will end and exclusion_message will be displayed.
inclusion_function function () => { return true; } A function that evaluates to true if the browser meets all of the inclusion criteria for the experiment, and false otherwise. The first argument to the function will be an object containing key value pairs with the measured features of the browser. The keys will be the same as those listed in features. See example below.
exclusion_message function () => { return <p>Your browser does not meet the requirements to participate in this experiment.</p> } A function that returns the message to display if inclusion_function evaluates to false or if the participant clicks on the resize fail button during the interactive resize. In order to allow customization of the message, the first argument to the function will be an object containing key value pairs with the measured features of the browser. The keys will be the same as those listed in features. See example below.

Data Generated

In addition to the default data collected by all plugins, this plugin collects the following data for each trial.

Name Type Value
width int The width of the browser window in pixels. If interactive resizing happens, this is the width after resizing.
height int The height of the browser window in pixels. If interactive resizing happens, this is the height after resizing.
browser string The browser used.
browser_version string The version number of the browser.
os string The operating system used.
mobile bool Whether the browser is a mobile device.
webaudio bool Whether the browser supports the WebAudio API.
fullscreen bool Whether the browser supports the Fullscreen API.
vsync_rate number An estimate of the refresh rate of the screen, in frames per second.
webcam bool Whether there is a webcam device available. Note that the participant still must grant permission to access the device before it can be used.
microphone bool Whether there is an audio input device available. Note that the participant still must grant permission to access the device before it can be used.

Note that all of these values are only recorded when the corresponding key is included in the features parameter for the trial.

Simulation Mode

In simulation mode the plugin will report the actual features of the browser, with the exception of vsync_rate, which is always 60.

In data-only mode, if allow_window_resize is true and the browser's width and height are below the maximum value then the reported width and height will be equal to minimum_width and minimum_height, as if the participant resized the browser to meet the specifications.

In visual mode, if allow_window_resize is true and the browser's width and height are below the maximum value then the experiment will wait for 3 seconds before clicking the resize fail button. During this time, you can adjust the window if you would like to.

As with all simulated plugins, you can override the default (actual) data with fake data using simulation_options. This allows you to test your exclusion criteria by simulating other configurations.

Install

Using the CDN-hosted JavaScript file:

<script src="https://unpkg.com/@jspsych/plugin-browser-check@1.0.3"></script>

Using the JavaScript file downloaded from a GitHub release dist archive:

<script src="jspsych/plugin-browser-check.js"></script>

Using NPM:

npm install @jspsych/plugin-browser-check
import browserCheck from '@jspsych/plugin-browser-check';

Examples

Recording all of the available features, no exclusions
var trial = {
  type: jsPsychBrowserCheck
};

Open demo in new tab

Using the inclusion function to mandate the use of Chrome or Firefox as the browser
var trial = {
  type: jsPsychBrowserCheck,
  inclusion_function: (data) => {
    return ['chrome', 'firefox'].includes(data.browser);
  },
  exclusion_message: (data) => {
    return `<p>You must use Chrome or Firefox to complete this experiment.</p>`
  },
};

Open demo in new tab

Setting a minimum window height & width, with the option to resize the window
var trial = {
  type: jsPsychBrowserCheck,
  minimum_width: 1000,
  minimum_height: 600
};

This demo only works in a resizable window. Please open it in new tab

Open demo in new tab

Custom exclusion message based on measured features
var trial = {
  type: jsPsychBrowserCheck,
  inclusion_function: (data) => {
    return data.browser == 'chrome' && data.mobile === false
  },
  exclusion_message: (data) => {
    if(data.mobile){
      return '<p>You must use a desktop/laptop computer to participate in this experiment.</p>';
    } else if(data.browser !== 'chrome'){
      return '<p>You must use Chrome as your browser to complete this experiment.</p>'
    }
  }
};

Open demo in new tab