2016rshah / web-science

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

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.
• Encourage researchers to practice data minimization when implementing studies.
• Provide an API that is built on and consistent with WebExtensions, and that is compatible 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 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 the node-resolve plugin to integrate WebScience 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

We will have documentation for the WebScience API online shortly. In the interim, the WebScience source includes voluminous JSDoc annotations.

API Implementation Progress

Module	No Breaking Changes Planned	No Known Bugs	Good Documentation	Good Test Coverage
debugging	✅	✅	✅	❌
events	✅	✅	✅	❌
id	✅	✅	✅	❌
idle	✅	✅	✅	❌
inline	✅	✅	✅	❌
linkExposure	❌ #17	✅	❌ #17	❌
linkResolution	✅	✅	✅	❌
matching	✅	✅	✅	❌
messaging	✅	✅	✅	❌
pageClassification	❌ #11	✅	✅	❌
pageManager	✅	✅	✅	❌
pageNavigation	✅	✅	✅	❌
permissions	✅	✅	✅	❌
randomization	✅	✅	✅	❌
scheduling	✅	✅	✅	❌
socialMediaActivity	❌ #23	✅	✅	❌
socialMediaLinkSharing	❌ #17	✅	✅	❌
storage	✅	✅	✅	❌
userSurvey	✅	✅	✅	❌