This document specifies a JSON based format to describe installable web applications. In addition, a set of JavaScript APIs are described that allow web content to trigger installation of such applications, as well as manage them on behalf of the user.

App Manifest

An application manifest is a JSON file describing an installable web application. This JSON file consists of a top-level object and several properties.

Example

  {
    "name": "MozillaBall",
    "description": "Exciting Open Web development action!",
    "launch_path": "/",
    "version": "1.0",
    "type": "privileged",
    "icons": {
      "16": "/img/icon_16.png",
      "48": "/img/icon_48.png",
      "128": "/img/icon_128.png"
    },
    "developer": {
      "name": "Mozilla",
      "url": "https://mozilla.org/en-US"
    },
    "installs_allowed_from": [
      "https://marketplace.mozilla.org"
    ],
    "appcache_path": "/cache.manifest",
    "locales": [
      "es": {
        "description": "¡Acción abierta emocionante del desarrollo del Web!",
        "developer": {
          "url": "https://mozilla.org/es-ES"
        }
      }
    ],
    "default_locale": "en",
    "screen_size": {
      "min_width": "600",
      "min_height": "300"
    },
    "required_features": [
      "touch", "geolocation", "webgl"
    ],
    "orientation": "landscape",
    "permissions": {
      "contacts": {
        "description": "Required for autocompletion in the share screen",
        "access": "read"
      }
    },
    "fullscreen": "true",
    "activities": {
      "share": {
        "filters": {
          "type": ["image/png", "image/gif"]
        }
        "href": "/share.html",
        "disposition": "window"
      }
    }
  }

Properties

All leaf properties MUST contain string values.

Mandatory Properties

  • name: The name of the web application in the default locale. Maximum length is 128 characters.
  • description: A short description of the web application in the default locale. Maximum length is 1024 characters.
  • default_locale: Mandatory only if "locales" property is set. The locale of the top-level name and description.

Optional Properties

  • launch_path: The path within the web application's origin that is loaded when the application is launched.
  • icons: A map of icon sizes to URIs of the icons (which may be absolute, relative or data URIs). Icons MUST be square. Paths beginning with "/" are treated as relative to the origin of the app.
  • type: Determines how this app and the manifest will be verified by the runtime, and what security policy will apply. See types of applications, for a more detailed description. The value for this property MUST be one of the following:
    • web: A regular web app, may be self hosted or distributed by an app store. All permissions are opt-in at install and runtime, limited to permissions enumerated in the manifest. If the type property is not specified, this will be the default value.
    • privileged: An authenticated application approved by an app store. Equivalent in functionality and security to apps on other mobile platforms, but is required to be approved by an app store after a code review or some equivalent risk management process. At install, app assets are verified & remain stored locally in a package. Requires a Content Security Policy, and all explicit permissions are requested at runtime, showing user the app's data usage intentions, and persisted by default.
    • certified: This category is reserved for apps that require approval by a device vendor or equivalent party due to risk of device corruption or risk to critical functionality. These include apps such as the system settings app, default dialer (to ensure emergency services are always accessible), core radio and power management, etc. Not intended for 3rd party applications.
  • developer: Information about the developer of the application, suitable for display.
    • name: The name of the developer.
    • url: A URL pointing to the developer's website
  • locales: A map of locale specific overrides of data contained in the manifest. Each locale key is keyed on a locale tag [RFC4646], and contains a sparse representation of the manifest. Any field in the locales property will override the corresponding property in the manifest. The locales, installs_allowed_from, and default_locale CANNOT be overridden. If the locales property is set, the default_locale MUST also be set.
  • installs_allowed_from: An array of origins that are allowed to trigger installation of this application. This field allows the developer to restrict installation of their application to specific sites. If the value is omitted, installs are allowed from any site.
  • appcache_path: The absolute path to the application cache (AppCache) manifest. When an app is installed, the AppCache manifest will be fetched and parsed, and its static assets under the CACHE header will be cached.
  • version: A string that represents the version of this manifest. The User-Agent does not interpret this value in any way and is opqaue to everyone but the application itself. The field is provided to help the developer deal with various update cases, which will be discussed in following sections.
  • screen_size: This object may contain the min_height and min_width properties that describe the minimum height and width (in pixels) the application needs in order to render correctly. Interpretation of these values is left up to the runtime and/or app store.
  • required_features: This array consists of a set of values that describes the mandatory features the application needs in order to run correctly. A full list of valid values is TBD.
  • orientation: This value defines the allowed orientations at which the application may be rendered. If a value is provided, the runtime MUST ensure that the viewport rendering the application will adhere to one of the specified values and never orient the application in a direction not specified in this property. The default behavior SHOULD be to rotate the viewport at an angle that best fits the orientation of the device, and MUST change as the user spatially rotates the device. The value MUST be an array containing one or more of the following string values (duplicates SHOULD be ignored):
    • portrait-primary: Locked to a single portrait direction. If the device has an obvious primary orientation in portrait mode, this is that orientation. If there is no obvious primary orientation due to landscape being the primary orientation for the device, this is the orientation if rotating the device 90 degrees clock-wise from the primary landscape mode.
    • landscape-primary: Locked to a single landscape direction. If the device has an obvious primary orientation in landscape mode, this is that orientation. If there is no obvious landscape orientation due to portrait being the primary orientation for the device, this is the orientation if rotating the device 90 degrees clock-wise from the primary portrait mode.
    • portrait-secondary: The portrait mode opposite of portrait-primary.
    • landscape-secondary: The landscape mode opposite of landscape-primary.
    • portrait: Equivalent to ["portrait-primary", "portrait-secondary"].
    • landscape: Equivalent to ["landscape-primary", "landscape-secondary"].
  • permissions: This value consists of a set of permissions that the application needs. An application MUST list every API that is considered to require user permission in this field. Usage of an API without a corresponding entry in the manifest will fail. The field is an object, with each property name specifying a single permission, and object containing the following fields:
    • description: Contains a human readable string specifying the intent behind requesting use of this API. This property is mandatory.
    • access: Contains a a string specifying the type of access required for this permission. This field is mandatory for a certain subset of permissions, and MUST be one of read, readwrite, readcreate, or createonly.
    The following table lists the various permissions, and whether they require an access property.
    Permission Name Permission Description Access Type
    alarm Schedule a notification, or for an application to be started, at a specific time. -
    backgroundservice Enable a web application to run in the background and perform tasks like syncing or respond 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. readonly, readwrite, readcreate, 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. readonly, readwrite, readcreate, 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, etc. Listen for and inspect resource lock events. -
    push Receive push events. -
    settings Configure or read device settings. readonly, readwrite
    sms Send and receive SMS. -
    storage Utilize localStorage and indexedDB without size limitations. -
    systemclock Set current time. (Timezone 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 All telephony related APIs. -
    wake-lock-screen Turn the display on and show the lock screen. -
    webapps-manage Obtain access to the navigator.apps.mgmt API to manage installed webapps. -
    wifi Enumerate available WiFi networks, get signal strength, connect to a network. -
  • fullscreen: This value MUST be set to either true or false to describe whether the runtime should launch the application in fullscreen mode.
  • activities: This value specifies a set of WebActivities that this app supports. Each property in this value is a discrete activity whose name matches the property name. Activity names are free-form text, and each activity is represented by an object. This object MUST contain the following property:
    • href: 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 page will be opened in the manner specified by the disposition property. The manner in which a particular app is chosen to perform an activity is out of scope for this specification.
    An activity object MAY also contain the following properties:
    • disposition: This value 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, for example, 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 details in the WebActivities document.
      • inline: The page handling the activity will open in an overlay (on a mobile device, for example, this will be rendered in a popup over the original app that requested the activity). Subsequent behavior is exactly the same as if the disposition were window.
    • filters: OPTIONAL. This value is a dictionary, each property of which specified a particular 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).

