mozilla

Revision 451441 of Aplicaciones empaquetadas

  • Revision slug: Aplicaciones/Packaged_apps
  • Revision title: Aplicaciones empaquetadas
  • Revision id: 451441
  • Created:
  • Creator: driverInside
  • Is current revision? No
  • Comment

Revision Content

Una aplicación empaquetada es una Open Web App que tiene todos sus recursos (HTML, CSS, JavaScript, manifiesto y demás) empaquetados en un archivo zip, en lugar de tenerlos en un servidor web. Una aplicación empaquetada es simplemente un archivo zip con el manifiesto de la aplicacion en su directorio raíz. El manifiesto debe ser llamado manifest.webapp.

Una direferencia de una aplicación alojada es que una aplicación empaquetada, es que debe especificar una ruta de arranque en el manifiesto en tanto que se trata de un campo opcional en una aplicación alojada.

Note: Actualmente (Enero 2013) Firefox Marketplace solamente soporta aplicaciones empaquetadas para Firefox OS.

Propósito de las aplicaciones empaquetadas.

El propósito de una aplicación empaquetada, es tener una forma viable de proveer aplicaciones que tengan acceso a APIs sensibles en el dispositivo. Las aplicaciones deben ser verificadas por la tienda donde es distribuida (como Firefox Markerplace). La tienda revisa la aplicación y si la encuentra aceptable, firma el archivo zip de la aplicación con su llave privada. Esto da a los usuarios de la aplicación más seguridad de que han sido revisados problemas potenciales de seguridad, privacidad y capacidad.

Tipos de aplicaciones empaquetadas.

Aplicaciones privilegiadas

Una aplicación privilegiada es aprovada por la Firefox Marketplace usando un proceso especial. Esto significa que provee más seguridad a los usuarios cuando la aplicación quiere accesar a ciertas APIs sensibles del dispositivo. Esto equivale a las aplicaciones nativas en plataformas como iOS o Android. Para especificar que se trata de una aplicación privilegiada agregue el campo type a su archivo manifest.webapp  y establezca el valor de privileged.
Una aplicación privilegiada tiene las siguientes características :
  • Es aprovada por una tienda de aplicaciones después de la revisión de código o equivalente.
  • Los recursos de la aplicación son firmados por la tienda de aplicaciones.
  • Permite usar ciertas APIs Web sensibles a las que contenido no confiable no puede accesar.
  • Aplica Politicas de seguridad de contenido (CSP). Una aplicacion con privilegios utiliza estas CSP:
    "default-src *; script-src 'self'; object-src 'none'; style-src 'self' 'unsafe-inline'"
  • Implementa otros requisitos relacionados con la seguridad. Vea Seguridad para mas informacion.
Certified app
Una aplicacion certificada está destinada a una función crítica del sistema como el marcado por defecto o la configuración del sistema en un teléfono inteligente. Este tipo de aplicación podría ser usada para funciones críticas en un teléfono con Firefox OS. No está destinada para aplicaciones de terceros por lo que la mayoría de desarrolladores no pueden utilizarlas. Una aplicación certificada es una aplicación empaquetada similar a una con privilegios, excepto que todos los permisos del dispositivos son implícitos, lo que significa que son habilitados sin la aprobación explícita del usuario. A certified app must be approved for a device by the OEM or carrier in order to have this implicit approval to use critical APIs. To specify that an app is a certified app, add the type field to its manifest.webapp file and set it to certified.
The following is the CSP for a certified app, which is slightly different from the CSP for a privileged app:
"default-src *; script-src 'self'; object-src 'none'; style-src 'self'"
This has the effect of slightly looser rules for inline CSP for privileged apps when compared to certified apps. If you want more of the reasoning behind this, see Default CSP policy and 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.

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.

  • 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": "http://<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 = 'http://<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 http://<server-ip>/install.html and confirm the prompt to install the app. The script will give an indication of installation success or failure.

Note: If you want to test certified app APIs (described above), turn on "developer mode" on the device you want to install the app on (Firefox OS) and make sure to specify the correct type in your manifest.webapp file.

Mini-manifest fields

Here is an example of a mini-manifest:

{
  "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"
  }
}

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

Packaged app example

Firefox OS Boilerplate App

Revision Source

