App manifest

Creating an app manifest

This section details the critical details you need to create and use an app manifest.

Conventions: file name, location, and format

• Name: manifest.webapp (you must use the .webapp extension)
• Location: your app's root directory
• Format: JSON (must be valid JSON)

Path handling

• Internal paths for manifests, icons, etc. must be absolute from the app's origin, not the root of the app. For example, if your manifest is at http://www.mysite.com/myapp/manifest.webapp, your install path will be /myapp/manifest.webapp, not /manifest.webapp.
• Internal paths also must be served from the same origin as the app.
• External paths must be fully qualified. For example, if you have a packaged app on the Firefox Marketplace but host the icon on your own server, the icon path would be http://mywebapp/images/myicon.png.

Requirements for submitting to the Firefox Marketplace

If you want to publish your app to the Firefox Marketplace, your app manifest must contain the following fields:

• name
• description
• launch_path (for Packaged Apps)
• icons (1 icon of 128×128 required, 1 icon of 512×512 recommended)
• developer
• default_locale (if locales is defined)
• type (for privileged and internal (certified) apps)

Requirements for generic Open Web Apps

If you're building a generic hosted app that will not be published in the Firefox Marketplace, your app manifest must contain the following fields below:

• name
• description
• icons (1 icon of 128×128 required, 1 icon of 512×512 recommended)

App manifest validation

If you're submitting to the Firefox Marketplace, your app manifest must pass Marketplace Validation.

Try our App Validator, which will help you identify any errors. Or you can use this API to validate your app manifest.

Updating manifests

For information on updating apps, see Updating apps.

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": "/index.html",
  "icons": {
    "512": "/img/icon-512.png",
    "128": "/img/icon-128.png"
  },
  "developer": {
    "name": "Your name or organization",
    "url": "http://your-homepage-here.org"
  },
  "default_locale": "en",
  "chrome": { "navigation": true }
}

Required app manifest fields

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

name

A human-readable name for the app. Maximum length is 128 characters.

If you change the name of your app after distribution, the name will not be updated for any existing installations.

"name": "The Open Web!"

description

A human-readable description for the app. Maximum length is 1024 characters.

"description": "Exciting Open Web App!"

launch_path

The path within the app's origin that is loaded when the app starts.

Specifies the starting point of the content local to the zip file containing the packaged app. For example, if the launch_path is /mywebapp/index.html, the app will open the file at /mywebapp/index.html when the app is launched.

"launch_path": "/index.html"

icons

A map of icon sizes to URIs of the icons.

Remember that internal paths to icons must be absolute from the app's origin, while paths to externally hosted icons must be fully qualified.

Icons must be square, and in .png format. Icons should not have solid backgrounds that extend to all four corners of the icon.

Required icon sizes

128×128

For display on the Firefox Marketplace and devices.

Recommended icon sizes

512×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×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×60

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

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

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

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

developer

• name: The name of the developer. Required for all app manifests.
• url: The URL of a website containing information about the app's developer. Optional.

"developer": {
    "name": "The Open Web!",
    "url": "http://www.mywebapp.com"
}

default_locale

A language tag (RFC 4646) that defines the language you used in the field values of your app manifest.

Although default_locale is not required for apps that don't have locales, it is recommended that you include it. If you do not define a default_locale, the Firefox Marketplace will guess your app's language.

For example, if your app uses English, it's default_locale would be:

"default_locale": "en"

type

The app's type, which defines its level of access to sensitive device WebAPIs. If you do not define type, it will default to web as the type.

• web: A regular hosted app. This type has the least access to WebAPIs.
• 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.

"type": "certified"

Optional app manifest fields

The following fields are optional.

activities

A set of Web Activities that your app supports (full list). It's structured like so:

• Each property in this field is an activity
• Activity names are free-form text
• Each activity is represented by an object

For example, here's an entry 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 filters, href, disposition and returnValue properties. These are described in Activity handler description.

appcache_path

The absolute path to the application cache (AppCache) manifest. When a Firefox OS 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"

chrome

Firefox OS 1.1+ Only

A set of navigation controls on the bottom of the screen that consists of Back, Forward, Reload and Favorite.

"chrome": { "navigation": true }

csp

This field can be used to define a Content Security Policy (CSP) that is applied to all pages in the app. The policies you can add to a CSP are listed in CSP policy directives, and for an app you'll need to include them in a line like so:

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

The default policies applied to Firefox OS privileged and internal/certified apps are as follows:

Privileged CSP

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

Certified/Internal CSP

default-src *; script-src 'self'; object-src 'none'; style-src 'self'