Serving Manifests

An application manifest MUST be served from the same origin that the application itself is served from. There MUST only be one application per origin.

When served as a static file, it is RECOMMENDED that the manifest be stored with the extension .webapp. The manifest MUST be served with a Content-Type header of application/x-web-app-manifest+json. It is RECOMMENDED that manifests be served over SSL.

Application Records

Applications are represented by a JavaScript object that is accessible to web content.

readonly attribute DOMString origin
The origin of the application, represented by a FQDN.
readonly attribute Object manifest
A JavaScript object as returned by JSON.parse invoked on the manifest.
readonly attribute DOMString installOrigin
The origin of the page from which the application was installed.
readonly attribute unsigned long installTime
Time in milliseconds since epoch at which the application was installed.
readonly attribute Object parameters
Parameters that were provided at install time.
EventTarget launch()
Launches this application (behaviour is runtime dependent).
EventTarget uninstall()
Uninstalls this application. This call is available to privileged callers only.

Application Registry

The following interface is made available to allow installation of apps and for apps to query for their current state.

EventTarget install(in DOMString manifestUrl, [Optional] in Object parameters)
Triggers the installation of an application as specified by the manifest at manifestUrl. The User-Agent must fetch the manifest from the provided URL, verify that it is valid, and then ask for permission from the user to allow installation to proceed. The User-Agent must also persist the parameters provided (if any) which may later be retrived from the AppObject representing this application. The user may choose to whitelist certain origins to allow them to install applications without any permission prompts.
EventTarget getSelf()
Retrieves the application record for the origin at which the call is made.
EventTarget getInstalled()
Retrieves application records for all apps that have been installed so far from the origin at which the call is made.
attribute AppRegistryManagement mgmt
Provides access to the management interace. This attribute is available to privileged callers only.

Application Registry Management

A privileged caller is a web page that has been explicitely authorized by the user to manage applications on their behalf. Such privileged origins also have access to the AppRegistryManagement interface as described below.

EventTarget getAll()
Retrieves the application records for all apps that have been installed so far.
attribute EventListener oninstall
This value may be set to a function that will be invoked when an application is installed. The only argument to this function will be the AppObject of the application that was installed.
attribute EventListener onuninstall
This value may be set to a function that will be invoked when an application is uninstalled. The only argument to this function be the AppObject of the application that was uninstalled.

Application Events

Most of the methods described above return an EventTarget object to which success and error handlers may be attached using standard DOM methods like addEventListener or attributes like onsuccess and onerror.

const unsigned short PERMISSION_DENIED = 1
Installation was denied (by user or UA).
const unsigned short MANIFEST_URL_ERROR = 2
The manifest could not be found at the given location.
const unsigned short NETWORK_ERROR = 3
The manifest could not fetched from the given location at this time.
const unsigned short MANIFEST_PARSE_ERROR = 4
The manifest could not be parsed.
const unsigned short INVALID_MANIFEST = 5
The manifest was able to be parsed but contains invalid values.
readonly attribute short code
This value is set to one of the constants defined in this interface.
attribute EventListener onsuccess
May be set to a success handler.
attribute EventListener onerror
May be set to an error handler.
void addEventListener(DOMString event, EventListener e)
event can be either be "install" or "uninstall".
void removeEventListener(DOMString event, EventListener e)
event can either be "install" or "uninstall".
readonly attribute Object result
The type and value of result depends on the operation for which this EventTarget was returned. If an onerror is fired, this value will be set to AppEventError. When getSelf() and getInstalled() succeed, ths value will be set to an array of AppObjects.