Publishing apps yourself

There may be circumstances where you don't want to make an app available through Firefox Marketplace. For example, you may want to distribute an app to members of your organization, run a beta test or simply do your own thing. This page explains how to publish apps yourself, outside Firefox Marketplace.

Open Web Apps are installed into Firefox OS, devices running Firefox for Android and desktops running Firefox for Desktop using Apps.install or Apps.installPackage. In both cases, these APIs work by sending the URL of the manifest describing the app to be installed. So the basic requirements for publishing an app yourself are:

a server containing the app's manifest.
a server containing the app (for hosted apps) or the app's packaged ZIP file.
code on a website to invoke Apps.install or Apps.installPackage as appropriate.

Limitations

Before publishing Open Web Apps yourself, you should be aware of the following limitations:

Self-published apps aren't able to make use of the privileged APIs. To make use of these APIs your app needs to be a Packaged App and have its ZIP file signed using the Firefox Marketplace submission process.
Your app cannot make use of Firefox Marketplace in-app purchases.
You'll need to implement your own discovery technique, as you won't have the benefit of a Firefox Marketplace listing.

Self-publishing packaged apps

You can self-publish a Packaged App by hosting its ZIP on a server, along with a mini-manifest. The mini-manifest must be in the same directory as the ZIP and is used to identify the app to the install process. You then create a script to invoke Apps.installPackage passing it details of the mini-manifest. Let's look at how to do this in detail:

Zip up your app's contents and give it the name package.zip. This file should contain all the app's resource files, including the (main) manifest.

Caution: Take care when zipping the content you wish to appear in the Packaged App and don't include the directory they are contained in. If you zip up the parent directory, the manifest will end up in the wrong place, and the Packaged App will be invalid.
Create a file called manifest.webapp and add the content shown below. This file is known as the mini-manifest, because it's a slightly cut-down version of the manifest file that's included in your Packaged App's ZIP file. It's used by Apps.installPackage to undertake the installation of your app. For more detailed information on the content, please see Mini-manifest fields below.
```
{
    "name": "My sample app",
    "package_path" : "http://my-server.com/my-app-directory/package.zip",
    "version": "1",
    "developer": {
        "name": "A. Developer",
        "url": "http://my-server.com"
    }
}
```

Create the script that will install your app. Here we're using a simple HTML file named index.html , but you can add the script to a button or use any appropriate method to invoke it on your website. The JavaScript on this page calls the Packaged App installer API (Apps.installPackage) and includes callbacks that provide notification of whether the installation was successful or failed.

<html>
  <body>
    <p>Packaged app installation page</p>
    <script>
      // This URL must be a full url.
      var manifestUrl = 'http://my-server.com/my-app-directory/manifest.webapp';
      var req = navigator.mozApps.installPackage(manifestUrl);
      req.onsuccess = function() {
        alert(this.result.origin);
      };
      req.onerror = function() {
        alert(this.error.name);
      };
    </script>
  </body>
</html>

Setup the files on your server or website by copying package.zip, manifest.webapp, and index.html into your chosen directory (my-app-directory in this example).
Now you can install the app using a compatible device (such as a Firefox OS phone). Simply open the index.html file (in this example its path is http://my-server.com/my-app-directory/index.html) and you'll get a prompt asking you to confirm that you want to install the app. Proceed with the installation, and once it's complete your Web page's script will provide an indication of installation success or failure.

Tip: You can host a Packaged App locally and test it on a device. The Web server and the device must be on the same network, and the server must be able to serve requests from the local network. You just need to include the absolute path in the mini-manifest's package_path, in the same way as the absolute path is included normally (see below). Remember to include the port information if you are using a non-standard port, for example http://10.10.12.1:8080/package.zip.

Mini-manifest fields

If you publish your apps in Firefox Marketplace you don't have to worry about creating a mini-manifest, as Firefox Marketplace generates it for you. It does this using the information provided in your app's manifest, the file you included in the app's ZIP. You can find details on the content of this 'main' manifest in App manifest.

For a self-published app you need to create your own mini-manifest. The best way to do this is to make a copy of your 'main' manifest and update it as needed. Using a copy will help with the first requirement of a mini-manifest, that the name, version, developer and locales fields must be the same in both (main and mini) manifests. You then have some additional content to add, fields that are unique to the mini-manifest: package_path, release_notes and size.

package_path (required): The absolute path (full URL, such as http://my-server.com/my-app-directory/package.zip) of the location where the app's zip file is stored.
release_notes (optional): Information about this release of the app. On Firefox Marketplace this information is provided as part of the submission process.

size (optional): The size of the app's zip file in bytes. This information is used by Apps.installPackage to provide a progress indicator during installation.

Here is an example:

{
  "name": "My app",
  "package_path": "http://thisdomaindoesnotexist.org/myapp.zip",
  "version": "1.0",
  "size": 172496,
  "release_notes": "First release",
  "developer": {
    "name": "Developer Name",
    "url": "http://thisdomaindoesnotexist.org/"
  },
  "locales": {
    "fr-FR": {
      "name": "Mon application"
    },
    "se-SE": {
      "name": "Min balla app"
    }
  },
  "icons": {
    "16": "/icons/16.png",
    "32": "/icons/32.png",
    "256": "/icons/256.png"
  }
}

The other fields in this example are:

name (required): The app's name. Maximum length is 128 characters.
version (optional): The version of the app.
developer (optional): Information about the developer, contains the name and url fields. The developer info needs to match between the mini-manifest and the main manifest file in the ZIP.
locales (optional): Localization information. Keys should be in xx-YY format.
icons (optional): Icons for use by the app.

For more detailed information on the content of manifest files, see App manifest.

Self-publishing Hosted Apps

Compared to Packaged Apps, self-publication of a Hosted App is more straightforward, if you create its content in the same way as you would for Firefox Marketplace publication. This basically means creating the manifest file for your app. You then need to add the code to invoke Apps.install. This code is essentially the same as that you would use for a Packaged App, shown above, the only difference being that you can make relative reference to the location of the manifest file if you wish.

Limitations

Self-publishing packaged apps

Mini-manifest fields

Self-publishing Hosted Apps

Also see

Document Tags and Contributors