App manifest

An Open Web App manifest contains information that a Web browser needs to interact with an app. A manifest is one of the key things that distinguish an Open Web App from a website. It is a JSON file with a name and description for the app, and it can also contain the origin of the app, icons, and the permissions required by the app, among other things. The browser that handles the manifest must incorporate a Web runtime.

To self-publish an app from a page that you control, you trigger installation of the app (for example, by calling navigator.mozApps.install() from a button). When a store or marketplace publishes an app, it triggers installation of the app by providing the browser with the URL of the manifest of the hosted app.

See About app manifests for a FAQ.

Example manifest

The following is a minimal manifest. You can copy it into a text file and replace the values with your own information.

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

Manifest fields

The following fields are allowed in the manifest. The fields in your manifest can be in any order. Fields in the manifest other than the ones given below will be ignored.

name

(required) A human-readable name for the app (maximum length is 128 characters).

description

(required) A human-readable description of the app (maximum length is 1024 characters).

launch_path

(optional, required for packaged apps) The path within the app's origin that is loaded when the app starts. If not provided, the app's origin is treated as the launch domain URL. See Path Handling.

In a packaged app, this field specifies the starting point of the content local to the zip file containing the packaged app. For example, if launch_path has a value of /myApp/index.html, when the packaged app is launched it will open the file /myApp/index.html.

icons

(optional) A map of icon sizes to URIs of the icons (which may be absolute paths, relative or data URIs). Icons must be square and are intended to visually represent the app. Icons should not have solid backgrounds that extend to all four corners of the icon. Paths beginning with "/" are treated as relative to the origin of the app.

For Windows 7 and Android, the following icon sizes are supported:

• 16 x 16
• 32 x 32
• 48 x 48
• 64 x 64
• 128 x 128
• 256 x 256

For Firefox OS icons should be provided without a drop shadow and a close cropped canvas in the following sizes:

• 30 x 30
• 60 x 60

You can download preliminary app icon guidelines for Firefox OS. Final style guidelines are coming soon at https://www.mozilla.org/en-US/styleguide/.

You can specify multiple icons like this example:

"icons": {
  "16": "/img/icon-16.png",
  "48": "/img/icon-48.png",
  "128": "/img/icon-128.png"
}

csp

(optional) Specify a Content Security Policy for the app. CSP syntax is described at https://wiki.mozilla.org/Security/CSP/Specification. 

Note that for privileged and certified apps there are default CSPs that do not require this field in the manifest. The CSP that you specify here for privileged and certified apps must be stricter than the default CSPs. The default CSPs for privileged and certified and apps are:

Privileged:
"default-src *; script-src 'self'; object-src 'none'; style-src 'self' 'unsafe-inline'"

Certified:
"default-src *; script-src 'self'; object-src 'none'; style-src 'self'"

type

(optional) The app's type, which can be web, privileged, or certified. These types are described below.

• web - A regular app. Permissions are limited to those listed in this manifest in the permissions field. If you do not specify the type field in the manifest, web is the default.
• privileged - An authenticated Open Web App that has been approved by an app store such as the Firefox Marketplace. It is meant to provide more security for a user when an app wants access to certain sensitive APIs on a device. A privileged app is equivalent in capability and security to apps on other mobile platforms. It is a packaged app (all resources contained in a zip file) that has the following additional characteristics:
  • Approved by an app store after code review or equivalent.
  • Has an app manifest signed by the app store.
  • Uses a Content Security Policy.
  • Implements other things related to security. For more information see Security.
• certified - An Open Web App that is intended for a critical system function like the default dialer or system settings app on a smartphone. It is not intended for 3rd party apps in an app store. A certified app is a packaged app that is similar to a privileged app, except that all device permissions are implicit. It must be approved by the OEM or carrier for the device that uses it.

Example:

"type": "privileged"

developer

(optional) Information about the developer of the app. It has these properties:

• name - The name of the developer.
• url - The URL of a site containing more information about the app's developer. This URL is typically rendered when the user clicks on the name of the app's developer while viewing details about an app inside the dashboard (or browser).

locales

(optional) A map of locale-specific overrides of the data contained in the manifest, which UIs use to provide localized views. Each locale entry is keyed on a locale tag and contains a sparse representation of the manifest. Any field that is present in the locale value overrides the matching field in the manifest. Certain fields cannot be overridden, including default_locale, locales itself and installs_allowed_from. A manifest that overrides any of these fields is invalid. When locales is present, default_locale must also be present. Example:

