Compatibility/System Addon/Override Policies and Workflows: Difference between revisions

From MozillaWiki
Jump to navigation Jump to search
(Add docs for writing a custom function inside injections.)
(Redirect to new documentation)
Tag: New redirect
 
(2 intermediate revisions by 2 users not shown)
Line 1: Line 1:
= Preamble =
#REDIRECT [[Compatibility/System Addon/Interventions]]
 
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 [[Compatibility/Interventions_Releases|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 [https://github.com/mozilla/webcompat-addon/blob/master/src/data/ua_overrides.js 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:
 
<syntaxhighlight lang="js">
  {
    baseDomain: "mozilla.org",
    uriMatcher: (uri) => uri.includes("/app/"),
    uaTransformer: (originalUA) => `Ohai Mozilla, it's me, ${originalUA}`
  }
</syntaxhighlight>
 
Applies to ''*.example.com/app/*'' on Firefox for Android:
 
<syntaxhighlight lang="js">
  {
    baseDomain: "example.com",
    applications: ["fennec"],
    uriMatcher: (uri) => uri.includes("/app/"),
    uaTransformer: (originalUA) => originalUA.replace("Firefox", "Otherfox")
  }
</syntaxhighlight>
 
== 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 [https://github.com/mozilla/webcompat-addon/blob/master/src/webextension/injections/css/ 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 [https://github.com/mozilla/webcompat-addon/blob/master/src/webextension/background.js#L7 src/webextension/background.js]. Details on available parameters can be found [https://developer.mozilla.org/en-US/Add-ons/WebExtensions/manifest.json/content_scripts 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 [https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Content_scripts#Content_script_environment the MDN web docs] for details. If it is required to run JS in the websites context, functions can be exported via [https://developer.mozilla.org/en-US/docs/Mozilla/Tech/XPCOM/Language_Bindings/Components.utils.exportFunction exportFunction]:
 
<syntaxhighlight lang="js">
Object.defineProperty(window.wrappedJSObject, "isTestFeatureSupported", {
  get: exportFunction(function() {
    return true;
  }, window),
 
  set: exportFunction(function() {}, window)
});
</syntaxhighlight>
 
=== Technical details ===
 
JS injections are defined within individual files within the [https://github.com/mozilla/webcompat-addon/blob/master/src/webextension/injections/js/ 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 [https://github.com/mozilla/webcompat-addon/blob/master/src/data/injections.js rc/data/injections.js]. Details on available parameters can be found [https://developer.mozilla.org/en-US/Add-ons/WebExtensions/manifest.json/content_scripts 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:
 
<syntaxhighlight lang="js">
{
  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",
}
</syntaxhighlight>
 
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.
 
= 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?
* How do we make sure that our override is indeed working? What do we need to test?
* 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?
 
[[Category:Web Compatibility]]

Latest revision as of 13:14, 28 May 2025

Redirect to:

Retrieved from "https://wiki.mozilla.org/index.php?title=Compatibility/System_Addon/Override_Policies_and_Workflows&oldid=1254225"