diff --git a/docs/demos/jspsych-browser-check-demo1.html b/docs/demos/jspsych-browser-check-demo1.html new file mode 100644 index 00000000..3335e6e6 --- /dev/null +++ b/docs/demos/jspsych-browser-check-demo1.html @@ -0,0 +1,50 @@ + + + + + + + + + + + + diff --git a/docs/demos/jspsych-browser-check-demo2.html b/docs/demos/jspsych-browser-check-demo2.html new file mode 100644 index 00000000..b41f004c --- /dev/null +++ b/docs/demos/jspsych-browser-check-demo2.html @@ -0,0 +1,53 @@ + + + + + + + + + + + + diff --git a/docs/demos/jspsych-browser-check-demo3.html b/docs/demos/jspsych-browser-check-demo3.html new file mode 100644 index 00000000..675a4900 --- /dev/null +++ b/docs/demos/jspsych-browser-check-demo3.html @@ -0,0 +1,51 @@ + + + + + + + + + + + + diff --git a/docs/plugins/browser-check.md b/docs/plugins/browser-check.md index 1e876a7c..bc602b1f 100644 --- a/docs/plugins/browser-check.md +++ b/docs/plugins/browser-check.md @@ -4,17 +4,26 @@ This plugin measures and records various features of the participant's browser a The plugin currently can record the following features: -* The width and height of the browser window. -* Support for the WebAudio API. +* 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.* -* Whether the browser supports fullscreen displays, e.g., through the [fullscreen plugin](../plugins/fullscreen.md). -* The frame rate. +* Support for the WebAudio API. +* Support for the Fullscreen API, e.g., through the [fullscreen plugin](../plugins/fullscreen.md). +* The display refresh rate in frames per second. -_*These features are recording through parsing the [user agent string](https://developer.mozilla.org/en-US/docs/Web/HTTP/Browser_detection_using_the_user_agent). This method is accurate most of the time, but is not guaranteed to be correct._ +!!! warning + Features with an * are recorded by parsing the [user agent string](https://developer.mozilla.org/en-US/docs/Web/HTTP/Browser_detection_using_the_user_agent). + This method is accurate most of the time, but is not guaranteed to be correct. + The plugin uses the [detect-browser package](https://github.com/DamonOehlman/detect-browser) to perform user agent parsing. + You can find a list of supported browsers and OSes in the [source file](https://github.com/DamonOehlman/detect-browser/blob/master/src/index.ts). -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. +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 @@ -22,7 +31,16 @@ In addition to the [parameters available in all plugins](../overview/plugins.md# | Parameter | Type | Default Value | Description | | ------------------------------ | ---------------- | ------------- | ---------------------------------------- | -| +| features | array of strings | `["width", "height", "webaudio", "browser", "browser_version", "mobile", "os", "fullscreen", "vsync_rate"]` | 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: `

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.

The minimum window width is px.

Your current window width is px.

The minimum window height is px.

Your current window height is px.

`. +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 | string | `

Your browser does not meet the requirements to participate in this experiment.

` | The message to display if `inclusion_function` evaluates to `false` or if the participant clicks on the resize fail button during the interactive resize. ## Data Generated @@ -30,47 +48,68 @@ In addition to the [default data collected by all plugins](../overview/plugins.m | Name | Type | Value | | ------------ | ------- | ---------------------------------------- | -| response | numeric | The numeric value of the slider. | -| rt | numeric | The time in milliseconds for the subject to make a response. The time is measured from when the stimulus first began playing until the subject's response. | -| stimulus | string | The path of the audio file that was played. | -| slider_start | numeric | The starting value of the slider. | +| 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. + +Note that all of these values are only recorded when the corresponding key is included in the `features` parameter for the trial. ## Examples -???+ example "A simple rating scale" +???+ example "Recording all of the available features, no interactive resize" === "Code" ```javascript var trial = { - type: jsPsychAudioSliderResponse, - stimulus: 'sound/speech_joke.mp3', - labels: ['Not Funny', 'Funny'], - prompt: '

How funny is the joke?

' - } + type: jsPsychBrowserCheck, + allow_resize: false + }; ``` === "Demo"
- +
- Open demo in new tab + Open demo in new tab -???+ example "No response allowed until audio finishes; subject must interact with slider to continue" +???+ example "Using the inclusion function to mandate the use of Chrome or Firefox as the browser" === "Code" ```javascript var trial = { - type: jsPsychAudioSliderResponse, - stimulus: 'sound/speech_joke.mp3', - labels: ['Not Funny', 'Funny'], - prompt: '

How funny is the joke?

', - response_allowed_while_playing: false, - require_movement: true - } + type: jsPsychBrowserCheck, + inclusion_function: (data) => { + return ['chrome', 'firefox'].contains(data.browser); + }, + exclusion_message: `

You must use Chrome or Firefox to complete this experiment.

` + }; ``` === "Demo"
- +
- Open demo in new tab \ No newline at end of file + Open demo in new tab + +???+ example "Interactive resize" + === "Code" + ```javascript + var trial = { + type: jsPsychBrowserCheck, + minimum_width: 1000, + minimum_height: 600 + }; + ``` + + === "Demo" +
+

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

+ + Open demo in new tab \ No newline at end of file