"locales": {
  "es": {
    "description": "¡Acción abierta emocionante del desarrollo del Web!",
    "developer": {
      "url": "https://es.mozillalabs.com/"
    }
  },
  "it": {
    "description": "Azione aperta emozionante di sviluppo di fotoricettore!",
    "developer": {
      "url": "https://it.mozillalabs.com/"
    }
  }
}

default_locale

(required when locales is present) The locale tag for the "default" translation of manifest properties. That is, the locale of values not included in the locales map.

installs_allowed_from

(optional) An array of origins (scheme+domain, for example https://marketplace.example.com) that are allowed to trigger installation of this app. This field allows you to explicitly allow only certain sites or stores, with whom you have a relationship, to install your app. The array ["*"] means that installations of this app are allowed from any site. This is the default.  Note that [] would disallow installation from any site, including your own site. Here is an example of allowing installations from any site:

"installs_allowed_from": ["*"]

version

(optional) A string that represents the version of the manifest. The Web runtime does not use this value in any way, so this can be any value. You can embed this string into the manifest and extract it to help deal with various update cases. See the section on updating below.

orientation

(Android & Firefox OS only, optional) A comma-separated list that defines the orientation at which the application will stay locked in even if the device orientation changes. Can be one of "portrait", "landscape", "portrait-primary", "landscape-primary", "portrait-secondary" or "landscape-secondary". The options with primary and secondary lock the orientation in only one device orientation, even if the device orientation changes. The options without primary and secondary combine both rules of primary and secondary together. The options additionally suffixed with "-secondary" imply a 180 degree rotation from the options without the suffix. For instance, holding the phone upside down (but still in a manner where width is less than height), implies the "portrait-secondary" orientation. If this field has a valid value, the runtime will not change the orientation of the view rendering the application even if the device is turned. Example:

"orientation": "portrait,landscape-secondary"

permissions

(optional) The set of permissions that the app needs. An app must list every API it intends to use that requires user permission. If an app tries to use one of these APIs without a corresponding entry in this field, it will fail.

The permissions field is an object, with each property specifying a single permission. Each API entry must have a description property. Some APIs also require an access property. Example of the permissions field:

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

• description - A string specifying the intent behind requesting use of this API. This property is mandatory.
• access - A string specifying the type of access required for the permission. This property is only required for a few APIs. The possible values are read, readwrite, readcreate, and createonly.

The permissions APIs are listed below. If an API requires an access property, it is mentioned. For more information on where these permissions are supported, see App permissions.

• alarm - Schedule a notification, or schedule an application to be started.
• backgroundservice - Enable a web application to run in the background and perform tasks like syncing or responding to incoming messages.
• bluetooth - Low level access to Bluetooth hardware.
• browser - Enables implementing a browser.
• camera - Take photos, shoot video and control the camera.
• contacts -  Add, read, or modify contacts from the address book on the device and read contacts from the SIM. Access property required: one of readonly, readwrite, readcreate, or createonly.
• desktop-notification - Display a notification on the user's desktop.
• device-storage - Add, read, or modify files stored at a central location on the device. Access property required: one of readonly, readwrite, readcreate, or createonly.
• fmradio - Control the FM radio.
• geolocation - Obtain the current location of the user.
• mobileconnection - Obtain information about the current mobile voice and data connection.
• power - Turn the screen on or off, control CPU, device power, and so on. Listen for and inspect resource lock events.
• push - Receive push events.
• settings - Configure or read device settings. Access property required: one of readonly or readwrite.
• sms - Send and receive SMS.
• storage - Utilize localStorage and indexedDB without size limitations.
• systemclock - Set current time. (Time zone information is controlled by the settings API.)
• network-http - Make HTTP requests without any origin restrictions.
• network-tcp - Create and communicate over TCP sockets.
• telephony - Access all telephony-related APIs.
• wake-lock-screen - Turn the display on and show the lock screen.
• webapps-manage - Obtain access to the navigator.mozApps.mgmt API to manage installed Open Web Apps.
• wifi - Enumerate available WiFi networks, get signal strength, connect to a network.

fullscreen

(Firefox OS only, optional) Set this to true or false to indicate whether the runtime should launch the app in full-screen mode. Example:

"fullscreen": "true"

appcache_path

(optional) The absolute path to the application cache (AppCache) manifest.  When an Open Web App is installed, the AppCache manifest will be fetched and parsed, and its static assets under the CACHE header will be cached.

"appcache_path": "/cache.manifest"

activities

(Firefox OS only, optional) Specifies a set of Web Activities that this app supports. Each property in this field is an activity. Activity names are free-form text, and each activity is represented by an object. Here is an example activities field with one activity named share:

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

The object for the share activity in the example has three properties: filters, href, and disposition. These are described below.

• href - (required) When another app or web page initiates an activity that is supported by this app, if this app is chosen to perform the activity, this specifies the page that will be opened. It will be opened in the manner specified by the disposition property.
• disposition - (optional) Specifies how the page specified in href is presented when an activity is invoked. The value, if specified, must be one of the following (if omitted, defaults to window):
  • window - The page handling the activity is opened in a new "window" (on a mobile device this view will replace the original app that requested the activity). The page must call navigator.setMessageHandler for each activity it supports and subsequently execute the activity for which it receives a message. Further, if the activity requires a return value, the page must call activity.postResult or activity.postError (where activity is the first argument provided to the function specified by setMessageHandler) as appropriate. These functions are specified in greater detail in Web Activities.
  • inline - The page that handles the activity will open in an overlay (on a mobile device this will be rendered in a popup over the original app that requested the activity). Subsequent behavior is exactly the same as if disposition were window.
• filters - (optional) A dictionary, each property of which specifies a filter. These filters will be applied while determining apps suitable for handling a given activity. Filter names are free-form text, but their values must be either a string or an array of strings (the exact type depends on the filter).

Path handling

All fields that hold paths in the manifest must be absolute paths (for example, /images/myicon.png), and the paths must be served from the same origin as the app.

Also, there are two ways to set launch_path:

• If your app is stored in the root of a Web server, for example mywebapp.github.com/, then launch_path must be set to /.
• Otherwise, if your app is stored in a subdirectory, for example mymarket.github.com/mywebapp/, then launch_path must be set to /mywebapp/.

Serving manifests

The app manifest must be served from the same origin that the app is served from.

When served from static files, it is recommended that the manifest be stored with a file extension of .webapp.  App manifests must be served with a Content-Type header of application/x-web-app-manifest+json (Note: this is currently not enforced by Firefox but is by the Marketplace). Manifests can be served over SSL to mitigate certain classes of attacks.

The document must be UTF-8 in order for the app to be submitted to Firefox Marketplace. It is recommended to omit the byte order mark (BOM). Other encodings can be specified with a charset parameter on the Content-Type header (i.e. Content-Type: application/x-web-app-manifest+json; charset=ISO-8859-4), though this will not be respected by the Marketplace.

User Agents when possible should meaningfully message the site identity and TLS status when prompting a user to install an app.

Serving from Apache

In your .htaccess file, you MUST add the following:

AddType application/x-web-app-manifest+json .webapp

If you don't have a .htaccess file, create it in the root directory of your server. If this doesn't work, your host may require you to also add AddHandler x-web-app-manifest+json .webapp.

Serving from NGINX

You need to edit your mime.types file in the conf directory. This will probably be located in either /etc/nginx/ or /opt/nginx/.

You should have something similar to below. Add in the bold line.

types {
  text/html   html htm shtml;
  text/css    css;
  text/xml    xml;
  application/x-web-app-manifest+json   webapp;
}

Serving from GitHub

If you serve your manifest file from GitHub Pages (https://pages.github.com/), GitHub will serve it with the Content-Type header of application/x-web-app-manifest+json. You must use the .webapp file extension on your manifest file. Example: manifest.webapp.

Updating manifests

An app respects the normal rules for Web caching, and may optionally use advanced mechanisms for improved start-up, like the HTML5 AppCache. Given this, there are no special considerations for updating the normal resources that an app uses.

Open Web Apps are different, however, in the handling of the manifest. Some changes to a manifest may require user approval. Depending on the implementation of the Web runtime, it may be unclear whether an update has occurred.

As a clean way to deal with this issue, you can provide a version field in the app manifest. You can later check the version by inspecting the return value of the navigator.mozApps.getInstalled() function. If the user's installed version is not up-to-date, you can trigger an update using navigator.mozApps.install().

The value of version is not used by the Web runtime, so you can use whatever versioning scheme you want.