These defaults can’t be overridden, only added to, i.e. the CSP policy in the manifest can only make the actual CSP applied more restrictive in the case of privileged/internal apps.

datastores-owned

When making use of the Data Store API, the app that owns the data store MUST include the datastores-owned field in its manifest to claim ownership, for example:

"datastores-owned": {
  "myData": {
    "access": "readwrite",
    "description": "my data store"
  }
}

You can include multiple properties to represent different data stores, and each one can use an access of readonly/readwrite to specify whether the data store can be read/modified by other applications. A description is also included to describe the purpose of the data store.

datastores-access

When making use of the Data Store API, any non-owner app that wants access to the the data store MUST include the datastores-access field in its manifest, for example:

"datastores-access": {
  "myData": {
    "access": "readwrite",
    "description": "Read and modify my data store"
  }
}

Without this field being specified, the default behaviour is "no access". Again, multiple properties can be included if you want to access multiple data stores, and an access of readonly or readwrite can be set to declare what access type is needed by the app.

fullscreen

A control that tells the runtime whether or not to launch the app in full-screen mode.

Since most apps run in fullscreen, we recommend setting this to true.

"fullscreen": "true"

inputs

Specifies supported layouts for the keyboard app. Each layout is described using a key-value pair, where the key represents the layout name (which will be displayed in the Settings app), and the value describes detailed information about the layout, including launch path of the layout and supported input types.

The allowed values in the types field is a subset of the <input> element type attribute values. Currently allowed values are text, search, tel, number, url, email.

An example follows:

"inputs": {
   "en": {
     "launch_path": "/index.html#en",
     "name": "English",
     "description": "English layout",
     "types": ["url", "text"],
     "locales": {
       "en-US": {
         "name": "English",
         "description": "English layout"
       },
       "zh-TW": {
         "name": "英文",
         "description": "英文鍵盤"
       }
     }
   },
   "en-Dvorak": {
     "launch_path": "/index.html#en-Dvorak",
     "name": "English (Dvorak)",
     "description": "Dvorak layout",
     "types": ["url", "text"]
   },
   "es": {
     "launch_path": "/index.html#es",
     "name": "Spanish",
     "description": "Spanish layout",
     "types": ["url", "text"]
   },
  ...
}

installs_allowed_from

One (or more) URLs to the domains where your app can be installed from.

This field is intended for apps that end-users can purchase. The field identifies the app stores with whom you have a commercial relationship. If left empty, your app can be installed from anywhere.

For example, if your app can be installed from the Firefox Marketplace, installs_allowed_from will look like this:

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

Note: The array ["*"] would mean 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.

locales

A map of one or more language-specific overrides of the field values in your app manifest.

Each locales entry contains a list of the app manifest fields you want to override for a specific language. Keys for locales use the same language tags as for default_locale (RFC 4646).

For example, your apps' default language is English, so its default_locale would be en. But you want to override the name and description for your Italian and German users with translated name and description. So your locales entries would look like this:

"locales": {
  "it": {
    "name": "L'Open Web",
    "description": "Eccitante azione di sviluppo web open!"
  },
  "de": {
    "name": "Der Open Web",
    "description": "Spannende offene Web-Entwicklung-Action!"
  }
}

messages

The system messages you allow the app to capture, and the pages in your app that will display when those messages occur.

Below is an example from the Firefox OS Dialer app. Every time an incoming call comes in (system message: telephony-new-call), the device shows the dialer's keypad (URL: /dialer/index.html#keyboard-view).

"messages": [
  { "alarm": "/index.html" }
  { "notification": "/index.html" }
  { "telephony-new-call": "/dialer/index.html#keyboard-view" }
]

orientation

The positioning at which the application will stay locked.

Illustration of possible values:

value	App will stay locked to
portrait-primary
portrait-secondary
portrait If you declare this, there's no need to write -primary or -secondary
landscape-primary
landscape-secondary
landscape If you declare this, there's no need to write -primary or -secondary

"orientation": [ "landscape-primary" ]

origin

Firefox OS 1.1+ Only

Packaged apps have a special internal protocol of app://UUID where UUID is a string unique to each device the app is installed on. UUID is not easily accessible at this time. The origin field allows you to replace this UUID value with a single domain name that will be used by each installed app.

"origin": "app://mywebapp.com"

permissions

The user permissions for sensitive device APIs that your app needs, for example, access to the user's Contacts. See a full list of WebAPI permissions/features.

Each permission requires:

• name: the name of the permission
• description: the reason why your app needs to use this permission
• access: the level of access required, options being readonly, readwrite, readcreate, and createonly. Only a few APIs need this, for example Data Store.

