Packaged Apps

A packaged app is an Open Web App that has all of its resources (HTML, CSS, JavaScript, app manifest, and so on) contained in a zip file, instead of having its resources on a Web server. A packaged app is simply a zip file with the app manifest in its root directory. The manifest must be named manifest.webapp.

One difference from a hosted app is that a packaged app must specify a launch_path in the manifest, whereas it's an optional manifest field for a hosted app.

Note: Currently the Firefox Marketplace supports packaged apps only when they are Firefox OS apps.

Purpose of packaged apps

The purpose of a packaged app is to have a workable way to provide apps that have access to sensitive APIs on devices. The app must be verified by the store where the app is distributed (such as the Firefox OS Marketplace). The store reviews the app and if it is found acceptable, the store cryptographically signs the app's zip file with its private key. This gives users of the app more assurance that the app has been carefully reviewed for potential security, privacy, and capability issues.

Types of packaged apps

There are three types of packaged apps:

Privileged app
A privileged app is approved by the Firefox Marketplace using a special process. It is meant to provide more safety for users when an app wants access to certain sensitive APIs on a device. It is equivalent to a native app on a platform like iOS or Android. To specify that an app is a privileged app, add the type field to its manifest.webapp file and set it to privileged. A privileged app has the following characteristics:
  • Approved by an app store after code review or equivalent.
  • App's resources are signed by the app store.
  • Allowed to use certain sensitive Web APIs that untrusted content cannot have access to.
  • Enforces a Content Security Policy (CSP). A privileged app uses this CSP:
    "default-src *; script-src 'self'; object-src 'none'; style-src 'self' 'unsafe-inline'"
  • Implements other requirements related to security. See Security for more information.
Certified app
A certified app is intended for a critical system function like the default dialer or the system settings app on a smartphone. This type of app would be used for critical functions on a Firefox OS phone. It is not intended for third party apps, so most app developers can disregard this type of app. A certified app is a packaged app that is similar to a privileged app, except that all device permissions are implicit, meaning they do not require explicit user approval. A certified app must be approved for a device by the OEM or carrier in order to have this implicit approval to use critical APIs. To specify that an app is a certified app, add the type field to its manifest.webapp file and set it to certified. The following is the CSP for a certified app, which is slightly different from the CSP for a privileged app:
"default-src *; script-src 'self'; object-src 'none'; style-src 'self'"
This has the effect of slightly looser rules for inline CSP for privileged apps when compared to certified apps. If you want more of the reasoning behind this, see Default CSP policy and Bug 768029.
Plain packaged app
You can also make a regular app that is simply packaged in a zip file. The Marketplace signs it, but does not perform the special authentication process used for privileged or certified apps. This plain packaged app cannot use certain sensitive Web APIs. It is not subject to the CSPs described for privileged and certified apps. This type of app could be useful if you want all of your app's resources available on the device when the user first uses it, with no downloading. This type of packaged app does not require the type field in its manifest.webapp file, because the default value for type (web) is correct.

Differences from hosted apps

Packaged apps have the same capabilites as normal website-style Open Web Apps ("hosted" apps), but packaged apps have a few differences:

  • They have no Internet origin. The one-app-per-origin policy that governs hosted apps does not apply to packaged apps.
  • They use a special protocol internal to the zip file: app://<uuid>. Example: When you load the content /index.html in a packaged app, you are actually loading something like the following (the UUID will be different):
  • The manifest file must be named manifest.webapp.
  • Their resources are accessed from the zip file, which is stored on the device where the app is installed.
  • They are installed with a different mozApps API function: installPackage().
  • They enforce a specific CSP for all application content (a hosted app could also use a CSP, but it is not required).
  • They can embed remote content in iframes, but that content will not have access to privileged APIs nor will it have the default CSP applied to it.
  • They have an update process for getting new versions of the app to users. Hosted apps do not need this process.

The packaged app can still do things like access a database on a Web server, like a regular hosted app.

Using sensitive Web APIs

There are Web APIs that could be used maliciously, so access to them must be controlled. For every sensitive API you want your app to access, you must add an entry to the permissions field in the app's manifest.

Some sensitive APIs can be accessed by normal hosted apps, but other APIs require that you use a packaged app (privileged or certified). See App permissions for a table that describes the requirements.

Packaged apps and the Firefox Marketplace

The Firefox Marketplace handles packaged apps differently from hosted apps. When you submit your packaged app, its zip file is stored on the Marketplace servers, and the Marketplace generates a new manifest called the "mini-manifest" that is based on the app manifest in your packaged app's zip file. When a user installs your app, the mini-manifest is passed to the installPackage() function to install the app. The mini-manifest exists for installation and update purposes and is not used when your app runs.

Testing packaged app installation

Installation of a packaged app is very easy using the Firefox OS Simulator. The Firefox OS Simulator comes in platform specific builds, and is available for Windows, OSX, and Linux.

Installing the simulator adds a menu item to Firefox's Web Developer menu. After opening the addon you can specify, through Add Directory, the location of a local webapp.manifest. The simulator will then package the app for you (zipping the containing folder), and open the simulator with the newly packaged app.

For Linux and Windows users, there are additional steps for setting up Android Debug Bridge (adb) which is used for communicating with an actual device. Please see step 3: Set up your system to detect your device .

On device, enable Remote debugging by going to Settings > Device Information > More Information > Developer > Remote Debugging.

You may at any point connect a supported device. When a supported device is connected, the simulator will detect it and display Device connected. Next to each app listing, you will also see a new button labeled "push". Click "push" to send your newly packaged app to device.

Updating packaged apps

For information on updating apps, see Updating apps.

Document Tags and Contributors

Contributors to this page: chrisdavidmills
Last updated by: chrisdavidmills,