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. You can also use our manifest validator. This tool will look at your manifest and help identify errors.

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. There are only two required fields: name and description. There are other fields that are required if you use certain fields. This is indicated in the documentation.

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

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",
    "returnValue": true
  }
}

The object for the share activity in the example has these properties: filters, href, disposition and returnValue. These are described in Activity handler description.

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"

csp

(optional) Specify a Content Security Policy for the app. This policy gets applied to all pages loaded in the app. See the Apps CSP page for more information.

default_locale

(required when locales is present). A language tag (RFC 4646) that tells what language your manifest uses. Do not include the language tag you use here in the locales field. It is a good practice to define default_locale even if you do not use locales. The Firefox Marketplace will use it to know what language your manifest is in, so it can use the correct locale values in translated fields. If you do not define default_locale, the Marketplace has to guess the language based on the serving locale. default_locale is not used by the device that installs the app.

Example for English:

"default_locale": "en"​

description

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

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).

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"

icons

(optional*) A map of icon sizes to URIs of the icons (which may be absolute paths 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 follow app icon guidelines for Firefox OS.

You can specify multiple icons like this example:

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

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": ["*"]

This field may be used by receipt validators to control which stores can issue receipts for your app.

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.

locales

(optional) A map of one or more locale-specific overrides of the data contained in the manifest, which UIs use to provide localized views based on the accessing device's locale. For example, if you have Italian speakers installing your app, you probably want to give them Italian UI text. Each locale entry is keyed on a language tag (RFC 4646) and contains a sparse representation of the manifest. Any field that is present in the locale field overrides the matching field in the manifest. You cannot override these fields: 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 with Spanish and Italian:

"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/"
  }
}
}

messages

(Firefox OS only, optional) Indicates the system messages that you are allowing the app to capture. This is an array that specifies mapping between system messages and pages that will display when the messages occur. Example from a Firefox OS app:

"messages": [
  { "telephony-new-call": "/dialer/index.html#keyboard-view" },
  { "bluetooth-dialer-command": "/dialer/index.html#keyboard-view" },
  { "headset-button": "/dialer/index.html#keyboard-view" },
  { "notification": "/dialer/index.html#keyboard-view" },
  { "alarm": "/facebook/fb_sync.html" }
]

In this example, when the system message telephony-new-call occurs (indicating an incoming phone call), the device will display the page /dialer/index.html at the anchor #keyboard-view. This page should do something like give the user an indication of the call and provide controls to answer the call.

name

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

orientation

(Android & Firefox OS only, optional) An array that defines the orientations at which the application will stay locked in even if the device orientation changes. Each entry in the array 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. The permissions control access to sensitive device APIs (WebAPIs), and an app must list every WebAPI it intends to use that requires user permission. If an app tries to use one of these APIs without a corresponding entry in the permissions 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"
    },
  "alarms": {
    "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 readonly, readwrite, readcreate, and createonly.

There are many WebAPIS. For the full list of permissions you can use, see App permissions.

type

(optional) The app's type, which can be web, privileged, or certified. These types of apps have different levels of access to sensitive device APIs (WebAPIs). These types are described below but for more information see Packaged apps. For more information on access to WebAPIs, see the permissions field.

• web - A regular hosted app. This type has the least access to WebAPIs. If you do not specify the type field in the manifest, web is the default.
• privileged - An authenticated app that has been approved by an app store such as the Firefox Marketplace. This type has greater access to WebAPIs than a web app.
• certified - An authenticated app that is intended for critical system functions like the default dialer or the system settings app on a smartphone. It is not intended for 3rd party apps in an app store. This type of app has the highest level of access to WebAPIs.

Example:

"type": "privileged"

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 add this string to the manifest and extract it to help deal with various update cases. See Updating Apps.

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/.

Validating a manifest

To validate a manifest, use this website: https://marketplace.firefox.com/developers/validator

There is also an API you can use the validate a manifest: https://zamboni.readthedocs.org/en/latest/topics/api.html#validate

Serving manifests

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

The manifest should 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. This is currently not enforced by Firefox but is enforced by the Firefox Marketplace. Firefox OS only checks this if the origin of the page where the user triggers the install is different from the origin of the app itself. You don't need other headers such as Content-Security-Policy and X-UA-Compatible.

Manifests can be served over SSL to mitigate certain classes of attacks. You can also serve the manifest with HTTP compression. The manifest should not be cached.

The manifest must be in UTF-8 encoding in order for the app to be submitted to Firefox Marketplace. It is recommended that you 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), although 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 the last 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, 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.

Serving from Python

If you have Python installed, you can easily run a server from the local directory, by running Python and pasting the same:

import SimpleHTTPServer
import SocketServer
SimpleHTTPServer.SimpleHTTPRequestHandler.extensions_map['.webapp'] = 'application/x-web-app-manifest+json'
httpd = SocketServer.TCPServer(("", 3000), SimpleHTTPServer.SimpleHTTPRequestHandler)
httpd.serve_forever()

Updating manifests

For information on updating apps, see Updating apps.