Apps empacotado

Um aplicativo empacotado ou App empacotado e é um Open Web App que tem todos os seus recursos (HTML, CSS, JavaScript, app manifest, e assim por diante) contido em um arquivo zip, em vez de ter os seus recursos em um servidor Web. Um aplicativo empacotado é simplesmente um arquivo zip com o app manifest em seu diretório raiz. O manifesto deve ser nomeado manifest.webapp.

Uma diferença de um aplicativo hospedado é que, um aplicativo empacotado deve especificar um launch_path no manifesto, ao passo que é um parâmetro opcional para um aplicativo hospedado.

Finalidade de aplicativos empacotados

O objetivo de um aplicativo empacotado é ter um caminho viável para fornecer aplicações que tenham acesso a APIs confidenciais em dispositivos. O aplicativo deve ser verificada por meio da loja onde o aplicativo é distribuído (como o Firefox Marketplace). A loja analisa o aplicativo e se ele for considerado aceitável, a loja cryptographically assina arquivo zip do aplicativo com sua chave privada. Isso dá aos usuários do aplicativo mais garantia de que o app foi cuidadosamente revisada para segurança em potencial, privacidade e questões de capacidade.

Tipos de aplicativos empacotados

Existem 3 tipos de aplicativos empacotados:

Privileged app

Um aplicativo privilegiado é aprovado pelo mercado Firefox através de um processo especial. Ele foi criado para proporcionar mais segurança para os usuários quando um aplicativo quer acesso a determinadas APIs confidenciais em um dispositivo. É o equivalente a um aplicativo nativo em uma plataforma como o iOS ou Android. Para especificar que um aplicativo é um aplicativo privilegiado, adicionar o type em seu arquivo manifest.webapp e defini-lo como privileged.

Uma aplicação privilegiada tem as seguintes características:

• Aprovado por uma loja de aplicativos após revisão de código ou equivalente.
• Recursos do aplicativo são assinados pelo app store.
• Permissão para usar certas APIs Web sensível que o conteúdo não confiável não pode ter acesso.
• Impõe uma Content Security Policy (CSP). Um aplicativo privilegiado usa essa CSP:

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

• Implementa outros requisitos relacionados com a segurança. Ver Security para obter mais informações.

Certified app

Um aplicativo certificado destina-se a uma função do sistema crítico como o discador padrão ou o aplicativo de configurações do sistema em um smartphone. Este tipo de aplicação seria utilizada para as funções de críticas de um Firefox OS phone. Ela não se destina a aplicativos de terceiros, por isso a maioria dos desenvolvedores de aplicativos não podem usar esse tipo de aplicativo. Um aplicativo certificado é um aplicativo empacotado que seja semelhante a um aplicativo privilegiado, exceto que todas as permissões do dispositivo são implícitos, ou seja, eles são ativados sem a aprovação explícita do usuário. Um aplicativo certificado deve ser aprovado por um dispositivo OEM ou portador, a fim de ter essa aprovação implícita de usar  APIs críticos. Para especificar que um aplicativo é um aplicativo privilegiado, adicionar o type em seu arquivo manifest.webapp e defini-lo como certified.

 

A seguir é a CSP para uma aplicação certificada, que é ligeiramente diferente do CSP para uma aplicação privilegiada:

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

Isso tem o efeito de regras um pouco mais solto para linha CSP para aplicações privilegiadas quando comparadas às aplicações certificadas. Se você quer saber mais sobre isso, ver Default CSP policy e Bug 768029.

Plain packaged app

Você também pode fazer uma aplicação regular que é simplesmente empacotado em um arquivo zip. O Marketplace aprova eles, mas não executa o processo de autenticação especial usado para aplicações privilegiadas ou certificado. 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.

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. The app:// protocol will be useful in future releases of the Web runtime for some identity, payment and OAuth flows.

• The manifest file must be named manifest.webapp.
• Their resources are accessed from the zip file, which is stored on the device where the app is installed.
• They are installed with a different mozApps API function: installPackage().
• 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.

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

To install a packaged app on a Firefox OS device using the Simulator, see the section on "Push to Device" in the Simulator guide.

Testing packaged app installation (without Simulator)

If you want to locally test the installation of your packaged app, here is another way to do it. Use the steps below to install a packaged app on a phone using a Web server that is on your local network. It can be a Web server that is running on your development computer. This will also give you an idea of how packaged app installation works.

Requirements

• The Web server must be on the same network as the phone, and it must be able to serve requests from the local network.
• The phone must be running Firefox OS and must be on Wi-Fi.
• Modify the file paths used in the following example code to match your server.
• Get your server's IP address and use it in place of <server-ip> in the examples below. If the server uses a non-standard port, use that also. Example IP address with a non-standard port:

  10.10.12.1:8080

Steps

1. Have your packaged app's zip file available and give it the name package.zip. This file contains all the app's resource files, including the manifest.
2. 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 information about mini-manifests.

   {
     "name": "My App",
     "package_path": "https://<server-ip>/package.zip",
     "version": "1.0"
   }

3. Create a file named install.html with the following contents. This contains the 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://<server-ip>/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>

4. Copy package.zip, package.manifest, and install.html into the Web server's document root folder.
5. Use the browser on the phone to open https://<server-ip>/install.html and confirm the prompt to install the app. The script will give an indication of installation success or failure.

Mini-manifest fields

Here is an 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 the 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) A full URL where the app's zip file can be found.

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.

locales

Localization information.

icons

Icons for use by the app.

Updating packaged apps

For information on updating apps, see Updating apps.