App Manifest Instructions

What is an App Manifest?

The App Manifest provides 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 contains a list of Web APIs that your app needs. This allows users to make informed decisions about apps before installing them.

If you are planning to publish your app on the Firefox Marketplace, you also need to have a Marketplace Config file.

Learn more about the App Manifest >

Creating an App Manifest

Conventions: File Name, Location, and Format

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

Path Handling

Internal paths must be absolute from the app's origin, for example, /images/myicon.png.

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 but host icons on your own server, the icons 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 required fields below.

name
description
launch_path (for Packaged Apps)
icons (1 icon of 128x128 required)
developer
default_locale (if locales is defined)
type for (Privileged and Certified Apps)

Requirements for Generic Open Web Apps

If you're building a generic open web app that will not be published in the Firefox Marketplace, your App Manifest must contain the required fields below.

name
description
icons (1 icon of 128x128 required)

App Manifest Validation

If you're submitting to the Firefox Marketplace, your App Manifest must pass Marketplace Validation.

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

Required App Manifest Fields

`name`

Required for all App Manifests.

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

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

Required for all App Manifests

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

"description": "Exciting Open Web App application!"

`launch_path`

If app is a Packaged App, required for App Manifest.

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.

Tips:

If your app is stored in the root of a Web server, for example mywebapp.github.com/, then launch_path must be set to /.
If your app is stored in a subdirectory, for example mymarket.github.com/mywebapp/, then launch_path must be set to /mywebapp/.

"launch_path": "/index.html"

`icons`

1 icon (sized 128x128) required for all App Manifests.

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. Icons should not have solid backgrounds that extend to all four corners of the icon.

Caution: if you're submitting to the Firefox Marketplace, your icons must also follow the Firefox Marketplace app icon guidelines.

Icon Sizes:

128 x 128: Used for display on the Firefox Marketplace. Required for all App Manifests.
60 x 60: Used as the app's icon on the device. Optional, but recommended.
32 x 32, 90 x 90, 120 x 120, and 256 x 256: Optional, needed for optimal display on other platforms your app might be installed on, for example, Windows 7 or Android.

"icons": {
  "128": "/img/icon-1.png",
  "60": "/img/icon47.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`

If locales is defined, default_locale is required for App Manifest.

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`

If app is Privileged or Certified, type is required for App Manifest.

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.

For more information on app types, see Packaged apps. For information on access to WebAPIs, see the permissions field.

"type": "web"

Optional App Manifest Fields

`activities`

A set of Web Activities that this 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
  }
}

`appcache_path`

The path to your application cache manifest file. Using an application cache provides speed, offline browsing capability, and reduced server load.

Although it is optional, defining appcache_path is recommended.

"appcache_path": "/cache.manifest"

`chrome`

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

We recommend designing a back button to your app interface, instead of relying on this option.

"chrome": { "navigation": true }

`csp`

A Content Security Policy (CSP) that is applied to all pages in the app. See the Apps CSP page for how to use this field.

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

`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 anywhere.

Caution: Do not put a trailing slash at the end of URLs, because the installation will fail.

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

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

Caution:

If you are defining locales, remember to also define default_locale.
Do not define the value of default_locale again in locales.
You cannot override these fields: default_locale, locales, and installs_allowed_from.

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`

Applies only to apps using Firefox OS.

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": [
  { "telephony-new-call": "/dialer/index.html#keyboard-view" }
]

`orientation`

Applies only to apps using Android or Firefox OS.

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`
`portrait-secondary`
`landscape` If you declare this, there's no need to write `-primary` or `-secondary`

"orientation": [ "landscape-primary" ]

`origin`

Applies only to Packaged Apps and requires Firefox OS 1.1.

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.

Remember: domain name must start with app://, and you must be the owner of the domain name you specify.

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

`permissions`

Applies only to Packaged Apps.

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 (some permissions don't need this)

For example, here's 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"
  }
}

`precompile`

Applies only to Packaged Apps and requires Firefox OS 1.4.

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`

Applies only to Packaged Apps using Firefox OS.

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 server is finished, it 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 Web URL that can be redirected to. So you use the redirects field to redirect an external Web 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"}
]

`version`

A string that represents the version of the manifest.

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"