<p>Una <strong>aplicación empaquetada</strong> es una <em>Open Web App</em> que tiene todos sus recursos (HTML, CSS, JavaScript, manifiesto y demás) empaquetados en un archivo zip, en lugar de tenerlos en un servidor web. Una aplicación empaquetada es simplemente un archivo zip con el <a href="/en-US/docs/Web/Apps/Manifest">manifiesto de la aplicacion </a>en su directorio raíz. El manifiesto debe ser llamado <code>manifest.webapp</code>.</p>
<p>Una direferencia de una aplicación alojada es que una aplicación empaquetada, es que debe especificar una ruta de arranque en el manifiesto en tanto que se trata de un campo opcional en una aplicación alojada.</p>
<div class="note">
  <p><strong>Note:</strong> Actualmente (Enero 2013) Firefox Marketplace solamente soporta aplicaciones empaquetadas para Firefox OS.</p>
</div>
<h2 id="Prop.C3.B3sito_de_las_aplicaciones_empaquetadas.">Propósito de las aplicaciones empaquetadas.</h2>
<p>El propósito de una aplicación empaquetada, es tener una forma viable de proveer aplicaciones que tengan acceso a APIs sensibles en el dispositivo. Las aplicaciones deben ser verificadas por la tienda donde es distribuida (como Firefox Markerplace). La tienda revisa la aplicación y si la encuentra aceptable, firma el archivo zip de la aplicación con su llave privada. Esto da a los usuarios de la aplicación más seguridad de que han sido revisados problemas potenciales de seguridad, privacidad y capacidad.</p>
<h2 id="Tipos_de_aplicaciones_empaquetadas.">Tipos de aplicaciones empaquetadas.</h2>
<p>Aplicaciones privilegiadas</p>
<dl>
  <dd>
    Una <em>aplicación privilegiada</em> es aprovada por la Firefox Marketplace usando un proceso especial. Esto significa que provee más seguridad a los usuarios cuando la aplicación quiere accesar a ciertas APIs sensibles del dispositivo. Esto equivale a las aplicaciones nativas en plataformas como iOS o Android. Para especificar que se trata de una aplicación privilegiada agregue el campo <a href="/en-US/docs/Web/Apps/Manifest#type"><code>type</code></a> a su archivo <code>manifest.webapp</code>&nbsp; y establezca el valor de <code>privileged</code>.</dd>
  <dd>
    Una aplicación privilegiada tiene las siguientes características :
    <ul>
      <li>Es aprovada por una tienda de aplicaciones después de la revisión de código o equivalente.</li>
      <li>Los recursos de la aplicación son firmados por la tienda de aplicaciones.</li>
      <li>Permite usar ciertas APIs Web sensibles a las que contenido no confiable no puede accesar.</li>
      <li>Aplica <a href="/en-US/docs/Security/CSP/Introducing_Content_Security_Policy">Politicas de seguridad de contenido</a> (CSP). Una aplicacion con privilegios utiliza estas CSP:
        <pre>
"default-src *; script-src 'self'; object-src 'none'; style-src 'self' 'unsafe-inline'"</pre>
      </li>
      <li>Implementa otros requisitos relacionados con la seguridad. Vea <a href="https://wiki.mozilla.org/Apps/Security">Seguridad</a> para mas informacion.</li>
    </ul>
  </dd>
  <dt>
    Certified app</dt>
  <dd>
    Una aplicacion certificada está destinada a una función crítica del sistema como el marcado por defecto o la configuración del sistema en un teléfono inteligente. Este tipo de aplicación podría ser usada para funciones críticas en un teléfono con Firefox OS. No está destinada para aplicaciones de terceros por lo que la mayoría de desarrolladores no pueden utilizarlas. Una aplicación certificada es una aplicación empaquetada similar a una con privilegios, excepto que todos los permisos del dispositivos son implícitos, lo que significa que son habilitados sin la aprobación explícita del usuario. A certified app must be approved for a device by the OEM or carrier in order to have this implicit approval to use critical APIs. To specify that an app is a certified app, add the <a href="/en-US/docs/Web/Apps/Manifest#type"><code>type</code></a> field to its <code>manifest.webapp</code> file and set it to <code>certified</code>.</dd>
  <dd>
    The following is the CSP for a certified app, which is slightly different from the CSP for a privileged app:
    <pre>
