Skip to content
WebExtension experiments API for privacy-related browser instrumentation that requires privileged code
Branch: develop
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.

OpenWPM WebExtension Experiment / API

CircleCI badge

This is the home of the openwpm-webext-experiment npm package (TODO), which provides:

  • WebExtension Experiment API's

  • Scripts:

    • installOpenWPM shell command copying these files in your study add-on.
  • testUtils/

    • Test utilities (helper classes to write functional/unit tests for your add-on)


Allows writing add-ons that use one or many of OpenWPM's instrumentation modules.

Installing OpenWPM WebExtension Experiment / API in your add-on

  1. Install the Package

    npm install --save mozilla/OpenWPM-WebExtension-Experiment#develop
  2. Copy the files to your 'privileged' src directory

    npx installOpenWPM src/privileged --example

    Suggestion: make this part of your package.json:scripts.postinstall script.

  3. Add the following to your add-on's manifest.json:

      "experiment_apis": {
        "openwpm": {
          "schema": "./privileged/openwpm/schema.json",
          "parent": {
            "scopes": ["addon_parent"],
            "script": "./privileged/openwpm/api.js",
            "paths": [["openwpm"]]
  4. Set logging level to All in about:config

    prefName: openwpm.logLevel
    values: All|Trace|Debug|Info|Warn|Error

    This allows openwpm-related log output in the browser console.

How to use in your add-on

  1. Read the documentation of the API

    Notice that there are

    • functions: async functions in the browser.openwpm.
    • events: webExtension events in the browser.openwpm
    • types: jsonschema draft-04 formats.
  2. Explore test-addon:

    • manifest.json

      Notice the experiment_apis section. This maps browser.openwpm to the privileged api code. (See details below)

    • openwpmSetup.js

      Construct a openwpmSetup usable by browser.openwpm.setup

    • background.js

      Uses the browser.openwpm api within a small instrumented feature.


  • Open an issue
  • Hack and file a PR
  • npm run test must pass.
  • Read ./docs/ for more in-depth development documentation.
  • Useful testing helpers:
    • KEEPOPEN=1 npm run test keeps Firefox open
    • npm run test-only skips build steps.
You can’t perform that action at this time.