Warning:
This wiki has been archived and is now read-only.

Application Manifest

From Web Application Store Community Group
Jump to: navigation, search

Application Manifest

An application manifest is a describing format for an installable web application. A manifest is one of the key things that distinguish an Web Application from a website. A manifest can contain the downloadable link of the application, icons, and the permissions required by the app, among other things. JSON format is most generally used format.

  • This JSON file consists of a top-level object and several properties. The JSON grammar is described in [RFC4627].

Abstract

This document specifies a standardized manifest format to describe installable web applications delivered by the Web Store.

Status of This Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

This document was published by the Web Store Community Group as an Editor's Draft. If you wish to make comments regarding this document, please send them to public-webstore@w3.org (subscribe, archives). All comments are welcome.

Publication as an Editor's Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

Table of Contents

@@@ TBD @@@

Application manifest

An application manifest is a describing format for an installable web application. A manifest is one of the key things that distinguish an Web Application from a website. A manifest can contain the downloadable link of the application, icons, and the permissions required by the app, among other things.

The app manifest provides useful information about an app (such as name, author, icon, and description) in a simple document usable by both users and app stores. Most importantly, it will contain a list of Web APIs (such as geolocation) that your App needs. This allows users to make informed decisions about apps before installing them.

Example Manifest

The following is a minimal manifest. 

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


Manifest properties

Note: 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 Propertieis

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 a comma-seperated list containing one or more of the following 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".
fullscreen
  • This value must be set to either true or false to describe whether the runtime should launch the application in fullscreen mode.


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

@@@ TBD @@@

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 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 Web Store. 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 Web Store.

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

another manifest format (Microdata format)

@@@ TBD @@@

Appendix

Issues

  • I18N(Internationalization) and L10N(Localization)
  • Application Life Cycle Management information in the Application manifest
  • Permissions and API usage notification by the Application manifest
  • Signed Application Manifest with Web Crypto API
  • Manifest Version Management
  • Change Notification using Application Manifest
  • Description method - JSON, Microdata, ...
  • Application Manifest and Web Store
  • How to provide details in the Application Manifest
    • Application Size information

Use Cases

Requirements

References

Retrieved from "https://www.w3.org/community/webappstore/wiki/index.php?title=Application_Manifest&oldid=177"