"default-src *; script-src 'self'; object-src 'none'; style-src 'self'"</pre>
    This has the effect of slightly looser rules for inline CSP for privileged apps when compared to certified apps. If you want more of the reasoning behind this, see <a href="https://wiki.mozilla.org/Apps/Security#Default_CSP_policy">Default CSP policy</a> and <a href="https://bugzilla.mozilla.org/show_bug.cgi?id=768029">Bug 768029</a>.</dd>
  <dt>
    Plain packaged app</dt>
  <dd>
    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 <code>type</code> field in its <code>manifest.webapp</code> file, because the default value for <code>type</code> (<code>web</code>) is correct.</dd>
</dl>
<h2 id="Differences_from_hosted_apps">Differences from hosted apps</h2>
<p>Packaged apps have the same capabilites as normal website-style Open Web Apps ("hosted" apps), but packaged apps have a few differences:</p>
<ul>
  <li>They have no Internet origin. The one-app-per-origin policy that governs hosted apps does not apply to packaged apps.</li>
  <li>They use a special protocol internal to the zip file: <code>app://&lt;uuid&gt;</code>. Example: When you load the content <code>/index.html</code> in a packaged app, you are actually loading something like the following (the UUID will be different):
    <pre>
app://550e8400-e29b-41d4-a716-446655440000/index.html</pre>
    <p>The UUID is randomly generated at install time, which means that it is unique per device it is installed on. The <code>app://</code> protocol will be useful in future releases of the Web runtime for some identity, payment and OAuth flows.</p>
  </li>
  <li>The manifest file must be named <code>manifest.webapp</code>.</li>
  <li>Their resources are accessed from the zip file, which is stored on the device where the app is installed.</li>
  <li>They are installed with a different <code>mozApps</code> API function: <code>installPackage()</code>.</li>
  <li>They enforce a specific <a href="/en-US/docs/Security/CSP/Introducing_Content_Security_Policy">CSP</a> for all application content (a hosted app could also use a CSP, but it is not required).</li>
  <li>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.</li>
  <li>They have an update process for getting new versions of the app to users. Hosted apps do not need this process.</li>
</ul>
<p>The packaged app can still do things like access a database on a Web server, like a regular hosted app.</p>
<h2 id="Using_sensitive_Web_APIs">Using sensitive Web APIs</h2>
<p>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 <code>permissions</code> field in the <a href="/en-US/docs/Web/Apps/Manifest">app's manifest</a>.</p>
<p>Some sensitive APIs can be accessed by normal hosted apps, but other APIs require that you use a packaged app (privileged or certified). See <a href="/en-US/docs/Web/Apps/App_permissions">App permissions</a> for a table that describes the requirements.</p>
<h2 id="Packaged_apps_and_the_Firefox_Marketplace">Packaged apps and the Firefox Marketplace</h2>
<p>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 <code>installPackage()</code> function to install the app. The mini-manifest exists for installation and update purposes and is not used when your app runs.</p>
<h2 id="Testing_packaged_app_installation_(with_Simulator)">Testing packaged app installation (with Simulator)</h2>
<p>To install a packaged app on a Firefox OS device using the Simulator, see the <a href="/en-US/docs/Tools/Firefox_OS_Simulator#Push_to_device">section on "Push to Device" in the Simulator guide</a>.</p>
<h2 id="Testing_packaged_app_installation_(without_Simulator)">Testing packaged app installation (without Simulator)</h2>
<p>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.</p>
<h3 id="Requirements">Requirements</h3>
<ul>
  <li>The Web server must be on the same network as the phone, and it must be able to serve requests from the local network.</li>
  <li>The phone must be running Firefox OS and must be on Wi-Fi.</li>
  <li>Modify the file paths used in the following example code to match your server.</li>
  <li>Get your server's IP address and use it in place of <strong><code>&lt;server-ip&gt;</code></strong> in the examples below. If the server uses a non-standard port, use that also. Example IP address with a non-standard port:
    <pre>
10.10.12.1:8080</pre>
  </li>
