One strategy for making web apps compete better with native platforms is the provision of functionality to allow them to be installed on devices. The advantages of this include making them available offline, access to device APIs for controlling hardware functionality, and better integration with the underlying system. Much of this functionality is not standardized yet, but efforts are underway from Google, Mozilla, Tizen, and more.

This section of MDN provides a detailed reference on web app development topics specific to creating apps that are installable on Firefox OS (and other Firefox-supported platforms like Android), including app manifests, writing install functionality, permissions for using device APIs, and more.

Note: If you are completely new to Firefox OS apps, start off with our Firefox OS app essentials guide — this provides a beginner's guide to the specifics of open web/Firefox OS apps. There is also a very useful screencast series available, if you prefer watching videos — App Basics for Firefox OS.

Firefox OS

Firefox OS (also referred to by its codename Boot to Gecko — or B2G) is Mozilla's open source mobile operating system. It's based on a Linux kernel, which boots into a Gecko-based runtime that lets users install and run open web apps, Gecko being the rendering engine that the Firefox browser uses to render and display web content.

Firefox OS comes with Gaia, which forms the entire UI layer of Firefox OS and the default suite of apps that handle the fundamental functions of the phone such as settings, calls, SMS, taking and storing photos, etc.

Mozilla's open web apps are installable on Firefox OS, and other Firefox-supported platforms via Mozilla's web run time technology. For more details, see Open web apps for Android, and Open web apps for Desktop.) In future, the technologies should be standardized and adopted across a wider range of platforms.

Installable app workflow

An installable open web app is very similar to a normal web app or web site — it is built using familiar web technologies like HTML, CSS and JavaScript. The difference is in the additional features the Firefox (OS) platform has available. The following diagram illustrates how those features work together.

Start with a fairly standard web application, built using your favourite toolchain.

