App manifest

manifest文件名称为 manifest.webapp, 位于您的web应用文件夹下的根目录下，同时与  index.html 文件相邻。

要在您控制的网页上自行发布app，则需要触发app的安装程序（例如，通过一个按钮来调用 navigator.mozApps.install() 方法)。当一个 store 或者 marketplace 发布了一个应用，它就会通过将托管应用的 manifest URL地址提供给浏览器来触发应用的安装过程。 

另外可参阅 About app manifests 来查看常见问题（FAQ），也可以使用我们的manifest validator 工具。这个工具会扫描您的manifest文件并且帮助找到其中的错误。

manifest 示例

下面的代码是一个最简单的manifest文件。您可以将其复制到一个text文件并且替换成您自己的信息。

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

Manifest 字段

下面是对 manifest 中合法的字段进行介绍。只有三个字段是 manifest 中所必须要求的： name, description 和 icons (包括一个128px icon i)。如果你在使用特定的字段时，会要求其他的字段存在。 这会在下面文档中提及。

在 manifest 中的字段可以以任何顺序存在。 如果使用了下面清单中没有的字段时，将会被忽略。

activities

(Firefox OS only, optional) 指定了这个 app 所支持的  Web Activities 集合。这个字段的每个属性都是一个 activity。Activity 的名称形式没有要求，每个 activity 都是以对象表示的。下面是名称为 share 的activity 示例。

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

示例中的share活动有以下特点： filters, href, disposition, returnValue. 在Activity handler description中有描述

appcache_path

（可选）应用缓存(AppCache)清单（manifest）的绝对路径。当安装完一个WebApp时，AppCache清单将会被获取与解析， and its static assets under the CACHE header will be cached.

"appcache_path": "/cache.manifest"

chrome

Requires Firefox OS 1.1

(optional) 在屏幕的下方添加导航接口。当 app 没有提供自身的返回按钮时，这是给出导航控制的快速方案。

在下面左侧图片中，导航区域是隐藏的；当往上拖动时，就会向右侧图片显示出来。

示例:

"chrome": { "navigation": true }

csp

（可选）为应用指定一个安全策略。此安全策略会在所有该App加载的页面生效。查看Apps CSP页面获得更多信息

default_locale

（存在locales时必须）一个告诉系统你的mainfest所使用的语言的标签(RFC 4646) 。在locales中不要包含此处所使用的语言。即使你没有使用locales标签，定义default_locale也是一个很好的习惯。Firefox Marketplace会靠它知道你的manifest的语言，因而它能够在“已翻译”中正确使用。如果你没有定义default_locale，Marketplace会尝试猜测所服务的地区的语言。default_locale不会被安装应用的设备使用

以英文为例：

"default_locale": "en"​

description

（必须）一个给人看的应用说明（最长不超过1024字节）

developer

（可选但请注意下面的说明） 关于应用开发者的信息，包含以下内容：

• name——开发者名称.
• url——一个关于应用开发者信息的URL 这个url所对应的站点拥有关于app开发者的更多信息。 当用户在dashboard（或者浏览器）中查看关于app的详细信息的时候，点击开发者名字，url通常会被激活。

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

(required) A map of icon sizes to URIs of the icons (which may be absolute paths or data URIs). Paths beginning with / are treated as relative to the origin of the app. Icons must be square, in PNG format, and are intended to visually represent the app. Icons should not have solid backgrounds that extend to all four corners of the icon, or a drop shadow. For more details on icon style, see the Firefox OS icon styleguide.

Required icon sizes

128 x 128

For display on the Firefox Marketplace and devices.

Recommended icon sizes

128 x 128

For display on the Firefox Marketplace and pre-Firefox OS 2.0 devices.

512 x 512

From Firefox 2.0 onwards, larger icons are needed for crisp display on all the different possible combinations of Phone and tablet screen sizes, screen resolutions, and 3 and 4-column layouts. We accept a 512 x 512 icon, which is then scaled for all the different uses across devices. This size is also useful for display on other platforms apps can be installed across, such as Android.

Other icon sizes that might be useful

60 x 60

For the exact on-device icon size on older Firefox OS versions.

16 x 16, 32 x 32, 48 x 48, 64 x 64, 90 x 90, 128 x 128 and 256 x 256

