Gepackte Apps

Eine gepackte App ist eine Offene Web App die all ihre Ressourcen (HTML, CSS, JavaScript, app mainfest und so weiter) komprimiert in einer zip Datei hat, anstatt die Dateien auf einem Webserver zu hosten. EIne gepackte App ist einfach einezip Datei, welche die App Mainfest in dem Hauptverzeichniss trägt. Die App Mainfest muss den Namen manifest.webapp tragen.

Einer der unterschiede zu einer gehosteten App ist, dass eine gepackte App den launch_path in der Mainfest eingetragen haben muss. Dennoch ist es optional den Pfad auch in einer gehosteten App einzutragen.

Anmerkung: Der Firefox Marktplatz unterstützt momentan nur gepackte App´s für Firefox OS.

Zweck einer gepackten App

Der Zweck einer gepackten App ist, das man einen verarbeitbaren Weg hat, um Zugriff auf die sensitiven API´s der Geräte zu haben. Die App muss von dem Store (Wie der Firefox Marktplatz), von dem die App´s verteilt werden geprüft werden. Der Store prüft die App, sobald diese für akzeptabel befunden wird, wird die App kryptographisch mit einem privatem Schlüssel versehen. Das gebit den Verbrauchern der App mehr Sicherheit, dass die App sorgsam auf Sicherheit, Datenschutz und Leistungsfähigkeit geprüft wurde.

Typen einer gepackten App

Es gibt 3 Typen einer gepackten App:

Privilegierte App

Eine privilegierte App wurde durch ein spezielles Verfahren von dem Firefox Marktplatz genehmigt. Dadurch soll mehr Sicherheit für den Benutzer gewährleistet werden, wenn eine App spezielle sensitiven APIs des Gerätes benutzen möchte. Es ist mit nativen Apps auf Plattformen wie iOS oder Android zu vergleichen. Um eine App als privilegierte App zu kennzeichnen muss das type Feld in der der Datei manifest.webapp auf privileged gesetzt werden.

Eine priviligierte App hat folgende Eigenschaften:

Freigegeben durch einen App Store nach einem Code Review oder einer vergleichbraen Prüfung.
Alle resourcen einer App's werden durch den App Store signiert.
Zugriff auf spezielle, sensible Web APIs, auf die nicht vertrauenswürdiger Inhalt nicht zugreifen darf.
Erzwingt eine sogenannte Content Security Policy (CSP). Eine privilegierte App benutz folgende CSP:
```
"default-src *; script-src 'self'; object-src 'none'; style-src 'self' 'unsafe-inline'"
```
Implementiert weitere Anforderungen an die Sicherheit. Siehe Security für mehr Informationen.

Zertifizierte App

Ein zertifiziertes App ist für einen kritischen Systemfunktion wie die Standard Dialer oder die Systemeinstellungen App auf einem Smartphone gedacht. Diese Art von App könnte für kritische Funktionen auf einem Firefox OS Phone verwendet werden . Es ist nicht für Anwendungen von Drittanbietern vorgesehen, so dass die meisten App nich mit anderen Apps funktionieren . Ein zertifiziertes App ist eine verpackte App, die ähnlich einer privilegierten App ist, mit der Ausnahme, dass alle Geräteberechtigungen implizit sind, das heißt, sie ist ohne ausdrückliche Genehmigung durch den Benutzer aktiviert sind. Ein zertifiziertes App muss für ein Gerät genehmigen vom OEM oder Träger, um diese implizite Zustimmung zu kritischen APIs verwenden zu können . Um anzugeben, dass dies eine zertifizierter App ist, fügen Sie den Feldtyp type auf seine manifest.webapp -Datei und legen Sie es auf zertifiziert.

Das folgende ist die CSP für eine zertifizierte App, die geringfügig von der CSP für eine privilegierte App abweicht:

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

Dies hat den Effekt von etwas lockerere Regeln für die Inline-CSP für privilegierte Apps im Vergleich zu zertifizierten Apps. Wenn Sie mehr von der Überlegung dahinter möchten, finden Sie unter Standard Default CSP policy und Bug 768029.

Plain packaged app

You can also make a regular app that is simply packaged in a zip file. The Marketplace signs it, but does not perform the special authentication process used for privileged or certified apps. This plain packaged app cannot use certain sensitive Web APIs. It is not subject to the CSPs described for privileged and certified apps. This type of app could be useful if you want all of your app's resources available on the device when the user first uses it, with no downloading. This type of packaged app does not require the type field in its manifest.webapp file, because the default value for type (web) is correct.

Using sensitive Web APIs

There are Web APIs that could be used maliciously, so access to them must be controlled. For every sensitive API you want your app to access, you must add an entry to the permissions field in the app's manifest.

Some sensitive APIs can be accessed by normal hosted apps, but other APIs require that you use a packaged app (privileged or certified). See App permissions for a table that describes the requirements.

Packaged apps and the Firefox Marketplace

