README.md

WebScience

WebScience is an open-source library for building browser-based research studies, including on Rally.

Design Goals

• Reduce the barriers to implementing browser-based research studies, by providing production-quality functionality that is commonly required, difficult to implement correctly, and difficult to maintain.
• Standardize measurement methods across browser-based research studies.
• Advance the state of the art in browser-based research methods, such as by providing a sophisticated model for user attention to web content and providing infrastructure for in-browser machine learning classification of webpages.
• Encourage researchers to practice data minimization when implementing studies.
• Support integration with existing libraries that are valuable for browser-based studies, such as for indexed data storage (e.g., Dexie.js) or for machine learning (e.g., TensorFlow.js, ONNX.js, WebDNN, or sklearn-porter).
• Provide an API that is built on and consistent with WebExtensions, reducing the learning curve and offering compatibility with all major web browsers.

Contributors

The primary contributors to WebScience are researchers at the Princeton University Center for Information Technology Policy and the Mozilla Rally team.

Getting Started with WebScience

The easiest way to get started is with the Rally + WebScience study template, which has already been configured to integrate the WebScience library.

If you would prefer to build a browser extension with WebScience from scratch, we recommend the following steps:

• Use Node.js for managing the extension's dependencies with a package.json file and npm install. WebScience is available on npm as the package @mozilla/web-science.
• Use Rollup with @rollup/plugin-node-resolve, @rollup/plugin-commonjs, and @mozilla/web-science/rollup-plugin to integrate the library into your bundled extension.

Using WebScience in a Study Extension

Using WebScience in your study extension is easy. At the start of the background script where you want to use WebScience, just add:

import * as webScience from "@mozilla/web-science";

You will then be able to use the WebScience API within the background script (e.g., webScience.pageNavigation...).

You can also selectively import components of the WebScience API, if you prefer. Just add, for example:

import { pageNavigation, socialMediaLinkSharing } from "@mozilla/web-science";

You will then be able to use those components of the API (e.g., pageNavigation...).

Exploring the WebScience API

Documentation for the latest release of WebScience is available at https://mozilla-rally.github.io/web-science/jsdocs/. The documentation is automatically generated from JSDoc annotations in the WebScience implementation.

API Implementation Progress

Module	No Breaking Changes Planned	No Known Bugs	Good Documentation	Good Test Coverage	Browser Support
debugging	✅	✅	✅	❌	Firefox, Chrome
events	✅	✅	✅	❌	Firefox, Chrome
id	✅	✅	✅	❌	Firefox, Chrome
idle	✅	✅	✅	❌	Firefox, Chrome
inline	✅	✅	✅	❌	Firefox, Chrome
linkExposure	✅	✅	✅	❌	Firefox
linkResolution	✅	✅	✅	❌	Firefox
matching	✅	✅	✅	❌	Firefox, Chrome
messaging	✅	✅	✅	❌	Firefox, Chrome
pageManager	✅	✅	✅	❌	Firefox, Chrome
pageNavigation	✅	✅	✅	❌	Firefox, Chrome
pageText	✅	✅	✅	❌	Firefox, Chrome
pageTransition	✅	✅	✅	❌	Firefox
permissions	✅	✅	✅	❌	Firefox, Chrome
randomization	✅	✅	✅	❌	Firefox, Chrome
scheduling	✅	✅	✅	❌	Firefox, Chrome
socialMediaActivity	❌ #23	✅	✅	❌	Firefox
socialMediaLinkSharing	❌ #17	✅	✅	❌	Firefox
storage	✅	✅	✅	❌	Firefox, Chrome
timing	✅	✅	✅	❌	Firefox, Chrome
userSurvey	✅	✅	✅	❌	Firefox
workers	✅	✅	✅	❌	Firefox, Chrome