WebExtensions: Difference between revisions

From MozillaWiki
Jump to navigation Jump to search
(lots more updates)
(→‎Additional APIs: Update link to webext experiments)
 
(73 intermediate revisions by 15 users not shown)
Line 1: Line 1:
This page is an introduction to Mozilla's implementation of WebExtensions, a new browser extension API. The goals of this API are:
'''If you are looking for documentation on how to develop an extension with WebExtensions APIs with Firefox, [https://developer.mozilla.org/en-US/Add-ons/WebExtensions please check out MDN].'''
* It should be easier to use.
 
* It must be compatible with multiprocess Firefox ([[Electrolysis]]).
This page is an introduction to Mozilla's implementation of WebExtensions, a new browser extension API; a cross-browser system for developing extensions. The goals of this API are:
* Porting add-ons to and from other browsers should be easier.
* Porting add-ons to and from other browsers should be easier.  
* Reviewing add-ons for addons.mozilla.org (AMO) should be easier.
* Compatibility with multiprocess Firefox ([[Electrolysis]]).
* Changes to Firefox's internal code should be less likely to break add-ons.
* Changes to Firefox's internal code should be less likely to break add-ons.
* It should be easier to review add-ons to reduce the backlog on addons.mozilla.org.
* WebExtensions APIs should be easier to use than the existing Firefox XPCOM/XUL APIs.
* WebExtensions APIs should maintain acceptable security and privacy standards.


