From 59351a55f1e97532d6161503ca8f727ecdd5603d Mon Sep 17 00:00:00 2001 From: Josh de Leeuw Date: Tue, 19 Oct 2021 21:53:33 -0400 Subject: [PATCH] start of browser-check docs --- docs/overview/exclude-browser.md | 30 ++----------- docs/plugins/browser-check.md | 76 ++++++++++++++++++++++++++++++++ docs/plugins/list-of-plugins.md | 1 + mkdocs.yml | 1 + 4 files changed, 81 insertions(+), 27 deletions(-) create mode 100644 docs/plugins/browser-check.md diff --git a/docs/overview/exclude-browser.md b/docs/overview/exclude-browser.md index 7526d169..76679e77 100644 --- a/docs/overview/exclude-browser.md +++ b/docs/overview/exclude-browser.md @@ -1,30 +1,6 @@ # Exclude Participants Based on Browser Features -Online subjects will use many different kinds of browsers. Depending on the experiment, it may be important to specify a minimum feature set of the browser. jsPsych makes this straightforward. Simply specify certain exclusion criteria in the `initJsPsych` method call. If a subject's browser doesn't meet the criteria the experiment will not start and the subject will see a message explaining the problem. For size restrictions the subject will see a message that displays the current size of their browser window and the minimum size needed to start the experiment, giving the subject an opportunity to enlarge the browser window to continue. +Online subjects will use many different kinds of browsers. +Depending on the experiment, it may be important to specify a minimum feature set of the browser. -Current exclusion options: -* Minimum browser width & height -* Support for the WebAudio API - -## Examples - -#### Exclude browsers that are not at least 800x600 pixels - -```javascript -initJsPsych({ - exclusions: { - min_width: 800, - min_height: 600 - } -}); -``` - -#### Exclude browsers that do not have access to the WebAudio API - -```javascript -initJsPsych({ - exclusions: { - audio: true - } -}); -``` +As of v7.1 of jsPsych, the recommended way to do this is using the [browser-check plugin](../plugins/browser-check.md). This plugin can record many features of the subject's browser and exclude subjects who do not meet a defined set of inclusion criteria. Please see the [browser-check plugin documentation](../plugins/browser-check.md) for more details. diff --git a/docs/plugins/browser-check.md b/docs/plugins/browser-check.md new file mode 100644 index 00000000..1e876a7c --- /dev/null +++ b/docs/plugins/browser-check.md @@ -0,0 +1,76 @@ +# browser-check + +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. +* Support for the WebAudio API. +* 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. + +_*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._ + +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](../overview/plugins.md#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 | +| ------------------------------ | ---------------- | ------------- | ---------------------------------------- | +| + +## Data Generated + +In addition to the [default data collected by all plugins](../overview/plugins.md#data-collected-by-all-plugins), this plugin collects the following data for each trial. + +| 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. | + +## Examples + +???+ example "A simple rating scale" + === "Code" + ```javascript + var trial = { + type: jsPsychAudioSliderResponse, + stimulus: 'sound/speech_joke.mp3', + labels: ['Not Funny', 'Funny'], + prompt: '

How funny is the joke?

' + } + ``` + + === "Demo" +
+ +
+ + Open demo in new tab + +???+ example "No response allowed until audio finishes; subject must interact with slider to continue" + === "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 + } + ``` + + === "Demo" +
+ +
+ + Open demo in new tab \ No newline at end of file diff --git a/docs/plugins/list-of-plugins.md b/docs/plugins/list-of-plugins.md index 3d3941ee..8a59bcbb 100644 --- a/docs/plugins/list-of-plugins.md +++ b/docs/plugins/list-of-plugins.md @@ -12,6 +12,7 @@ Plugin | Description [audio‑button‑response](audio-button-response.md) | Play an audio file and allow the subject to respond by choosing a button to click. The button can be customized extensively, e.g., using images in place of standard buttons. [audio‑keyboard‑response](audio-keyboard-response.md) | Play an audio file and allow the subject to respond by pressing a key. [audio‑slider‑response](audio-slider-response.md) | Play an audio file and allow the subject to respond by moving a slider to indicate a value. +[browser‑check](browser-check.md) | Measures various features of the participant's browser and runs an inclusion check to see if the browser meets a custom set of criteria for running the study. [call‑function](call-function.md) | Executes an arbitrary function call. Doesn't display anything to the subject, and the subject is usually unaware that this plugin has even executed. It's useful for performing tasks at specified times in the experiment, such as saving data. [canvas‑button‑response](canvas-button-response.md) | Draw a stimulus on a [HTML canvas element](https://www.w3schools.com/html/html5_canvas.asp), and record a button click response. Useful for displaying dynamic, parametrically-defined graphics, and for controlling the positioning of multiple graphical elements (shapes, text, images). [canvas‑keyboard‑response](canvas-keyboard-response) | Draw a stimulus on a [HTML canvas element](https://www.w3schools.com/html/html5_canvas.asp), and record a key press response. Useful for displaying dynamic, parametrically-defined graphics, and for controlling the positioning of multiple graphical elements (shapes, text, images). diff --git a/mkdocs.yml b/mkdocs.yml index 4a955bd4..ecda532e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -74,6 +74,7 @@ nav: - 'audio-button-response': 'plugins/audio-button-response.md' - 'audio-keyboard-response': 'plugins/audio-keyboard-response.md' - 'audio-slider-response': 'plugins/audio-slider-response.md' + - 'browser-check': 'plugins/browser-check.md' - 'call-function': 'plugins/call-function.md' - 'canvas-button-response': 'plugins/canvas-button-response.md' - 'canvas-keyboard-response': 'plugins/canvas-keyboard-response.md'