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:
``js
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:
`js
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 | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: | Firefox, Chrome |
| events | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: | Firefox, Chrome |
| id | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: | Firefox, Chrome |
| idle | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: | Firefox, Chrome |
| inline | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: | Firefox, Chrome |
| linkExposure | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: | Firefox |
| linkResolution | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: | Firefox |
| matching | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: | Firefox, Chrome |
| messaging | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: | Firefox, Chrome |
| pageManager | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: | Firefox, Chrome |
| pageNavigation | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: | Firefox, Chrome |
| pageText | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: | Firefox, Chrome |
| pageTransition | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: | Firefox |
| permissions | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: | Firefox, Chrome |
| randomization | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: | Firefox, Chrome |
| scheduling | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: | Firefox, Chrome |
| socialMediaActivity | :x: #23 | :white_check_mark: | :white_check_mark: | :x: | Firefox |
| socialMediaLinkSharing | :x: #17 | :white_check_mark: | :white_check_mark: | :x: | Firefox |
| storage | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: | Firefox, Chrome |
| timing | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: | Firefox, Chrome |
| userSurvey | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: | Firefox |
| workers` | :white_check_mark: | :white_check_mark: | :white_check_mark: | :x: | Firefox, Chrome |