Building apps for Firefox OS

Firefox OS apps have a low barrier for entry, especially for existing web developers and mobile developers; they are also a lot more portable across platforms than native equivalents, and not locked into walled gardens. As we've already mentioned Firefox OS apps are based on web technologies — HTML, CSS, and JavaScript — so if you've written a web page you already know the basics. Even if you don't have the basics you'll be able to easily follow this guide, but you may want to check out our list of Beginner's tutorials to learn more about developing with open web technologies.

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. It is targeted towards experienced developers that are just looking to create or port an existing app to 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.

1. Start with a fairly standard web application, built using your favourite toolchain.
2. Identify this as an installable web app by adding a manifest.webapp file to the web app root directory. This defines a number of things about the app such as its name, icons, localization information, and probably most importantly the permissions the app needs to access device APIs such as Camera, Device Storage, Bluetooth and SMS.
3. Create any functionality you require that makes use of special device APIs.
4. Create the assets your app needs, such as the icons.
5. 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:

{
  "name": "My App",
  "description": "My elevator pitch goes here",
  "launch_path": "/index.html",
  "icons": {
    "512": "/img/icon-512.png",
    "128": "/img/icon-128.png"
  },
  "developer": {
    "name": "Your name or organization",
    "url": "https://your-homepage-here.org"
  },
  "default_locale": "en"
}

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:

• Gathering and modifying data: Retrieving data from files, device hardware (e.g. battery, proximity, light sensor, GPS) and key services (e.g. camera, contacts).
• Giving the user notifications: With system notifications, alarms, and vibration APIs.
• Making your app work offline: With APIs like IndexedDB, localStorage, and the Firefox OS-specific Data Store API.
• Implementing control mechanisms: Mouse, keyboard, pointer lock, touch inputs, drag and drop, and more.
• Push Notifications: invoked using the SimplePush Web API, these are a way to make applications wake up when a device receives a certain message.
• Web Activities: A way to get applications to talk to each other and share capabilities, for example taking pictures or recording video. This often provides easier ways to share capabilities.
• Controlling device communication functionality: Such as SMS, Bluetooth, Dialer, and NFC.

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:

"type" : "privileged",
"permissions": {
  "contacts": {
    "description": "Required for autocompletion in the share screen",
    "access": "readcreate"
    },
  "alarms": {
    "description": "Required to schedule notifications"
  }
}

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

"activities": {
  "share": {
    "filters": {
      "type": [ "image/png", "image/gif" ]
    },
    "href": "foo.html",
    "disposition": "window",
    "returnValue": true
  }
}

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:

"messages": [
    { "alarm": "/index.html" },
    { "notification": "/index.html" }
  ]

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.

1. 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.
2. You should take advantage of the building blocks and design patterns we've made available (see our app Design section.)
3. 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).
4. 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.
5. 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 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.
• You can publish a packaged app on the Firefox Marketplace. The process for doing this is well documented over at our Marketplace zone.

Multi-locale apps

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

1. 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:
2. <h1 data-l10n-id="app-title">My app</h1>.
3. Including the l10n.js library in your page using a regular <script> element.
4. 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.
5. 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)

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

   <link rel="resource" type="application/l10n" href="locales/locales.ini" />

7. Updating your manifest file to include a default locale and locales field containing information about your supported locales:

   "default_locale": "en",
   "locales": {
     "fr": {
       "name" : "Mon application",
       "description" : "Mon application description"
     }
   }

For more details, begin with our Getting started with app localization article, then check out the rest of our articles about app localization.

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 WebIDE tool. This will give you a more realistic idea of how it will look on a real device.

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:

adb logcat GeckoConsole:* *:F | grep -vE "parsing value|Unknown property|declaration|invalid source| but found |pseudo-"

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.

Examples

You can find many examples throughout the App Center Build section; there are also some examples in our Reference apps section.

Tutorials

Installable app basics

Firefox OS app beginners tutorial

A complete beginner's guide to creating a Firefox OS app.

Packaged apps

A packaged app is an Open Web App that has all of its resources contained in a zip file, instead of having its resources on a Web server. In here you'll learn all you need to know about packaged apps.

Hosted apps

A hosted app is an Open Web App that has all of its resources (HTML, CSS, JavaScript, app manifest and so on) stored on a Web server. This article will tell you all you need to know about hosted apps.

Packaged or hosted?

Should you make your app hosted or packaged? This article will help you decide.

Self-publishing apps

This guide explains how to write the code that controls publishing apps, should you wish to write it yourself rather than use the Firefox Marketplace.

Advanced topics

Icon implementation for apps

Implementation specifics for implementing Firefox app icons, including different sizes needed.

Updating apps

How app updates are handled.