rhelmer / web-science

A library of reusable functionality for Mozilla Rally studies.

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.

Measurement Modules - /Measurements/

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.

Utility Modules - /Utilities/

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 the webRequest 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 the tabs, windows, and webRequest WebExtensions APIs and the Idle 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 the idle-daily event emitted by the Firefox nsIdleService.
• 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.