Web Science
A library of reusable functionality for Firefox Pioneer studies.
Requirements
- Node.js, available via Homebrew on macOS
- Mozilla web-ext
Example Usage
See the News and Disinformation Study, which we recommend using as a template.
Architecture
The Web Science library consists of two types of modules: measurement modules that collect a specific type of data, and utility modules that provide supporting functionality. A Firefox Pioneer study can optionally take advantage of the Web Science library (or a subset of the library) for faster development and review. We recommend including the repository for Web Science as a Git subtree in the repository for a Firefox Pioneer study.
/Measurements/
Measurement Modules -The measurement modules provide reusable passive collection and intervention building blocks for conducting studies.
- LinkExposure.js - Measures user exposure to links to domains of interest, using a content script.
- content-scripts/linkExposure.js - A content script that extracts links to domains of interest from a page DOM.
- PageNavigation.js - Measures user navigation and attention to webpages on domains of interest, using the
PageEvents
utility module. - SocialMediaAccountExposure.js - Measures how users are exposed to content from specific social media accounts on YouTube and Facebook, using content scripts.
- content-scripts/socialMediaAccountExposure-youtube.js - A content script that identifies content from known YouTube channels.
- content-scripts/socialMediaAccountExposure-fb.js - A content script that identifies posts from know Facebook accounts.
- SocialMediaNewsExposure.js - Measures how users are exposed to news on social media , using a content script.
- content-scripts/socialMediaNewsExposure-youtube.js - A content script that checks for the News & Politics category on Youtube.
- SocialMediaLinkSharing.js - Measures user sharing of links to domains of interest on social media platforms, using the
SocialMediaActivity
utility module.
/Utilities/
Utility Modules -The utility modules provide a library of reusable functions that assist with conducting studies.
- Lifecycle.js - Functions for starting and stopping studies.
- Debugging.js - Functionality for outputting debugging messages to the console in a consistent format. Implemented with the
console
Web API. - Idle.js - Functionality for supporting browser idle state listeners with differing idle state thresholds. Implemented with the
idle
WebExtensions API. - LinkResolution.js - Functionality for resolving shortened and shimmed URLs. Implemented with the
fetch
Web API and thewebRequest
WebExtensions API. - Matching.js - Functions for efficiently matching domain names and URLs.
- Messaging.js - Functionality for supporting message types and message schemes for messaging between the background page and content scripts. Implemented with the
runtime
WebExtensions API. - PageEvents.js - Functions for acting on events associated with webpage loading and user attention. The
PageEvents
module provides a research abstraction that guarantees the order of events (i.e., a finite-state automaton). Implemented with thetabs
,windows
, andwebRequest
WebExtensions APIs and theIdle
utility module. - Randomization.js - Functionality for selecting and persisting randomized conditions.
- ResponseBody.js - Functionality for reassembling an HTTP(S) response body using the
webRequest
WebExtensions API. - Scheduling.js - Functionality for scheduling daily and weekly tasks, when the browser is idle. Implemented with the
Idle
utility module. Similar to theidle-daily
event emitted by the FirefoxnsIdleService
. - SocialMediaActivity.js - Functionality for listening to and acting on user sharing activity on social media platforms. Facebook, Twitter, and Reddit are currently supported. Implemented with the
webRequest
WebExtensions API. - Storage.js - Functionality for persisting study data. Implemented using the
localForage
library.- ../dependencies/localforagees6.min.js - The
localForage
library, lightly modified to support importation as an ES6 module.
- ../dependencies/localforagees6.min.js - The