The Firefox Marketplace handles packaged apps differently from hosted apps. When you submit your packaged app, its zip file is stored on the Marketplace servers, and the Marketplace generates a new manifest called the "mini-manifest" that is based on the app manifest in your packaged app's zip file. When a user installs your app, the mini-manifest is passed to the installPackage() function to install the app. The mini-manifest exists for installation and update purposes and is not used when your app runs.

Testing packaged app installation

To install a packaged app on a Firefox OS device using the Simulator for testing purposes, see the section on "Push to Device" in the Simulator guide. To test a packaged app without the Simulator, you can install it on a device from a regular web server by following the steps below, in the Self-publishing packaged apps section.

Self-publishing packaged apps

You can self-publish a packaged app by hosting it on a server along with a mini-manifest in the same directory that identifies the app and is used in the install process. This section covers how to do this detail.

Note that you can also host a packaged app locally and test it on a real device. The Web server and the phone 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 to the referenced files, in the same way as the absolute paths are included normally (see below.) Remember to include the port information if you are using a non-standard port, for example https://10.10.12.1:8080/package.zip.

Steps

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 manifest.

Caution: You must be also careful to zip the contents you wish to appear in the packaged app, and not 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 package.manifest and give it the contents below. This is a mini-manifest used for packaged app installation purposes. It is not the main manifest of your app that is inside the zip file. See Mini-manifest fields if you want more detailed information about mini-manifests.
```
{
    "name": "My sample app",
    "package_path" : "https://my-server.com/my-app-directory/my-app.zip",
    "version": "1",
    "developer": {
        "name": "Chris Mills",
        "url": "https://my-server.com"
    }
}
```

Create a file named index.html with the following contents. This contains sample JavaScript that calls the packaged app (installPackage()) and callbacks for success and failure notification.

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

Copy package.zip, package.manifest, and index.html into your app root directory (my-app-directory in my examples).
Using a compatible device (such as a Firefox OS phone), navigate to the location on your server where you put the example files and confirm the prompt to install the app. The script will give an indication of installation success or failure.

Note: You can not install privileged or certified apps with installations from hosted packages, as they need to be signed. Use the Simulator to test privileged apps.

Mini-manifest fields

Here is a more in-depth example of a mini-manifest:

{
  "name": "My app",
  "package_path": "https://thisdomaindoesnotexist.org/myapp.zip",
  "version": "1.0",
  "size": 172496,
  "release_notes": "First release",
  "developer": {
    "name": "Developer Name",
    "url": "https://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"
  }
}

When the Firefox Marketplace generates a mini-manifest for your app, it pulls information from your app's manifest for some of the fields. You can find documentation for these fields at App manifest. The fields unique to the mini-manifest are package_path, release_notes, and size. The name, version, developer, and locales fields in your app manifest must be exactly the same as in your mini-manifest.

Here is information on the mini-manifest that relates to using it locally for your own testing:

name: (required) The app's name. Maximum length is 128 characters.
package_path: (required) The URL where the app's zip file can be found. You need to make sure the package_path is absolute to where the ZIP file is located.
version: The version of the app.
size: The size of the app's zip file in bytes. This is not necessary for local testing, but provide it to get a progressbar during installation.
release_notes: Information about this release of the app. On the Marketplace this information comes from a Web page that is part of the submission process.
developer: 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: Localization information. Keys should be in xx-YY format.
icons: Icons for use by the app.

Note: Values in package and webapp.manifest need to be the same, otherwise installation will fail. The safest way is to copy manifest.webapp into package.manifest and just add the package_path.

Differences from hosted apps

Packaged apps have the same capabilites as normal website-style Open Web Apps ("hosted" apps), but packaged apps have a few differences:

They have no Internet origin. The one-app-per-origin policy that governs hosted apps does not apply to packaged apps.
They use a special protocol internal to the zip file: app://<uuid>. Example: When you load the content /index.html in a packaged app, you are actually loading something like the following (the UUID will be different):
```
app://550e8400-e29b-41d4-a716-446655440000/index.html
```
The UUID is randomly generated at install time, which means that it is unique per device it is installed on. The app:// protocol will be useful in future releases of the Web runtime for some identity, payment and OAuth flows.
Their resources are accessed from the zip file, which is stored on the device where the app is installed.
For a self-hosted packaged app, you need to include an additional mini-manifest in the same directory as the zipped packaged app, which doesn't need to be called manifest.webapp (you might call it something like package.webapp). See Self-publishing packaged apps above for more details.
They are installed with a different mozApps API function, installPackage(), which for a self-hosted packaged app must point to the mini-manifest.
They enforce a specific CSP for all application content (a hosted app could also use a CSP, but it is not required).
They can embed remote content in iframes, but that content will not have access to privileged APIs nor will it have the default CSP applied to it.
They have an update process for getting new versions of the app to users. Hosted apps do not need this process.

The packaged app can still do things like access a database on a Web server, like a regular hosted app.

Updating packaged apps

For information on updating apps, see Updating apps.

Packaged app example

Firefox OS Boilerplate App