For example, here's a manifest entry for an app that needs permission to use the device's contacts and alarms.

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

There are many APIs, some of whom require the app type to be privileged or internal (certified). For example, systemXHR requires the type field to be set to privileged in order to work:

  "type": "privileged",
  "permissions": {
    "systemXHR": {
      "description": "Required to download podcasts."
    }
  }

precompile

Firefox OS 1.4+ Only

The path to JavaScript files containing asm.js code that you want compiled at install time.

Compilation at install time makes the installation process longer, but reduces the time it takes to start up an app.

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

redirects

The internal URLs your app uses to handle external processes.

For example, your app might use Facebook OAuth authentication to get a user's contacts. When the authentication is finished, the server usually redirects back to a URL that you control. Because packaged apps are not hosted on the web, a packaged app does not have a valid URL that can be redirected to. So you use the redirects field to redirect an external URL to an internal app URL.

In the scenario above, the redirects field will look like this:

"redirects": [
  {"from": "http://facebook.com/authentication/success.html",
    "to": "/app/main_interface.html"}
]

The scope of the redirects 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.

role

The role field is mainly for internal use by the Gaia engineering team; it allows you to specify how an app should be used by B2G, its role in the system. For example, is it a keyboard, or a homescreen replacement?

"role": "system",

Options include:

• system: Does not display the app on the homescreen, and was originally intended as a system app replacement. Note however that in practice this doesn't really equate to a system app, and is used to only hide apps that shouldn't be available directly to the user (the Bluetooth app, for example.).
• input: Shows up in the Settings app as a replaceable keyboard, and does not display on the homescreen.
• homescreen: Shows up in the Settings app as a replacement homescreen option; does not display on the homescreen itself.
• addon: The app is a Firefox OS Add-on. Firefox OS 2.5 Only
• keyboard: Defines the app as an IME app. This will show up in the Settings app as an alternative keyboard, but not display on the homescreen itself. Firefox OS 1.2+ Only

version

A string that represents the version of the app, shown in Marketplace and when installing the app.

In packaged apps the version is used to determine distinguish if an update needs to be installed. The field needs to be incremented when uploading an update of your app to Marketplace.

In hosted apps this field is for your convenience; it's not used by the runtime, so version can be any value. Defining it is recommended.

"version": "2.1"

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 adding in an .htaccess file didn't work for you, you can add the same line in your Apache configuration file. Your configuration file might be named httpd.conf or 000-default.conf, depending upon your operating system and configuration.

Serving from Apache, using a PHP snippet

It may be that on a shared hosting plan, changing the Content-Type header with a .htaccess file is not working because this is globally disallowed. Meanwhile, if this hosting supports PHP, using the following short script can serve the purpose:

<?php
// Serving the manifest file 'manifest.webapp' with the appropriate header
header('Content-type: application/x-web-app-manifest+json');
readfile('manifest.webapp');
?>

This code should be placed in the same directory as the manifest, and named manifest.webapp.php for example.

Serving from Tomcat

In your web.xml file, you need to set the mime mapping

<mime-mapping>
    <extension>webapp</extension>
    <mime-type>application/x-web-app-manifest+json</mime-type>
</mime-mapping>

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

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 the following. Add the last line seen here:

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.

Serving from Python

If you have Python installed, you can easily run a server from the local directory using the following:

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

If you have flask project you don't need create file manifest.webapp but you can use route() decorator to tell Flask what URL should trigger our function. First you need import Response from Flask

from flask import Response

in your flask application, add the route() decorator, as indicated below:

@app.route('/manifest.webapp')
def manifest():
        data = json.dumps({
            "name": "Flask Application",
            "version": "1.0",
            "description": "Example of manifest.webapp",
            "launch_path": "/",
            "icons": {
                    "256": "/img/256.png",
                    "128": "/img/128.png",
                    "120": "/img/120.png",
                    "90": "/img/90.png",
                    "60": "/img/60.png",
                    "32": "/img/32.png"
                },
            "developer": {
            "name": "Rizky Ariestiyansyah",
            "url": "http://oonlab.com"
            },
            "orientation": ["portrait"],
            "default_locale": "en"
        })
        return Response(data, mimetype='application/x-web-app-manifest+json')

Serving from Rack (Ruby)

In config/initializers/mime_types.rb, add:

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

Specification

Not part of any specification — this document refers to the proprietary Firefox OS manifest format, and not the W3C manifest spec. We will hopefully document this at a different location, sometime soon.

Browser compatibility

For obvious reasons, support is primarily expected on mobile browsers.