Using the App Manager
Important: The App Manager should be considered deprecated; work has begun to remove the App Manager code from Firefox (see bug 1007061), and you really use WebIDE instead, unless you have a really good reason not to.
The App Manager is a tool for Firefox Desktop which provides a number of useful tools to help developers test, deploy and debug HTML5 web apps on Firefox OS phones & Simulator, directly from Firefox browser. This page documents how to use the App Manager.
App Manager is available for Firefox OS 1.2 or later, lower versions are supported in Firefox OS 1.1 Simulator. The App Manager is being replaced by the WebIDE, starting from Firefox 33. The WebIDE provides all the features of the App Manager and also features an editing environment to create and develop Firefox OS apps.
The App Manager is composed of:
- An Apps panel, which manages local apps (app source code located on your computer) and apps hosted externally, allowing you to package and install them on your device or simulator, and debug them using Toolboxes
- A Device panel, which displays information about the connected device including Firefox OS version installed, permissions required for using device APIs on the device, and apps installed
- Toolboxes, which are are sets of developer tools (web console, inspector, debugger, etc.) that can be connected to a running app via the Apps panel to perform debugging operations
This section is designed to get you up and running as soon as possible; if you need some more detail please skip forward to the Device and system configuration section and start reading from there. Also see the Troubleshooting section for help if you are having trouble.
- Make sure you have Firefox Desktop 26+ installed
- Open the App Manager (in the URL bar, type
about:app-manager, or go to Tools > Web Developer > App Manager in your Firefox menu.) This should appear in a new browser tab.
- If you don't have a real device:
- Install the Firefox OS Simulator add-on, then go back to the App Manager tab of your browser.
- In App Manager's bottom toolbar, click on Start Simulator, then click on the name of the installed simulator, which should appear there.
- If you have a real device:
- Make sure your device is running Firefox OS 1.2+
- On Windows, make sure to install the drivers provided by your phone manufacturer
- In the Settings of your device, disable Screen Lock (
Settings > Phone lock >) and enable Remote Debugging (
Settings > Device information > More information > Developer)
- Install the ADB Helper add-on in Firefox Desktop
- Connect your device to your machine via a USB cable
- You should see the name of your device in the App Manager's bottom bar. Click on it.
- The bottom bar should show "Connected to: xxx"
- Click on the Apps panel and add an app (packaged or hosted)
- The Refresh button validates your app and installs it on the Simulator/Device
- The Debug button connects the developer tools to the running app
- See the Troubleshooting section for help if you are having trouble
The first thing you'll need to do when using the App Manager is make sure your system and phone are set up correctly. This section will run through all the steps required.
Make sure your device is running Firefox OS 1.2/Boot2Gecko 1.2 or higher. To check which version of Firefox OS the device is runing, go to
Settings > Device Information > Software.
If you don't have a high enough version installed, depending on what phone you have you will need to either install an available nightly build of Firefox 1.2+, or configure and build it yourself from source.
- Geeksphone Keon/Peak builds (to find out more about using these, read Updating and Tweaking your Firefox OS Developer Preview phone/Geeksphone)
- More to follow
Next, you need to enable remote debugging in Firefox OS. To do so, go to
Settings > Device information > More information > Developer and check the Remote Debugging checkbox.
The process uses the Android Debug Bridge (ADB) to handle the device-computer connection and communication. There are two options for running ADB:
Let Firefox handle ADB (recommended). Install the ADB Helper add-on, which makes the process easier. With this installed, there's no need to install the ADB, and no need to type theDownload ADB Helper Add-on
adb forwardcommand: everything is handled by the add-on.
- Use ADB manually. You need to have it installed on your computer: download and install
adbas explained in Installing ADB. You'll need to enable port forwarding by entering the following command into your terminal:
adb forward tcp:6000 localfilesystem:/data/local/debugger-socketNote that you'll need to do this every time the phone is restarted or unplugged then re-plugged.
Note: There's no need to run this command if you installed the ADB Helper Add-on.
With all your configuration done, it's now time to plug your device into your computer and start the App Manager:
- Plug the device into your computer via USB.
- Disable Screen lock on your device by going to
Settings > Screen Lockand unchecking the
Lock Screencheckbox. This is a good idea because when the screen gets locked, the phone connection gets lost, meaning it is no longer available for debugging.
- Start the App Manager — In Firefox Desktop select the
Tools > Web Developer > App Managermenu option, or type
about:app-managerin the URL bar.
- At the bottom of the App Manager tab, you will see a connection status bar (see screenshot below). You should be able to connect your device by clicking the "Connect to localhost:6000" button.
- If this works successfully, a prompt should appear on your device: "An incoming request to permit remote debugging connection was detected. Allow connection?". Tap the OK button (You may also have to press the power button on the phone so you can see the prompt.) The connection status bar should update to say "Connected to B2G", with a Disconnect button available to press if you want to cancel the connection.
Note: The other controls in the connection status bar allow you to connect a simulator to the App Manager, which we cover in the next section, below, and change the port that the connection happens on. If you change the port, you'll also need to enable port forwarding for this port as well, as instructed in the Enable port forwarding section, above.
If you haven't got a real device available to use with App Manager, you can still try it out using a Firefox OS Simulator Add-on. To start off, install the simulator with the following button (multiple versions are available; you are advised to install them all, for maximum flexibility):
Once you've installed the simulator(s), you need to go to about:app-manager to see the connection status bar at the bottom of the App Manager tab, and click the "Start simulator" button. At least three buttons will appear:
- "Firefox OS 1.3", "Firefox OS 1.2" ... etc. (or something similar): the left-most buttons contain the names of the simulator versions you have installed. Click one to start a connection to a simulator.
- "Add": the middle button navigates to the simulator install links in this article, so you can add more Simulators (Firefox OS 1.3, Firefox OS 1.4, etc.)
- "Cancel": the right hand button cancels the connection.
Note: The Firefox OS 1.5 Simulator has been removed, as 1.5 was changed to 2.0. If you have the Firefox OS 1.5 Simulator installed, it won't automatically update to 2.0, so you should uninstall 1.5 and install 2.0 instead. The Firefox OS 2.0 simulator will then automatically update.
Note: The Firefox OS 1.2 Simulator has been removed, as no phones are likely to be released with version 1.2 installed — this version is therefore of limited value, and it makes more sense to spend your time debugging on other versions.
Note that you can run custom B2G Desktop and Gaia/Gecko builds in the App Manager via the simulator. Read Running custom Firefox OS/Gaia builds in the App Manager for instructions on how to do this.
Apps panel: Test and debug Firefox OS apps
Now that everything is working, let's review the functionality available inside the App Manager, starting with the Apps panel. From here, you can import an existing app to push onto your device, for testing and debugging:
- To install a locally stored app, click on the plus next to the "Add Packaged App" label and use the resulting file chooser dialog to select the directory your app is contained inside.
- To install an externally hosted app, enter the absolute URL of the app's manifest file into the text field inside the "Add Hosted App" box, then press the plus button.
Information about your app should appear on the right hand side of the window, as seen below:
From Firefox 28 onwards, the Apps Panel includes an editor for the app manifest:
Clicking on "Update" will update (install) the app on the device. Clicking on "debug" will connect a toolbox to the app, allowing you to debug its code directly:
You'll enjoy playing around with the toolbox — try altering the DOM, CSS etc. and you'll see the updates reflected on the device in realtime. Such updates will be saved on the installed app code; you'll see them next time you open the app on the device.
Before Firefox 28, the tools are launched in a separate window. From Firefox 28 onwards, the tools are launched in a separate tab in the App Manager itself, alongside the Apps and Device tabs. The tab is given your app's icon so it's easy to find:
If an app was not added successfully — for example if the URL was incorrect, or you selected a packaged app folder — an entry will be added to the page for this app, but this will include error information.
You can also delete an app from this view, by hovering over the App name/description on the left of the window, and pressing the "X" button that appears in each case. This however doesn't remove the app from the device. To do that you need to manually remove the app using the device itself.
The Device tab displays information about the connected device. From the "Installed Apps" window, apps on the device can be started and debugged.
Note: Certified Apps are not listed by default. See how to debug certified apps.
The "Permissions" window shows the required privileges for different Web APIs on the current device:
Finally, you can take a screenshot of the current device display by clicking the "Screenshot" button. The screenshot appears in a new tab on Firefox, and from there you can save or discard it as you wish.
Currently only devices running a development build of Firefox OS 1.2+ are capable of debugging certified apps. If you have a development build, you can enable certified app debugging by changing the pref
false in your profile. To do this, follow the steps below:
On your computer, enter the following command in Terminal/console to enter your device's filesystem via the shell:
Your prompt should change to
Next, stop B2G running using the following command:
Navigate to the following directory:
Here, update the prefs.js file with the following line:
echo 'user_pref("devtools.debugger.forbid-certified-apps", false);' >> prefs.js
After you've finished editing and saving the file, start B2G again using the following command:
Exit the android filesystem using the
exitcommand; this will return you to your normal terminal prompt.
Next, reconnect to the App Manager and you should see certified apps appear for debugging.
With the B2G desktop client, the preference is already defined in your profile in
greprefs.js, located at the root of your B2G desktop client folder. Stop your B2G desktop client and edit the file to turn the
devtools.debugger.forbid-certified-apps preference to
false. Then restart the B2G client and connect the App Manager. You should now see all applications.
Note: If you want to add this preference to your Gaia build you can run
make DEVICE_DEBUG=1 reset-gaia.
If the device is not recognized:
- If clicking the button corresponding to your Firefox OS phone doesn't do anything, make sure you haven't connected an Android phone at the same time as the Firefox OS phone to your computer.
- Read the Device and system configuration section thoroughly, and make sure all the steps are followed:
- Is your device running at least Firefox OS 1.2?
- Don't see all the apps? Do you need to enable Certified Apps debugging?
- Did you enable "Remote Debugging" in the settings of your phone?
- If you are not using the ADB Helper add-on:
- Did you successfully run the
- Did you successfully run the
- If you are using the ADB Helper add-on and your device is not listed in the bottom toolbar:
- If you use Linux, make sure to setup udev correctly
- If you use Windows, make sure to install the appropriate drivers
- You can also enable verbose logging to gather diagnostics:
- Use about:config to set the pref " to the string value "all"
- Disable and re-enable the ADB Helper add-on from the add-ons manager, or restart Firefox
- Open the App Manager again
- In the Browser Console, you should now see additional output lines that mention "adbhelper"
- If you see them but aren't sure what they mean, stop by the #devtools room on IRC or file a bug with the log output
- See "???????" instead of the device name on Linux? You have permissions issues. Make sure to setup udev correctly.
- Is your phone screen unlocked?
- If the command "adb devices" shows no entries even though the phone is connected and unlocked, you may have to edit adb_usb.ini.
- Try with only the phone connected to your computer and nothing else. If the command "adb devices" shows multiple entries, you may have a second device that's causing troubles and needs to be removed (including an emulated device, eg BlueStacks, which may need its processes manually terminated).