Package and distribute your app. This can be done in a variety of ways, from simple self-published hosted apps (in which case you'd have to write your own install functionality), to packaged apps distributed via the Firefox Marketplace (which handles the install functionality for you.)

Recommendations

This section provides recommendations and best practices for creating installable open web apps.

Web app manifest files

Your app's manifest.webapp file should be placed in the root of your app directory, and contain a simple JSON structure, as explained in detail in our App Manifest reference. A simple App Manifest JSON looks like so:

For simple apps, this is all you'll need, but you may also need other fields, as discussed in appropriate places below.

Functionality, Device APIs, and permissions

One of the main strengths of the Firefox OS platform is the provision of new Web APIs to access key device services like the contacts, and hardware like NFC, Bluetooth and SMS. There are many examples of the different new APIs available along with examples throughout our App Center Build section, but in this section we'll give you some specific pointers towards tasks you might want to accomplish with them. Common task categories include:

Different APIs have different levels of security, with some APIs being limited in who can access them. This makes sense — it would be really insecure to just let any app have access to say, a device's SMS and dialer functionality. The different levels are as follows:

Common: Common APIs like Notification, getUserMedia, IndexedDB, and Geolocation don't need any special privileges to use them. Some of these APIs have an extra level of security anyway, for example a getUserMedia or Geolocation call will result in the user being shown a confirmation box to ask if they are happy with an app accessing their GPS or web cam.

Privileged: Privileged APIs have more security implications than common ones, and as such can only be used by packaged apps that have been verified by the Firefox Marketplace (see below). These include the Camera, Browser, Contacts and TCP Socket APIs.

Certified: Certified APIs are generally critical in terms of device security, and therefore only usable in apps pre-installed on the device by Mozilla or the device vendor. These include the SMS, Bluetooth, and Dialer APIs.

To request permission to use a restricted API, you have to include a permissions field in your manifest file, and set the type field to privileged in the case of privileged APIs. These fields will look something like this:

Note: You can find out exactly what permissions (if any) each API requires by looking at our App permissions reference; this reference also lists which version of Firefox OS supports each API. To find out what API features are new as of each version of Firefox OS, consult our Firefox OS developer release notes.

Using Web activities also requires that you specify their type and required data in the activities field, for example:

Lastly, some APIs such as the Alarm and Notification APIs also require you to specify a messages field, which details what kind of system messages are to be captured by the app, and what page(s) will handle them:

Icons and other design best practices

The best practices you would use for creating a Firefox OS app are pretty much the same as those you would use for creating any standard web app, in terms of both coding and design.

You should use responsive design techniques to make sure your app layout will work well on a variety of screen sizes, especially media queries and viewport. Because many devices have high resolution screens these days, this should include use of resolution media queries to optimize for different resolutions.

You should take advantage of the building blocks and design patterns we've made available (see our app Design section.)

You should also make sure to optimize your code as much as possible so it is more likely to work on low-memory devices, which many Firefox OS devices are (see our Performance topic).

For the visual design of Firefox apps, you are free to follow your own path, but you could certainly get some useful pointers from our Firefox OS style guide.

For your app icons, you should make sure to include at least a 512x512 icon and a 128x128 icon. Read Icon implementation for Apps for more information.

App packaging, installation and distribution

When an App is ready to be distributed, you have a few options of how to publish them:

You can self-publish a hosted app. This requires you to simply upload your app to a web server, just like you would for a normal web site, and include the manifest, icons, etc. that the installable app needs. In addition, you need to include some code to install your app on a Firefox OS device or other device where Firefox is present. This will generally take the form of a <button> element that when pressed invokes the Apps.install method, passing it the URL of the manifest file. Note that hosted apps, even when installed, are always run from the web site they are hosted on, so don't confer the ability to run offline, unless you provide this ability using a technology like AppCache (or soon, Service Workers.)

You can self-publish a packaged app. This requires you to zip your app up, and upload your zip to a web server, after making sure you've included included the manifest, icons, etc. that the installable app needs. In addition, you need to include a mini-manifest file in the same directory as the zip to reference the app, and some code to install your app on a Firefox OS device or other device where Firefox is present. This will generally take the form of a <button> element that when pressed invokes the Apps.installPackage method, passing it the URL of the mini-manifest file.

Note: Another common cause of failure in app installation is incorrect paths in manifests and install code. These paths should be relative to the origin of the server location. So for example, if your example's root is at http://www.mysite.com/myapp/, and your icon is at http://www.mysite.com/myapp/manifest.webapp, the install path would be /myapp/manifest.webapp, not /manifest.webapp.

Note: Installable open web apps used to have a "single app per origin" security policy, but this was lifted as of Firefox 34/Firefox OS 2.1 (read this FAQ entry for more information). If you still need to support older versions, consider hosting your apps at separate origins; one strategy is to create different subdomains for your apps.

Multi-locale apps

You can create multi-locale apps quite easily. This is done by:

Adding special data-l10n-id attributes to each HTML element that requires localization, the value of which should be an identifier for that string. For example:

<h1 data-l10n-id="app-title">My app</h1>.

Including the l10n.js library in your page using a regular <script> element.

Creating a locales folder inside your app directory containing a folder for each separate locale, then placing an app.properties file inside each one containing that language's translations, each one on a new line. For example app-title = Mon application for French.

Creating a locales.ini file inside the locales folder, which specifies the default locale and the path to each app.properties file. This will look like so:

@import url(en/app.properties)
[es]
@import url(fr/app.properties)

Referencing locales.ini from your HTML file using a <link> element, like so:

Debugging apps

Mozilla provides a number of tools to help you test Firefox OS apps.

Testing on Firefox desktop

The quickest way to test your app's basic functionality is to simply load it in Firefox desktop (open the index.html file in the browser) — this supports most of the features you'll be using to develop your app (with the exception of some of the device APIs.) From here you can use the standard Firefox Toolbox to debug your code, and the Responsive Design View to test responsive/mobile layouts.

Testing in the Firefox OS simulator

You can also test the app in a Firefox OS simulator via our App Manager tool (and soon, on our all-new WebIDE tool). This will give you a more realistic idea of how it will look on a real device.

Note: Our new WebIDE tool is currently only available in Firefox Nightly, but will be rolled out across all versions soon. It does everything App Manager does and more, including in-app code editing, creation of new apps, and tools like the Monitor, which enables to track performance across an app's lifespan.

Testing on a Firefox OS device

Some device APIs — such as the vibration API — can't be tested successfully on a simulator. To fully test this you'll need to get hold of a real Firefox OS device. If you've got one, you can connect it to your computer and install apps contained on your local drive straight onto it via the App Manager/WebIDE.

Logcat

The Android adb logcat tool is very useful for getting debugging output from a Firefox OS device, if you are comfortable with command line tools. For example, you can get info on dying apps using the following:

Supporting cross-Firefox OS versions

Note that when developing apps for Firefox OS, you need to bear in mind what platform versions will be available on the devices your customers will have (see our available phones table for a list.) Remember that it is not as simple to update phone platform software as it is desktop software — users tend to be at the mercy of the network providers. You therefore need to develop apps to support these versions. As an example, multiline Flexbox doesn't work on Firefox OS versions below 1.3, so you may need to use a simpler layout method or provide a fallback for older versions.

This issue should go away soon, as more consumer Firefox OS devices appear, equipped with newer versions of Firefox OS out of the box.

The current baseline platform we recommended developing for is Firefox OS 1.1.

Advanced topics

Reference

This page provides a list of useful tools, libraries and examples that are useful for Firefox OS app developers, whether you want an code template to copy, or need help with adding a specific feature to your Firefox OS app.

Unlike traditional web sites, privileged and certified apps enforce a CSP (content security policy) by default. This may cause quite a bit of existing code to break while porting and cause a significant amount of confusion if developers are unaware that the CSP exists. This article explains what the restrictions imposed by the open web app CSP are.