注意： This article discusses building cross-browser extensions for manifest v2. At the time of writing (December 2021), manifest v3 is being introduced by the major browser vendors. Manifest v3 is likely to change the way cross-browser extension development is undertaken. However, work on Manifest v3 is not complete. The major browser vendors are collaborating (with community members) to ease the development of a cross-browser extension in the W3C WebExtensions Community Group .
The introduction of the browser extensions API created a uniform landscape for the development of browser extensions. However, there are differences in the API implementations and the scope of coverage among the browsers that use the extensions API (the major ones being Chrome, Edge, Firefox, Opera, and Safari).
Maximizing the reach of your browser extension means developing it for at least two browsers, possibly more. This article looks at six of the main challenges faced when creating a cross-browser extension and suggests how to address these challenges.
There are six areas you need to address when tackling a cross-platform extension:
There are two API namespaces in use among the main browsers:
browser.*
, the proposed standard for the extensions API used by Firefox and Safari.
chrome.*
used by Chrome, Opera, and Edge.
Firefox also supports the
chrome.*
namespace for APIs that are compatible with Chrome, primarily to assist with
porting
. However, using the
browser.*
namespace is preferred. In addition to being the proposed standard,
browser.*
uses promises—a modern and convenient mechanism for handling asynchronous events.
Only in the most trivial extensions is namespace likely to be the only cross-platform issue that has to be addressed. Therefore, it’s rarely, if ever, helpful to address this issue alone. The best approach is to address this with asynchronous event handling.
There are two approaches to handling asynchronous events in use among the main browsers:
Firefox also supports callbacks for the APIs that support the
chrome.*
namespace. However, using promises (and the
browser.*
namespace) is recommended. Promises have been adopted as part of the proposed standard. It greatly simplifies asynchronous event handling, particularly where you need to chain events together.
注意： If you’re unfamiliar with the differences between these two methods, take a look at Getting to know asynchronous JavaScript: Callbacks, Promises and Async/Await or the MDN Using promises 页面。
So, how do you take advantage of promises easily? The solution is to code for Firefox using promises and use the WebExtension browser API Polyfill to address Chrome, Opera, and Edge.
This polyfill addresses the API namespace and asynchronous event handling across Firefox, Chrome, Opera, and Edge.
To use the polyfill, install it into your development environment using npm or download it directly from GitHub releases .
Then, reference
browser-polyfill.js
in:
manifest.json
, to make it available to background and content scripts.
browserAction
popups or tab pages.
executeScript
call in dynamically-injected content scripts loaded by
tabs.executeScript
, where it hasn’t been loaded using a
content_scripts
declaration in
manifest.json
.
So, for example, this
manifest.json
code makes the polyfill available to background scripts:
{
// ...
"background": {
"scripts": [
"browser-polyfill.js",
"background.js"
]
}
}
Your goal is to ensure that the polyfill executes in your extension before any other scripts that expect the
browser.*
API namespace execute.
注意： For more details and information on using the polyfill with a module bundler, see the project’s readme on GitHub.
There are other polyfill options. However, at the time of writing, none of the other options provide the coverage of the WebExtension browser API Polyfill. So, where you haven’t targeted Firefox as your first choice, your options are to accept the limitations of alternative polyfills, port to Firefox and add cross-browser support, or develop your own polyfill.
The differences in the API functions offered in each of the main browsers fall into three broad categories:
browserSettings
函数。
notifications.onButtonClicked
, while Firefox is the only browser that supports
notifications.onShown
.
contextualIdentities
函数。
Details about the support for the extension APIs among the main browsers and Firefox for Android and Safari on iOS can be found on the Mozilla Developer Network Browser support for JavaScript APIs page. Browser compatibility information is also included with each function and its methods, types, and events in the Mozilla Developer Network JavaScript API reference pages.
A simple approach to addressing API differences is to limit the functions used in your extension to functions that offer the same functionality across your range of targeted browsers. In practice, this approach is likely to be too restrictive for most extensions.
Instead, where there are differences among the APIs, you should either offer alternative implementations or fallback functionality. (Remember: you may also need to do this to allow for differences in API support between versions of the same browser.)
The use of runtime checks on the availability of a function’s features is the recommended approach to implementing alternative or fallback functionality. The benefit of performing a runtime check is that you don’t need to update and redistribute the extension to take advantage of a function when it becomes available.
The following code enables you to perform a runtime check:
if (typeof <function> === "function") {
// safe to use the function
}
The differences in the
manifest.json
file keys supported by the main browsers fall broadly into three categories:
developer
key for details about the developer of the extension.
browser_specific_settings
key.
"manifest_version"
,
"version"
，和
"name"
are mandatory keys.
Browser compatibility information is included with each key in the Mozilla Developer Network
manifest.json
key reference pages
.
As
manifest.json
files tend to change little—except for release numbers, which may differ between the various browsers—creating and editing a static version for each browser is usually the simplest approach.
Packaging an extension for distribution through the browser extension stores is relatively straightforward. Firefox, Chrome, Edge, and Opera all use a simple zip format that requires the
manifest.json
file to be at the root of the zip package. Safari requires extensions to be packaged in a similar way to apps.
For details on packaging, refer to the guidance on the respective extension’s developer portals.
Each of the major browsers maintains browser extension stores. Each store also reviews your extension to check for security vulnerabilities.
As a consequence, you need to approach adding and updating your extension for each store separately. In some cases, you can upload your extension using a utility.
This table summarizes the approach and features of each store:
| Browser | Registration fee | Upload utility | Pre-publication review process | Account two-factor authentication |
|---|---|---|---|---|
| Chrome | Yes | Yes | Automatic, less than an hour | Yes |
| Edge | No | No | No SLA provided | Yes |
| Firefox | No | web-ext |
Automatic, a few seconds. A manual review of the extension takes place after publication, which may result in the extension being suspended where issues that need fixing are found. |
Yes |
| Opera | No | No | Manual, no SLA provided | No |
| Safari | Yes | No | Yes with, according to Apple, on average, 50% of apps reviewed in 24 hours and over 90% reviewed in 48 hours. | Yes |
The Firefox, Chrome, and Edge stores require that each uploaded version has a different version number. This means you cannot revert to an earlier version number if you come across issues in a release.
When approaching a cross-platform extension development, the differences between extension API implementations can be addressed by targeting Firefox and using the WebExtension browser API Polyfill . Following this approach, you benefit from using API features that are closely aligned with the proposed extensions API standard and gain the simplicity of promises for asynchronous event handling.
The bulk of your cross-platform work is likely to focus on handling variations among the API features supported by the main browsers. Creating your
manifest.json
files should be relatively straightforward and something you can do manually. You will then need to account for the variations in the processes for submitting to each extension store.
可以使用 browser-extension-template to quickly set up a working project for building and publishing a browser extension.
Following the advice in this article, you should be able to create an extension that works well on all of the four main browsers, enabling you to deliver your extension features to more people.
最后修改： , 由 MDN 贡献者