</ul>
<h3 id="Steps">Steps</h3>
<ol>
  <li>Have your packaged app's zip file available and give it the name <code>package.zip</code>. This file contains all the app's resource files, including the manifest.</li>
  <li>Create a file called <code>package.manifest</code> 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 <a href="#Mini-manifest_fields">Mini-manifest fields</a> if you want more information about mini-manifests.
    <pre class="brush: js">
{
  "name": "My App",
  "package_path": "http://<strong>&lt;server-ip&gt;</strong>/package.zip",
  "version": "1.0"
}</pre>
  </li>
  <li>Create a file named <code>install.html</code> with the following contents. This contains the JavaScript that calls the packaged app (<a href="/en-US/docs/Web/API/Apps.installPackage"><code>installPackage()</code></a>) and callbacks for success and failure notification.
    <pre class="brush: html">
&lt;html&gt;
&nbsp; &lt;body&gt;
&nbsp; &nbsp; &lt;p&gt;Packaged app installation page&lt;/p&gt;
&nbsp; &nbsp; &lt;script&gt;
      // This URL must be a full url.
&nbsp; &nbsp; &nbsp; var manifestUrl = 'http://<strong>&lt;server-ip&gt;</strong>/package.manifest';
&nbsp; &nbsp; &nbsp; var req = navigator.mozApps.installPackage(manifestUrl);
&nbsp; &nbsp; &nbsp; req.onsuccess = function() {
&nbsp; &nbsp; &nbsp; &nbsp; alert(this.result.origin);
&nbsp; &nbsp; &nbsp; };
&nbsp; &nbsp; &nbsp; req.onerror = function() {
&nbsp; &nbsp; &nbsp; &nbsp; alert(this.error.name);
&nbsp; &nbsp; &nbsp; };
&nbsp; &nbsp; &lt;/script&gt;
&nbsp; &lt;/body&gt;
&lt;/html&gt;</pre>
  </li>
  <li>Copy <code>package.zip</code>, <code>package.manifest</code>, and <code>install.html</code> into the Web server's document root folder.</li>
  <li>Use the browser on the phone to open <code>http://<strong>&lt;server-ip&gt;</strong>/install.html</code> and confirm the prompt to install the app. The script will give an indication of installation success or failure.</li>
</ol>
<div class="note">
  <p><strong>Note:</strong> If you want to test certified app APIs (described above), turn on "developer mode" on the device you want to install the app on (Firefox OS) and make sure to specify the correct <a href="/en-US/docs/Web/Apps/Manifest#type"><code>type</code></a> in your <code>manifest.webapp</code> file.</p>
</div>
<h2 id="Mini-manifest_fields">Mini-manifest fields</h2>
<p>Here is an example of a mini-manifest:</p>
<pre class="brush: js">
{
  "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"
  }
}
</pre>
<p>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 <a href="/en-US/docs/Web/Apps/Manifest">App manifest</a>. The fields unique to the mini-manifest are <code>package_path</code>, <code>release_notes</code>, and <code>size</code>. The <code>name</code>, <code>version</code>, <code>developer</code>, and <code>locales</code> fields in your app manifest must be exactly the same as in your mini-manifest.</p>
<p>Here is information on the mini-manifest that relates to using it locally for your own testing:</p>
<dl>
  <dt>
    <code>name</code></dt>
  <dd>
    (required) The app's name. Maximum length is 128 characters.</dd>
  <dt>
    <code>package_path</code></dt>
  <dd>
    (required) A full URL where the app's zip file can be found.</dd>
  <dt>
    <code>version</code></dt>
  <dd>
    The version of the app.</dd>
  <dt>
    <code>size</code></dt>
  <dd>
    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.</dd>
  <dt>
    <code>release_notes</code></dt>
  <dd>
    Information about this release of the app. On the Marketplace this information comes from a Web page that is part of the submission process.</dd>
  <dt>
    <code>developer</code></dt>
  <dd>
    Information about the developer, contains the <code>name</code> and <code>url</code> fields.</dd>
  <dt>
    <code>locales</code></dt>
  <dd>
    Localization information.</dd>
  <dt>
    <code>icons</code></dt>
  <dd>
    Icons for use by the app.</dd>
</dl>
<h2 id="Updating_packaged_apps">Updating packaged apps</h2>
<p>For information on updating apps, see <a href="/en-US/docs/Web/Apps/Updating_apps">Updating apps</a>.</p>
<h2 id="Packaged_app_example">Packaged app example</h2>
<p><a href="https://github.com/robnyman/Firefox-OS-Boilerplate-App" title="https://github.com/robnyman/Firefox-OS-Boilerplate-App">Firefox OS Boilerplate App</a></p>
Revert to this revision