Compatibility/System Addon/Override Policies and Workflows

Preamble

If important sites are broken in Firefox, getting them fixed is our highest priority (even if by the user agent intervening on behalf of the user). However, there's a balance to be struck: we do not have the bandwidth to fix the entire web, and patching certain problem may disincentivize developers from fixing their bugs.

As a guiding principle, if deploying a site patch or override would dramatically improve user experience or fix a top site it should be seriously considered. At the same time, we make efforts to remove the override as soon as possible, working with the site developers where possible.

Consult Intervention Releases for more information on the process of shipping interventions.

To Override or not?

Our goal is to fix top sites, or sites that will have the most impact for Firefox users.

• It's important to consider a site's popularity on a by-country level, in addition to global level.
• We have no fixed threshold on the sites rank that qualifies for an override. However, we might set a soft limit in the future when we have more experience deploying site patches.
• Trending sites should also be considered, even when they don't rank highly in global usage metrics.

Types of Interventions

User Agent overrides

Designing the override

• Since we are able to set a very specific scope for overrides, we aim to limit the scope of overrides as much as possible. If only a specific site in a specific subdirectory is affected, it's much better to override just that segment instead of overriding the UA for the entire site.
• We try to touch the user agent as little as possible. If adding a segment like "mobile" or "iPhone" solves an issue, this is should be preferred over replacing the entire UA. That way, Firefox still might be recognized by the sites statistics.

Technical details

User agent overrides are defined within src/data/ua_overrides.js of the addon sources. In this file, you will only find an array containing all active user agent overrides. Each object can have three attributes:

• baseDomain, required: The base domain that further checks and user agents override are applied to. This does not include subdomains.
• applications: Array of applications this override is valid in. Defaults to ["firefox"], can be one or more of:
  • firefox: Firefox Desktop (regardless of the operating system)
  • fennec: Firefox for Android
• uriMatcher: Function that gets the requested URI passed in the first argument and needs to return boolean whether or not the override should be applied. If not provided, the user agent override will be applied every time.
• uaTransformer, required: Function that gets the original Firefox user agent passed as its first argument and needs to return a string that will be used as the the user agent for this URI.

Examples

Gets applied for all requests to mozilla.org and subdomains made on Firefox Desktop:

  {
    baseDomain: "mozilla.org",
    uriMatcher: (uri) => uri.includes("/app/"),
    uaTransformer: (originalUA) => `Ohai Mozilla, it's me, ${originalUA}`
  }

Applies to *.example.com/app/* on Firefox for Android:

  {
    baseDomain: "example.com",
    applications: ["fennec"],
    uriMatcher: (uri) => uri.includes("/app/"),
    uaTransformer: (originalUA) => originalUA.replace("Firefox", "Otherfox")
  }

CSS Injections

Designing the injection

As with user agent overrides, CSS injections should be designed to use as little code as possible. Due to the nature of these overrides, it is hard to provide exact guidelines.

Injected CSS files will be in the first place of the cascading chain, so be careful to use selectors with a high specificity, or use the !important keyword.

Technical details

CSS injections are defined within individual files within the src/webextension/injections/css/ directory of the addon sources. In this folder, you will find a collection of files, one file per override or injection. For easier cross-reference, please stick to the bugNNNNN-short-description.css file name schema.

In addition, the injection file has to be registered in the constant array located at the top of src/webextension/background.js. Details on available parameters can be found in the MDN web docs.

JS Injections

Designing the injection

As with user agent overrides, JS injections should be designed to use as little code as possible. Due to the nature of these overrides, it is hard to provide exact guidelines.

The injected JS will be executed in its own context per default, check the MDN web docs for details. If it is required to run JS in the websites context, functions can be exported via exportFunction:

Object.defineProperty(window.wrappedJSObject, "isTestFeatureSupported", {
  get: exportFunction(function() {
    return true;
  }, window),

  set: exportFunction(function() {}, window)
});

Technical details

JS injections are defined within individual files within the src/webextension/injections/js/ directory of the addon sources. In this folder, you will find a collection of files, one file per override or injection. For easier cross-reference, please stick to the bugNNNNN-short-description.js file name schema.

In addition, the injection file has to be registered in the array located in rc/data/injections.js. Details on available parameters can be found in the MDN web docs.

=== Using "custom functions" for more complex overrides

Some injections may require additional logic inside the WebExtension to make them work. An example of this could be a custom blocking browser.webRequest.onBeforeRequest handler to detect and alter the usage of a popular JavaScript library. To use customized logic, define a customFunc in your injection definition:

{
  id: "bug1551672",
  platform: "android",
  domain: "Sites using PDK 5 video",
  bug: "1551672",
  data: {
    urls: ["https://*/*/tpPdk.js", "https://*/*/pdk/js/*/*.js"],
    types: ["script"],
  },
  customFunc: "pdk5fix",
}

Then, head to src/lib/custom_functions.js and make sure to define the function you just named. Suppose you need additional logic for clearing up when disabling the intervention, for example, to unregister a handler. In that case, you can define a second function with the Disable suffix, pdk5fixDisable in this example.

Custom functions are executed within the background script and have full permissions to do anything that a WebExtension background script can do.

Automated Testing

See https://wiki.mozilla.org/Compatibility/System_Addon/Automated_Testing

Open points for further discussion

Some cases might never be added to this decision guide, but discussed with the team on the individual case:

• Should we override/inject if a site adds a "Your browser is not supported" note? What if the warning is really annoying or even blocking the site, what if it's just a note?
• Do we override websites that require a login? How can we ensure that we don't break the site with overriding the user agent or injecting code?