Your Search Results

    Developing for Firefox Mobile

    Developing add-ons for Firefox Mobile is still an experimental feature of the SDK. Although the SDK modules used are stable, the setup instructions and cfx commands are likely to change.
    To follow this tutorial you'll need to have installed the SDK and learned the basics of cfx.

    Firefox for Android implements its UI using native Android widgets instead of XUL. With the add-on SDK you can develop add-ons that run on this new version of Firefox Mobile as well as on the desktop version of Firefox.

    You can use the same code to target both desktop Firefox and Firefox Mobile, and just specify some extra options to cfx run, cfx test, and cfx xpi when targeting Firefox Mobile.

    Right now not all modules are fully functional, but we're working on adding support for more modules. The tables at the end of this guide list the modules that are currently supported on Firefox Mobile.

    This tutorial explains how to run SDK add-ons on an Android device connected via USB to your development machine. We'll use the Android Debug Bridge (adb) to communicate between the Add-on SDK and the device.

    It's possible to use the Android emulator to develop add-ons for Android without access to a device, but it's slow, so for the time being it's much easier to use the technique described below.

    Setting up the Environment

    First you'll need an Android device capable of running the native version of Firefox Mobile. Then:

    On the development machine:

    • install version 1.5 or higher of the Add-on SDK
    • install the correct version of the Android SDK for your device
    • using the Android SDK, install the Android Platform Tools

    Next, attach the device to the development machine via USB.

    Now open up a command shell. Android Platform Tools will have installed adb in the "platform-tools" directory under the directory in which you installed the Android SDK. Make sure the "platform-tools" directory is in your path. Then type:

    adb devices

    You should see some output like:

    List of devices attached
    51800F220F01564 device

    (The long hex string will be different.)

    If you do, then adb has found your device and you can get started.

    Running Add-ons on Android

    You can develop your add-on as normal, as long as you restrict yourself to the supported modules.

    When you need to run the add-on, first ensure that Firefox is not running on the device. Then execute cfx run with some extra options:

    cfx run -a fennec-on-device -b /path/to/adb --mobile-app fennec --force-mobile

    See "cfx Options for Mobile Development" for the details of this command.

    In the command shell, you should see something like:

    Launching mobile application with intent name org.mozilla.fennec
    Pushing the addon to your device
    Starting: Intent { act=android.activity.MAIN cmp=org.mozilla.fennec/.App (has extras) }
    --------- beginning of /dev/log/main
    --------- beginning of /dev/log/system
    Could not read chrome manifest 'file:///data/data/org.mozilla.fennec/chrome.manifest'.
    info: starting
    info: starting
    zerdatime 1329258528988 - browser chrome startup finished.

    This will be followed by lots of debug output.

    On the device, you should see Firefox launch with your add-on installed.

    console.log() output from your add-on is written to the command shell, just as it is in desktop development. However, because there's a lot of other debug output in the shell, it's not easy to follow. The command adb logcat prints adb's log, so you can filter the debug output after running the add-on. For example, on Mac OS X or Linux you can use a command like the below to filter only the lines of console output:

    adb logcat | grep console

    You can experiment with different filter strings on adb logcat to focus in on the lines relevant to you.

    Running cfx test is identical:

    cfx test -a fennec-on-device -b /path/to/adb --mobile-app fennec --force-mobile

    cfx Options for Mobile Development

    As you see in the quote above, cfx run and cfx test need four options to work on Android devices.

    -a fennec-on-device This tells the Add-on SDK which application will host the add-on, and should be set to "fennec-on-device" when running an add-on on Firefox Mobile on a device.
    -b /path/to/adb

    As we've seen, cfx uses the Android Debug Bridge (adb) to communicate with the Android device. This tells cfx where to find the adb executable.

    You need to supply the full path to the adb executable.


    This is the name of the Android intent. Its value depends on the version of Firefox Mobile that you're running on the device:

    • fennec: if you're running Nightly
    • fennec_aurora: if you're running Aurora
    • firefox_beta: if you're running Beta
    • firefox: if you're running Release

    If you're not sure, run a command like this (on OS X/Linux, or the equivalent on Windows):

    adb shell pm list packages | grep mozilla

    You should see "package" followed by "org.mozilla." followed by a string. The final string is the name you need to use. For example, if you see:


    ...then you need to specify:

    --mobile-app fennec

    This option is not required if you have only one Firefox application installed on the device.


    This is used to force compatibility with Firefox Mobile, and should always be used when running on Firefox Mobile.

    Packaging Mobile Add-ons

    To package a mobile add-on as an XPI, use the command:

    cfx xpi --force-mobile

    Actually installing the XPI on the device is a little tricky. The easiest way is probably to copy the XPI somewhere on the device:

    adb push my-addon.xpi /mnt/sdcard/

    Then open Firefox Mobile and type this into the address bar:


    The browser should open the XPI and ask if you want to install it.

    Afterwards you can delete it using adb as follows:

    adb shell
    cd /mnt/sdcard
    rm my-addon.xpi

    Module Compatibility

    Modules not supported in Firefox Mobile are marked in the tables below.

    High-Level APIs

    addon-page Not supported
    base64 Supported
    clipboard Not supported
    context-menu Not supported
    hotkeys Supported
    indexed-db Supported
    l10n Supported
    notifications Supported
    page-mod Supported
    page-worker Supported
    panel Not supported
    passwords Supported
    private-browsing Not supported
    querystring Supported
    request Supported
    selection Not supported
    self Supported
    simple-prefs Supported
    simple-storage Supported
    system Supported
    tabs Supported
    timers Supported
    ui Not supported
    url Supported
    widget Not supported
    windows Supported

    Low-Level APIs

    loader Supported
    chrome Supported
    console/plain-text Supported
    console/traceback Supported
    content/content Supported
    content/loader Supported
    content/mod Supported
    content/worker Supported
    core/heritage Supported
    core/namespace Supported
    core/promise Supported
    event/core Supported
    event/target Supported
    frame/hidden-frame Supported
    frame/utils Supported
    io/byte-streams Supported
    io/file Supported
    io/text-streams Supported
    lang/functional Supported
    lang/type Supported
    loader/cuddlefish Supported
    loader/sandbox Supported
    net/url Supported
    net/xhr Supported
    places/bookmarks Not supported
    places/favicon Not supported
    places/history Not supported
    platform/xpcom Supported
    preferences/service Supported
    stylesheet/style Supported
    stylesheet/utils Supported
    system/environment Supported
    system/events Supported
    system/globals Supported
    system/runtime Supported
    system/unload Supported
    system/xul-app Supported
    tabs/utils Supported
    test/assert Supported
    test/harness Supported
    test/httpd Supported
    test/runner Supported
    test/utils Supported
    ui/button/action Not supported
    ui/button/toggle Not supported
    ui/frame Not supported
    ui/id Supported
    ui/sidebar Not supported
    ui/toolbar Not supported
    util/array Supported
    util/collection Supported
    util/deprecate Supported
    util/list Supported
    util/match-pattern Supported
    util/object Supported
    util/uuid Supported
    window/utils Supported


    Document Tags and Contributors

    Contributors to this page: wbamberg, Canuckistani, jsantell
    Last updated by: wbamberg,
    Hide Sidebar