Differences between desktop and Android extensions

Firefox for Android offers a subset of the WebExtensions APIs available to the desktop version of Firefox. Some of these differences are due to the nature of the Android environment and therefore the features Firefox can implement, others are where Firefox for Android does not offer all the desktop features. This article explores these differences and how they affect your add-on development.

A detailed list of the WebExtension APIs supported in Firefox for Android is provided on the Browser support for JavaScript APIs page and details of the supported manifest.json keys are provided on the manifest.json section page.

User interface

Firefox for Android offers a streamlined version of the UI found in desktop Firefox, ensuring Firefox offers an enjoyable and engaging experience on mobile. Some differences relate to how the Android UI differs from the desktop UIs found in Linux, Mac OS, and Windows. For example, Android does not support a windowing environment, and devices do not usually include a physical keyboard from which keyboard shortcuts can be issued. Other differences relate to optimizing usability on smaller mobile device screens.

UI API and manifest.json key differences

As a result of the UI differences, extensions for Firefox for Android do not support the following APIs and manifest.json keys:

• chrome_url_overrides and chrome_settings_overrides manifest.json keys, which means you cannot add custom home and new tab pages.
• commands and the related commands manifest.json key, as Android tablets and smartphones do not usually have a physical keyboard from which ‘commands’ can be issued.
• omnibox and the related omnibox manifest.json key, which means you cannot provide custom address bar suggestions.
• menus, which means you cannot add options to context menus.
• sidebarAction and the related sidebar_action manifest.json key, due to the limited screen real estate on Android devices sidebars, such as the browser history, are presented in full browser tabs. Where possible, you should move any sidebar content to tabs.
• browserAction (Manifest V2), action (Manifest V3), and pageAction add their "button" to the Add-ons item in the Firefox for Android browser menu. Also, popup content opens as an overlay, covering the browser window until the user closes the overlay.

Other related API and manifest.json key differences

There are some other related features that are not supported, these are:

• bookmarks, which means you cannot manipulate the user’s bookmarks, although the user can do this themselves through the UI.
• history, which means you cannot search or manipulate the history of browsed pages.
• sessions, which means you cannot list and restore tabs that have been closed while the browser has been running.
• windows, as there is only one Firefox on Android ‘window’, and the browser cannot open or otherwise manipulate additional browser windows.

Developer tools for Firefox for Android are provided through remote debugging mechanisms over USB or Wi-Fi that connect to the WebIDE on a desktop. Therefore, Firefox for Android does not provide any built-in developer tools and its extensions do not support the APIs to extend the developer tools:

• devtools.inspectedWindow
• devtools.network
• devtools.panels and the related devtools_page manifest.json key.

Effect on your add-on UI

Reveal your add-on

You reveal your add-on as an option under the Add-ons item in the Firefox for Android browser menu. Depending on the manifest version used by your app, you add an option like this:

• for Manifest V2 with the manifest.json browser_action key and browserAction API.
• for Manifest V3 with the manifest.json action key and action API.

Note that the browserAction and action popup content opens as an overlay, covering the browser window until the user closes the overlay.

Work with tabs

You can also manipulate tabs on Firefox for Android. The tabs API enables you to perform most of the actions you can on the desktop, the main exceptions are:

• zoom features, Firefox for Android has one zoom level only, which the user can override with a pinch gesture on the page.
• features related to selecting and moving tabs, again as these features are not supported on Android.
• the ability to detect a tab’s language or muted status.

Execution model

The process model on Android kills idle processes to maintain device performance. Among the processes Android can kill are extension processes. To account for this behavior, extensions should be designed to recover after they have been killed. Event pages, or non-persistent background scripts, are the best mechanism to support this. If your extension uses persistent background script, learn how to convert them to event pages.

Native application interaction

You do not have the ability to interact with native applications as runtime.connectNative() and runtime.sendNativeMessage() are not available.

Permissions

Permissions to use certain WebExtension APIs must be requested in the manifest.json file. On the desktop version of Firefox users are warned when an extension requests a permission and are given the option to deny the add-on that permission. However, on Firefox for Android permissions are granted automatically and the user isn’t given the option to deny them. It is currently planned to resolve this issue in Firefox 57.

Storage

Desktop Firefox supports the local, managed, session, and sync storage areas.

Firefox for Android supports local, session, and sync storage. However, data in sync storage is not synchronized with the user's Mozilla account from Firefox for Android. More details can be found in bug 1625257.

Firefox for Android doesn't support the managed storage area. All calls to StorageArea methods are rejected.