These icon sizes are used on various other platforms your app can be installed on, such as Windows, Mac OS X and Android.

Icon manifest code

You can specify icons in the manifest like so:

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

installs_allowed_from

(optional) One or more sites that are allowed to trigger installation of the app. This field is intended to be used with a paid app (an app that will be purchased) to identify the stores with which you have a commercial relationship. If you have a free app, it is recommended that you allow it to be installed from anywhere by omitting this field.

This is an array of origins in the format <scheme name> + <domain>. Example:

"installs_allowed_from": [
  "https://marketplace.firefox.com",
  "https://marketplace.example.com"
]

The array ["*"] means that installations of this app are allowed from any site. This is the default. Note that an empty array [] would disallow installation from any site, including your own.

This field can 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. Read Path Handling for additional details; there are special considerations if your app isn't located at the root of its domain.

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.

Keys for this field should be in the format of xx-YY or xx. For example, you should prefer the format pt-BR and es over alternatives like pt_br, pt_BR, or ES. The Firefox Marketplace enforces this recommendation for consistency.

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, 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 containing -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"]

origin

Requires Firefox OS 1.1

(privileged or certified apps only) Used to give an origin to a privileged or certified packaged app. You do not need this field for hosted apps, which already have an origin (the website that they are served from). One use for this field is to make it easier to give your packaged app an authentication capability like OAuth or Persona.

There is a special protocol that is internal to a packaged app, which is app://<UUID>, where <UUID> is a long string that is unique to each device that the app is installed on. This URL is not easily available to app developers at this time. The origin field enables you to replace this UUID with a single domain name that will be used by each installed app, such as app://my-app.com.

The domain name you use should be a domain that you control. The app probably will not be approved for the Firefox Marketplace if it is a domain like app://facebook.com and you are not Facebook.

Example (make sure you use the app:// protocol):

"origin": "app://my-app.com"

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.

precompile

Requires Firefox OS 1.4

(Firefox OS only, optional, packaged apps only) Specifies that asm.js code contained within the app should be compiled at install time, install of during first run. This significantly reduces the cost of starting an app for the first time, at the expense of a longer initial install. The field accepts an array of relative paths to JavaScript assets containing asm.js code that needs to be compiled.

"precompile": [
  "game.js",
  "database.js"
]

redirects

(Firefox OS only, privileged and certified apps only) A privileged or certified app might need to do external authentication. For example, the app could do Facebook OAuth authentication so it can get a person's contacts. When the authentication server is finished, it will usually redirect the app back to a URL that you control.

But a privileged or certified app does not have a valid Web URL that can be redirected to, because the app is not hosted anywhere (it is a packaged app with no public origin). So you use the redirects field to redirect a Web URL to an internal app URL.

Example:

"redirects": [
  {"from": "https://mydomain.com/oauth2/flow.html",
    "to": "/redirects/redirect.html"},
  {"from": "https://mydomain.com/oauth2/dialogs_end.html",
    "to": "/redirects/dialogs_end.html"}
]

The from field labels the Web URL and the to field labels the internal app URL to redirect it to. The internal app URL must be a relative URL, do not use a protocol like https:// in front of it.

The scope of the redirections that are declared by redirects is limited to the app that declares them. That makes it so that several apps can redirect the same public URL to their own local resources, and it also prevents global hijacking of public URLs by an application.

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 to validate a manifest: https://firefox-marketplace-api.readthedocs.org/en/latest/

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.

If adding in .htaccess file didn't work for you, you can add the following line in your apache configuration file. Your configuration file might be named httpd.conf, 000-default.conf etc depending upon your operating system and configuration.

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

Serving from IIS

You need to edit your web.config file. This will probably be located in the web site's root directory.

You will have to add a new entry in the <configuration> <system.webServer> <staticContent> section.

<remove fileExtension=".webapp" />
<mimeMap fileExtension=".webapp" mimeType="application/x-web-app-manifest+json; charset=UTF-8" />

More info on adding static content MIME mappings in IIS.

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

Serving from Rack (Ruby)

In config/initializers/mime_types.rb, add:

Rack::Mime::MIME_TYPES['.webapp'] = 'application/x-web-app-manifest+json'

Updating manifests

For information on updating apps, see Updating apps.

Specification