Much of the specifics of the new API are similar to the Blink extension API. Google has [https://developer.chrome.com/extensions extensive documentation on the API]. [https://dev.opera.com/extensions/ So does Opera].
Much of the specifics of the new API are similar to the Blink extension API. Google has [https://developer.chrome.com/extensions extensive documentation on the API]. [https://dev.opera.com/extensions/ So does Opera]. But the [https://developer.mozilla.org/en-US/Add-ons/WebExtensions Firefox docs on MDN] are the best.


We hope to ship a preliminary version of this API in Firefox 42.
'''Please note:''' the API is called "WebExtensions" because it can be found in search engines; "Web Extensions" (with a space) does not yield relevant results. Information on terminology usage is available [[Add-ons/Terminology|here]].


== Testing out the WebExtensions API ==
== Status ==
First, you need to set up Firefox:


* download, install, and launch [https://nightly.mozilla.org/ Firefox Nightly].
* Bugs are filed in Bugzilla under WebExtensions, [https://bugzilla.mozilla.org/enter_bug.cgi?format=guided#h=dupes%7CWebExtensions find or create a bug]
* flip the preference that controls whether Firefox allows you to install unsigned add-ons:
** type <code>about:config</code> into the URL bar in Firefox
** in the Search box type <code>xpinstall.signatures.required</code>
** double-click the preference, or right-click and selected "Toggle", to set it to <code>false</code>.


===Example WebExtensions add-on===
=== Useful queries ===
To help get you started, we've created a very simple example add-on at https://github.com/mdn/webextensions-examples. Clone this repo and navigate to the "borderify" directory.
* [https://bugzilla.mozilla.org/buglist.cgi?f1=keywords&list_id=13314909&o1=anywords&query_format=advanced&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&v1=dev-doc-needed&component=Android&component=Compatibility&component=Developer%20Tools&component=Experiments&component=Frontend&component=General&component=Request%20Handling&component=Untriaged&product=WebExtensions Need documentation]
* [https://bugzilla.mozilla.org/buglist.cgi?f1=status_whiteboard&list_id=13314901&o1=substring&resolution=---&query_format=advanced&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&v1=triaged&component=Android&component=Compatibility&component=Developer%20Tools&component=Experiments&component=Frontend&component=General&component=Request%20Handling&component=Untriaged&product=WebExtensions Triaged]
* [https://bugzilla.mozilla.org/buglist.cgi?f1=status_whiteboard&o3=notsubstring&list_id=13314898&v3=intermittent-failure&o1=notsubstring&resolution=---&o2=notsubstring&query_format=advanced&f3=keywords&f2=status_whiteboard&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&v1=triaged&component=Android&component=Compatibility&component=Developer%20Tools&component=Experiments&component=Frontend&component=General&component=Request%20Handling&component=Untriaged&v2=design-decision-needed&product=WebExtensions Untriaged] (note: this is different from the untriaged component)
* [https://bugzilla.mozilla.org/buglist.cgi?f1=status_whiteboard&list_id=13314907&o1=anywordssubstr&resolution=---&query_format=advanced&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&v1=design-decision-needed&component=Android&component=Compatibility&component=Developer%20Tools&component=Experiments&component=Frontend&component=General&component=Request%20Handling&component=Untriaged&product=WebExtensions Design Decision Needed]
* [https://bugzilla.mozilla.org/buglist.cgi?f1=status_whiteboard&list_id=13314907&o1=anywordssubstr&resolution=---&query_format=advanced&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&v1=advisory-group&component=Android&component=Compatibility&component=Developer%20Tools&component=Experiments&component=Frontend&component=General&component=Request%20Handling&component=Untriaged&product=WebExtensions Advisory Group]
* [https://bugzilla.mozilla.org/buglist.cgi?list_id=13314906&resolution=---&query_format=advanced&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&component=Android&component=Compatibility&component=Developer%20Tools&component=Experiments&component=Frontend&component=General&component=Request%20Handling&component=Untriaged&product=WebExtensions All bugs]
* [https://bugzilla.mozilla.org/buglist.cgi?list_id=13315397&resolution=FIXED&chfieldto=Now&query_format=advanced&chfield=cf_last_resolved&chfieldfrom=-17d&bug_status=RESOLVED&bug_status=VERIFIED&bug_status=CLOSED&component=Android&component=Compatibility&component=Developer%20Tools&component=Experiments&component=Frontend&component=General&component=Request%20Handling&component=Untriaged&product=WebExtensions Closed in past 17 days]


  git clone https://github.com/mdn/webextensions-examples
==== Firefox 57 ====
  cd webextensions-examples/borderify/


This directory contains two files: <code>manifest.json</code> and <code>borderify.js</code>.
To keep track of priorities for Firefox 57, we are using the webextensions tracking flag. You can nominate a bug by using the flag with a ?. Bugs that are not on the tracking flag may still be worked but, but will not be a priority. All bugs must have a priority and preferably an assignee. All P1 bugs must have an assignee.


Every WebExtensions add-on must contain a <code>manifest.json</code> file. This one looks like:
* [https://bugzilla.mozilla.org/buglist.cgi?list_id=13377474&o1=equals&v1=%2B&f1=cf_blocking_webextensions&query_format=advanced&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&component=Android&component=Compatibility&component=Developer%20Tools&component=Experiments&component=Frontend&component=General&component=Request%20Handling&component=Untriaged&product=WebExtensions webextensions+]
* [https://bugzilla.mozilla.org/buglist.cgi?list_id=13377455&o1=equals&v1=%3F&f1=cf_blocking_webextensions&query_format=advanced&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&component=Android&component=Compatibility&component=Developer%20Tools&component=Experiments&component=Frontend&component=General&component=Request%20Handling&component=Untriaged&product=WebExtensions webextensions?]


    {
== Communication and meetings ==
     
      "manifest_version": 2,
      "name": "Borderify",
      "version": "1.0",
     
      "applications": {
        "gecko": {
          "id": "borderify@mozilla.org"
        }
      },
     
      "content_scripts": [
        {
          "matches": ["*://*.mozilla.org/*"],
          "js": ["borderify.js"]
        }
      ]
     
    }


* The first three keys are mandatory basic metadata.
* There is a [[Add-ons/Projects#New_WebExtension_APIs|list of prioritized WebExtension APIs]] publicly available as part of [[Add-ons/Projects|ongoing Add-ons work]].
* The next key, <code>"applications"</code>, contains Firefox-specific information.
* There are [https://wiki.mozilla.org/Add-ons/developer/communication developer resources] to help you through the migration.
* The next key, <code>"content_scripts"</code>, specifies a match-pattern and a content script. In this case the pattern matches any pages under <code>mozilla.org</code>, or any of its subdomains. The content script is <code>"borderify.js"</code>.
* Currently every week there is a [https://wiki.mozilla.org/Add-ons/developer/communication#Add-on_Developer_Communication_Calendar public triage meeting] of the bugs we hope to complete.
* Every week there is a [https://wiki.mozilla.org/WebExtensions/Triage triage of WebExtensions APIs].
* Join the mailing list at [https://mail.mozilla.org/listinfo/dev-addons dev-addons@mozilla.org].
* Join us on [[IRC|IRC]] at #webextensions or #addons


The other file is <code>borderify.js</code> itself, which just draws a red border around the document body:
== Testing WebExtensions APIs ==


    document.body.style.border = "5px solid red";
See [https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Your_first_WebExtension Your first extension] on MDN.


===Packaging===
= Technical Details =


Firefox extensions are packaged as XPI files, which are just ZIP files with an "xpi" extension. One trick is that the ZIP file must be a ZIP of the files in the add-on, not of the containing directory. So to create an XPI from the borderify files, at the command prompt type, from inside the `borderify` directory, type:
== Permission Model ==


    # in webextensions-examples/borderify/
We currently enforce [https://developer.chrome.com/extensions/declare_permissions manifest permissions] for [https://developer.mozilla.org/en-US/Add-ons/WebExtensions/API the supported APIs]. We also enforce CSP protections.
    zip ../borderify.xpi *


===Installing===
== Namespacing ==


To install the XPI, you can just open it in Firefox:
At this time, all APIs are accessible through the chrome.* and browser.* namespace. When we begin to add our own APIs, we expect to add them to the browser.* namespace.


* from the File Menu, select Open, or press Ctrl/Cmd+O
== Out-of-process Extensions ==
* select <code>borderify.xpi</code> from the file selection dialog


You should get a warning that you are installing an unsigned extension. Accept the warning.
Extensions developed with WebExtensions APIs are compatible with Electrolysis. They run in the main Firefox process (except for content scripts, which run in the same process as web content). We are considering a plan to run extensions in a separate process (or possibly the content process) eventually, see {{Bugzilla|1190679}} for more details.


Now navigate to a page that matches, such as https://developer.mozilla.org/. You should see a red border appear round the page.
Technical details about the implementation are published at [[WebExtensions/Implementing_APIs_out-of-process]].  


===Experimenting===
Testing details are published at [[WebExtensions/Testing-out-of-process]].
 
Try experimenting:
* change the match-pattern to match different pages.
* change "borderify" to do something else to the page.
* use [[#List_of_supported_APIs|a different API]] to make the add-on do something else.
Each time you change the add-on, you'll need to repeat the [[#Packaging]] and [[#Installing]] sections above.
 
At this time, it is not possible to publish WebExtensions to addons.mozilla.org.


== Packaging ==
== Packaging ==


Extensions are packaged as standard Zip files, but with <code>.xpi</code> extensions. In the future, we're planning to use the <code>.zip</code> extension instead.
Extensions are packaged as standard Zip files, but with <code>.xpi</code> extensions. In the future, we're planning to move towards what the W3C WG recommends.


The <code>manifest.json</code> file supports the following directives, in addition to the directives supported by Blink:
See https://developer.chrome.com/extensions/manifest for a complete list of manifest directives.


<blockquote><pre>
== API support status ==
"applications": {
  "gecko": {
    "id": "{the-addon-id}",
    "strict_min_version": "40.0.0",
    "strict_max_version": "50.*"
    "update_url": "https://foo/bar"
  }
}
</pre></blockquote>


Both version fields are Gecko versions, and allow extension to support any application built on that version of Gecko. In the case of Firefox, they correspond to the Firefox release version.
The list of APIs and their status is now maintained on [https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome_incompatibilities MDN]. We intend to fix any of the exceptions listed there.


The <code>update_url</code> field may point to an [https://developer.mozilla.org/en-US/docs/Extension_Versioning,_Update_and_Compatibility#Update_RDF_Format RDF update manifest] to allow automatic updates.
== Additional APIs ==
 
In the future, we hope to make all of these properties optional (which will require generating a unique ID upon installation or upload to addons.mozilla.org).
 
See https://developer.chrome.com/extensions/manifest for a complete list of manifest directives. Of these, we currently support the following:
 
* name
* version
* description
* content_scripts
* permissions
* web_accessible_resources
* background
* browser_action
* default_locale
 
== List of supported APIs ==
 
Note that we expect to fix virtually all of the exceptions printed below.
 
* [https://developer.chrome.com/extensions/alarms alarms]
** This API is entirely supported.
 
* [https://developer.chrome.com/extensions/browserAction browserAction]
** We don't support the imageData attribute on setIcon.
** We don't support enable or disable.
 
* [https://developer.chrome.com/extensions/extension extension]
** We support only getBackgroundPage and getURL.
 
* [https://developer.chrome.com/extensions/i18n i18n]
** We support only getMessage in the JavaScript API.
** We only support @@extension_id and @@ui_locale predefined messages.
** We don't localize CSS files.
** Strings to be localized must consist entirely of __MSG_foo__ in order for a substitution to be made.
 
* [https://developer.chrome.com/extensions/notifications notifications]
** The only supported notification options are iconUrl, title, and message.
** The only methods we support are create, clear, and getAll.
** The only event we support is onClosed. We don't provide byUser data.
 
* [https://developer.chrome.com/extensions/runtime runtime]
** We support onStartup, getManifest, id, and the message passing interfaces (sendMessage, onMessage, onConnect).
 
* [https://developer.chrome.com/extensions/storage storage]
** The only storage area we support is local.
** We don't support getBytesInUse or clear.


* [https://developer.chrome.com/extensions/tabs tabs]
*If you're experienced with Mozilla infrastructure and would like to develop WebExtensions APIs directly for Firefox, here is a list of [https://mzl.la/2dVs5Ys approved APIs] that you can start contributing to.
** Unsupported functions: getCurrent, sendRequest, getSelected, duplicate, highlight, move, detectLanguage, captureVisibleTab, get/setZoom, get/setZoomSettings. We probably will never support detectLanguage.
** We treat highlighted and active as effectively the same since Firefox cannot select multiple tabs.


* [https://developer.chrome.com/extensions/webNavigation webNavigation]
*If you'd like to become familiar with Mozilla infrastructure so you can develop WebExtensions APIs directly for Firefox, follow these steps:
** We don't support getFrame or getAllFrames.
**Familiarize yourself with the on-boarding materials: [http://areweeveryoneyet.org/onramp/desktop.html Onboard to Firefox codebase]
** We don't support onCreatedNavigationTarget or onHistoryStateUpdated.
**Pick a [https://bugzilla.mozilla.org/buglist.cgi?quicksearch=product%3AWebExtensions%20keyword%3Agood-first-bug&list_id=13160623 "Good First Bug"] to work on
** We don't support transition types and qualifiers.
** onReferenceFragmentUpdated also triggers for pushState.
** Filtering is unsupported.


* [https://developer.chrome.com/extensions/webRequest webRequest]
*If you just want to tinker with WebExtensions APIs without having to build Firefox, [https://firefox-source-docs.mozilla.org/toolkit/components/extensions/webextensions/basics.html#adding-experimental-apis-in-privileged-extensions WebExtensions Experiments] is for you!
** We don't support handlerBehaviorChanged.
** We don't support onAuthRequired, onBeforeRedirect, or onErrorOccurred.
** Requests can be canceled only in onBeforeRequest.
** Requests can be modified/redirected only in onBeforeSendHeaders.
** Responses can be modified only in onHeadersReceived.


* [https://developer.chrome.com/extensions/windows windows]
*If you simply want to request a WebExtensions API, please [[WebExtensions/NewAPIs|read this information]] before filing a bug.
** onFocusChanged will trigger multiple times for a given focus change.
** create does not support the focused, type, or state options.
** update only supports the focused option.


== List of APIs we will likely support in the future ==
== Contributing ==


* [https://developer.chrome.com/extensions/bookmarks bookmarks]
Please see the [[WebExtensions/Hacking|hacking guide]] for information about contributing code to the WebExtensions project.
* [https://developer.chrome.com/extensions/commands commands]
* [https://developer.chrome.com/extensions/contextMenus contextMenus]
* [https://developer.chrome.com/extensions/cookies cookies]
* [https://developer.chrome.com/extensions/downloads downloads]
* [https://developer.chrome.com/extensions/history history]
* [https://developer.chrome.com/extensions/idle idle]
* [https://developer.chrome.com/extensions/omnibox omnibox]
* [https://developer.chrome.com/extensions/pageAction pageAction]
* [https://developer.chrome.com/extensions/permissions permissions]


== Technical details ==
Please see https://webextensions-experiments.readthedocs.io/en/latest/ for some information on Experiments which might be useful for contributing.
 
We currently enforce Chrome's permission model. However, we don't yet support the activeTab permission. We also don't enforce the CSP protections at all. Support for that is planned.
 
WebExtensions run in the main Firefox process (except for content scripts, which run in the same process as web content). We are planning to run extensions in a separate process (or possibly the content process) eventually.
 
== Additional APIs ==


We plan to add our own APIs based on the needs of existing Firefox add-ons.
Here is a list of all [https://wiki.mozilla.org/Add-ons/Contribute add-on contribution opportunities].


* NoScript-type functionality. This would come in the form of extensions to webRequest and possibly contentSettings.
== Frequently-Asked Questions ==
* Sidebars. Opera already supports sidebar functionality; Chrome may soon. We would like to be able to implement Tree Style Tabs or Vertical Tabs by hiding the tab strip and showing a tab sidebar.
You can find more information about WebExtensions on [[WebExtensions/FAQ|our FAQ page]].
* Toolbars. Firefox has a lot of existing toolbar add-ons.
* Better keyboard shortcut support. We'd like to support Vimperator-type functionality.
* Ability to add tabs to about:addons.
* Ability to modify the tab strip (Tab Mix Plus).
* Ability to take images of frames/tabs (like canvas.drawWindow)

Latest revision as of 10:38, 9 July 2024

If you are looking for documentation on how to develop an extension with WebExtensions APIs with Firefox, please check out MDN.

This page is an introduction to Mozilla's implementation of WebExtensions, a new browser extension API; a cross-browser system for developing extensions. The goals of this API are:

  • Porting add-ons to and from other browsers should be easier.
  • Reviewing add-ons for addons.mozilla.org (AMO) should be easier.
  • Compatibility with multiprocess Firefox (Electrolysis).
  • Changes to Firefox's internal code should be less likely to break add-ons.
  • WebExtensions APIs should be easier to use than the existing Firefox XPCOM/XUL APIs.
  • WebExtensions APIs should maintain acceptable security and privacy standards.

Much of the specifics of the new API are similar to the Blink extension API. Google has extensive documentation on the API. So does Opera. But the Firefox docs on MDN are the best.

Please note: the API is called "WebExtensions" because it can be found in search engines; "Web Extensions" (with a space) does not yield relevant results. Information on terminology usage is available here.

Status

Useful queries

Firefox 57

To keep track of priorities for Firefox 57, we are using the webextensions tracking flag. You can nominate a bug by using the flag with a ?. Bugs that are not on the tracking flag may still be worked but, but will not be a priority. All bugs must have a priority and preferably an assignee. All P1 bugs must have an assignee.

Communication and meetings

Testing WebExtensions APIs

See Your first extension on MDN.

Technical Details

Permission Model

We currently enforce manifest permissions for the supported APIs. We also enforce CSP protections.

Namespacing

At this time, all APIs are accessible through the chrome.* and browser.* namespace. When we begin to add our own APIs, we expect to add them to the browser.* namespace.

Out-of-process Extensions

Extensions developed with WebExtensions APIs are compatible with Electrolysis. They run in the main Firefox process (except for content scripts, which run in the same process as web content). We are considering a plan to run extensions in a separate process (or possibly the content process) eventually, see 1190679 for more details.

Technical details about the implementation are published at WebExtensions/Implementing_APIs_out-of-process.

Testing details are published at WebExtensions/Testing-out-of-process.

Packaging

Extensions are packaged as standard Zip files, but with .xpi extensions. In the future, we're planning to move towards what the W3C WG recommends.

See https://developer.chrome.com/extensions/manifest for a complete list of manifest directives.

API support status

The list of APIs and their status is now maintained on MDN. We intend to fix any of the exceptions listed there.

Additional APIs

  • If you're experienced with Mozilla infrastructure and would like to develop WebExtensions APIs directly for Firefox, here is a list of approved APIs that you can start contributing to.
  • If you'd like to become familiar with Mozilla infrastructure so you can develop WebExtensions APIs directly for Firefox, follow these steps:

Contributing

Please see the hacking guide for information about contributing code to the WebExtensions project.

Please see https://webextensions-experiments.readthedocs.io/en/latest/ for some information on Experiments which might be useful for contributing.

Here is a list of all add-on contribution opportunities.

Frequently-Asked Questions

You can find more information about WebExtensions on our FAQ page.

Retrieved from "https://wiki.mozilla.org/index.php?title=WebExtensions&oldid=1251254"