Note: The Quickstart section has been updated with a new, more focused Firefox OS app essentials article, which replaces all the previous Quickstart articles. We hope you'll find this more useful, and a quicker learning experience than the older set of articles.
Open web apps give web developers exactly what they've wanted for years: a cross-platform environment dedicated to installable apps created with just HTML, CSS, and JavaScript — with Firefox OS being the first dedicated open web apps platform. This guide aims to get you up and running quickly with a basic architecture and build instructions so that you can create the next great app!
If you'd like to follow along with this guide, you can download our quick start app template. Find more out about what this contains by reading our Apps template guide.
App Structure
Packaged vs. Hosted Apps
There are two types of open web apps: packaged
and hosted
. Packaged apps are essentially zip
files containing all application assets: HTML, CSS, JavaScript, images, manifest, etc. Hosted apps are run from a server at a given domain, just like a standard website. Both app types require a valid manifest. When it comes time to list your app on the Firefox Marketplace, you will either upload your app as a zip file or provide the URL to where your hosted app lives.
For the purposes of this guide, you'll create a hosted app which will live at your localhost
address. Once your app is ready to list on the Firefox Marketplace, you can make the decision to bundle it as a packaged app or launch it as a hosted app.
App Manifests
Every Firefox app requires a manifest.webapp file at the app root. The manifest.webapp
file provides important information about the app, such as version, name, description, icon location, locale strings, domains the app can be installed from, and much more. Only the name and description are required. The simple manifest included within the app template is similar to the following:
{ "version": "0.1", "name": "Open Web App", "description": "Your new awesome Open Web App", "launch_path": "/app-template/index.html", "icons": { "16": "/app-template/app-icons/icon-16.png", "48": "/app-template/app-icons/icon-48.png", "128": "/app-template/app-icons/icon-128.png" }, "developer": { "name": "Your Name", "url": "https://yourawesomeapp.com" }, "locales": { "es": { "description": "Su nueva aplicación impresionante Open Web", "developer": { "url": "https://yourawesomeapp.com" } }, "it": { "description": "La tua nuova fantastica Open Web App", "developer": { "url": "https://yourawesomeapp.com" } } }, "default_locale": "en" }
A basic manifest is all you need to get started. For more details about manifests, read App Manifest.
App Layout & Design
Responsive design has become increasingly important as more screen resolutions become standard on different devices. Even if the main target of your app is mobile platforms such as Firefox OS, other devices will likely have access to it as well. CSS media queries allow you to adapt layout to device, as shown in this skeleton CSS example:
/* The following are examples of different CSS media queries */ /* Basic desktop/screen width sniff */ @media only screen and (min-width : 1224px) { /* styles */ } /* Traditional iPhone width */ @media only screen and (-webkit-min-device-pixel-ratio : 1.5), only screen and (min-device-pixel-ratio : 1.5) { /* styles */ } /* Device settings at different orientations */ @media screen and (orientation:portrait) { /* styles */ } @media screen and (orientation:landscape) { /* styles */ }
There are many JavaScript and CSS frameworks available to aid in responsive design and mobile app development (Bootstrap, etc.) Choose the framework(s) that best fit your app and development style.
Web APIs
JavaScript APIs are being created and enhanced as quickly as devices are. Mozilla's WebAPI effort brings dozens of standard mobile features to JavaScript APIs. A list of device support and status is available on the WebAPI page. JavaScript feature detection is still the best practice, as shown in the following example:
// If this device supports the vibrate API... if('vibrate' in navigator) { // ... vibrate for a second navigator.vibrate(1000); }
In the following example, the display style of a <div>
is modified based on changes in the battery state of the device:
// Create the battery indicator listeners (function() { var battery = navigator.battery || navigator.mozBattery || navigator.webkitBattery, indicator, indicatorPercentage; if(battery) { indicator = document.getElementById('indicator'), indicatorPercentage = document.getElementById('indicator-percentage'); // Set listeners for changes battery.addEventListener('chargingchange', updateBattery); battery.addEventListener('levelchange', updateBattery); // Update immediately updateBattery(); } function updateBattery() { // Update percentage width and text var level = (battery.level * 100) + '%'; indicatorPercentage.style.width = level; indicatorPercentage.innerHTML = 'Battery: ' + level; // Update charging status indicator.className = battery.charging ? 'charging' : ''; } })();
In the code sample above, once you confirm that the Battery API is supported, you can add event listeners for chargingchange
and levelchange
to update the element's display. Try adding the following to the quickstart template, and see if you can get it working.
Check the WebAPI page frequently to keep up to date with device API statuses.
Install API functionality
In our sample quickstart app template, we've implemented an install button that you can click when viewing the app as a standard Web page, to install that site on Firefox OS as an app. The button markup is nothing special:
<button id="install-btn">Install app</button>
This button's functionality is implemented using the Install API (see install.js):
var manifest_url = location.href + 'manifest.webapp'; function install(ev) { ev.preventDefault(); // define the manifest URL // install the app var installLocFind = navigator.mozApps.install(manifest_url); installLocFind.onsuccess = function(data) { // App is installed, do something }; installLocFind.onerror = function() { // App wasn't installed, info is in // installapp.error.name alert(installLocFind.error.name); }; }; // get a reference to the button and call install() on click if the app isn't already installed. If it is, hide the button. var button = document.getElementById('install-btn'); var installCheck = navigator.mozApps.checkInstalled(manifest_url); installCheck.onsuccess = function() { if(installCheck.result) { button.style.display = "none"; } else { button.addEventListener('click', install, false); }; };
Let's run through briefly what is going on:
- We get a reference to the install button and store it in the variable
button
. - We use
navigator.mozApps.checkInstalled
to check whether the app defined by the manifest athttps://people.mozilla.com/~cmills/location-finder/manifest.webapp
is already installed on the device. This test is stored in the variableinstallCheck
. - When the test is successfully carried out, its success event is fired, therefore
installCheck.onsuccess = function() { ... }
is run. - We then test for the existence of
installCheck.result
using anif
statement. If it does exist, meaning that the app is installed, we hide the button. An install button isn't needed if it is already installed. - If the app isn't installed, we add a click event listener to the button, so the
install()
function is run when the button is clicked. - When the button is clicked and the
install()
function is run, we store the manifest file location in a variable calledmanifest_url
, and then install the app usingnavigator.mozApps.install(manifest_url)
, storing a reference to that installation in theinstallLocFind
variable. You'll notice that this installation also fires success and error events, so you can run actions dependent on whether the install happened successfully or not.
You may want to verify the implementation state of the API when first coming to Installable web apps.
Note: Installable open web apps have a "single app per origin" security policy; basically, you can't host more than one installable app per origin. This makes testing a bit more tricky, but there are still ways around this, such as creating different sub-domains for apps, testing them using the Firefox OS Simulator, or testing the install functionality on Firefox Aurora/Nightly, which allows you to install installable web apps on the desktop. See FAQs about apps manifests for more information on origins.
WebRT APIs (Permissions-based APIs)
There are a number of WebAPIs that are available but require permissions for that specific feature to be enabled. Apps may register permission requests within the manifest.webapp
file like so:
// New key in the manifest: "permissions" // Request access to any number of APIs // Here we request permissions to the systemXHR API "permissions": { "systemXHR": {} }
The three levels of permission are as follows:
- Normal — APIs that don't need any kind of special access permissions.
- Privileged — APIs available to developers to use in their applications, as long as they set access permissions in the app manifest files, and distribute them through a trusted source.
- Certified — APIs that control critical functions on a device, such as the call dialer and messaging services. These are generally not available for third party developers to use.
For more information on app permission levels, read Types of packaged apps. You can find out more information about what APIs require permissions, and what permissions are required, at App permissions.
It's important to note that not all Web APIs have been implemented within the Firefox OS Simulator.
Tools & Testing
Testing is incredibly important when supporting mobile devices. There are many options for testing installable open web apps.
WebIDE with Firefox OS Simulator
The new kid on the block with regards to testing tools is called WebIDE. This tool allows you to connect desktop Firefox to a compatible device via USB (or a Firefox OS simulator), push apps straight to the device, validate apps, and debug them as they run on the device.
Unit Testing
Unit tests are extremely valuable when testing on different devices and builds. jQuery's QUnit is a popular client-side testing utility, but you can use any set of testing tools you'd like.
Installing Firefox OS on a Device
Since Firefox OS is an open source platform, code and tools are available to build and install Firefox OS on your own device. Build and installation instructions, as well as notes on what devices it can be installed on, can be found on MDN.
Dedicated Firefox OS developer preview devices are also available: read our Developer preview phone page for more information.
App Submission and Distribution
Once your app is complete, you can host it yourself like a standard web site or app (read Self-publishing apps for more information), or it can be submitted to the Firefox Marketplace. Your app's manifest will be validated and you may choose which devices your app will support (e.g. Firefox OS, Desktop Firefox, Firefox Mobile, Firefox Tablet). Once validated, you can add additional details about your app (screenshots, descriptions, price, etc.) and officially submit the app for listing within the Marketplace. Once approved, your app is available to the world for purchase and installation.