From MozillaWiki
Jump to: navigation, search


Most of this documentation is now out of date. Please go see https://webextensions-experiments.readthedocs.io/en/latest/ instead.


As we move to a world of WebExtensions for add-ons we need to be able to provide more APIs than ever before to our users. We need to be able to go beyond what chrome provides to allow more flexibility and customisation than other browsers.

At the same time, we need to be able to move faster than the Firefox train and allow developers to be able to quickly develop and experiment with APIs. Those APIs would land in an add-on and as APIs become stable and supported they could be moved down into mozilla-central and move from "experimental" to "stable".

To repeat, this is the overall goal: be an area to allow developers to develop and experiment with APIs.

Key points:

  • We would land experimental APIs in an add-on outside of Firefox.
  • There would be only one WebExtensions Experiments add-on.
  • All add-ons using WebExtensions Experiments would be dependent upon the WebExtensions Experiment.
  • The use of WebExtensions Experiments would be declared in the manifest through a permission.
  • Documentation would be on MDN but marked as experimental.
  • APIs would be available in the browser namespace, and not in chrome.
  • APIs exposed by native.js extensions would be as high-level as possible. We would look for things like "open a sidebar containing HTML content", or "enter fullscreen mode". APIs exposing concepts from the internals of Firefox (e.g., channels, load groups, or particular XUL element names from browser.xul) would be forbidden.
  • Breaking changes could occur to the WebExtensions Experiment. But would be discouraged.


It's expected that when developers add in an API we are applying a rigor that is similar to what we would apply to mozilla-central - but hopefully easier to use. For example:

  • code will be under MPL
  • code will live on github (or similar)
  • APIs should aim for the high level approach
  • APIs should come with documentation and tests
  • each release of WebExtensions Experiments will be tested on every version of Firefox and will be expected to pass
  • releases can be frequent (eg: weekly)

For any API, developers submitting an API should be understanding that one of a few things can happen:

  • it will be accepted and move down into mozilla-central
  • it will change and be altered with the aim of improving it so it can land into mozilla-central
  • it will be rejected and removed because it will not be accepted into mozilla-central


With the addition of mozilla.json, we have a bit more free reign about what is available here

Extension Type

A new extension type of 256 was added to differentiate experiments.



There is another project at Mozilla that is focused on opt-in tools to allow developers to turn on certain add-ons and provide feedback. That's Test Pilot and it might make sense for us to integrate with that infrastructure instead of build our own. Test Pilot could potentially provide:

  • a website for developers to access to get the WebExtensions Experiments add-on
  • to find add-ons using WebExtensions Experiments
  • to provide metrics back through the Test Pilot metrics pipeline about what add-ons are in use and the metrics within that add-on
  • to collect feedback about the add-on tested when its uninstalled

I also like the synergy. Want to add a new feature to Firefox? You do it using Test Pilot. Adding a new feature, well you might want some APIs for that...

This would also require the SDK - WebExtensions transition flow to be completed to allow a WebExtensions and SDK add-on to communicate with each other.

Specific limitations

This proposal is suggesting some specific limitations for the first release namely that:

  • it is explicitly opt-in
  • no multiple dependencies, everything in one bundle

The main reasons for doing this are the following:

  • we need to build the infrastructure for having an add-on that does this
  • dependency management is hard and I haven't seen proof of its need yet

If the first stage is successful, then we'll move onto the future steps (see below) that remove these limitations.

Other proposals

This is based on the original proposal by Giorgio here. All the errors and watering down of said proposal is done by Andy. In many ways this proposal is significantly and deliberately scoped down version of that proposal. To recognise that we need to move in steps to achieve the bigger goal.

Chrome has an experimental API.

Workflow for a new API

Please see docs on https://webextensions-experiments.readthedocs.io/en/latest/new.html


If the experiment results in an API that is going to land into Firefox, then we'll uplift that to mozilla-central. Any code must meet basic criteria.

TODO: complete this flow

An email to dev-addons@mozilla.com would be useful with the subject: "Intent to implement [name]" detailing the experiment that is moving up into Firefox.


Milestone 1

  • Create a prototype
  • Prove that this can work

Status: complete bug 1263011

Milestone 2

  • Automated testing of the experiment code across multiple channels
  • Two APIs that work with experiment
  • A first experiment add-on loaded onto AMO

Milestone 3

  • [proposal] Go Faster, maybe
  • [proposal] Experiment homepage, something to list the experiments, explain what to do
  • [proposal] Would an uplift policy make sense

Next phases

More people

Currently this proposal differs from some of the proposals in a key way, its is explicitly trying to limit the population of users to an opt-in audience. If the first phase is successful, we'd want to look at moving to more users.

This is similar to the differentiation between Test Pilot (opt-in only), Shield (a % of the audience) and Go Faster (all the users).

More libraries

Currently this proposal limits us to one and only one Web-Extensions Experiment. In the future we might want to allow a multitude of libraries.