mozilla

Revisão 293004 de App manifest

  • Slug da revisão: Apps/Manifest
  • Título da revisão: App manifest
  • ID da revisão: 293004
  • Criado:
  • Criador: lfz
  • É a revisão atual? Não
  • Comentar

Conteúdo da revisão

Um manifesto de aplicativo contém informação necessário para que o navegador web interaja com um aplicativo. Ele provê tanto elementos para serem lidos por humanos (um nome, um conjunto de ícones, uma descrição; possivelmente em várias línguas) quanto elementos para serem lidos por máquinas, que permite ao navegador exibir e executar aplicativos. O manifesto e a origem do aplicativo (protocolo, host name e número de porta) são em conjunto uma descrição completa do aplicativo instalado. O manifesto é codificado em um arquivo como uma estrutura de dados  JSON. Instalar um aplicativo consiste em prover uma URL deste arquivo para o navegador.

Para publicar um aplicativo, a partir de uma página sua, você inicia a instalação do aplictivo (por exemplo, ao chamar navigator.mozApps.install() usando um botão). Quando uma loja ou diretório publica um aplicativo, isto causa a instalação do aplicativo provendo ao navegador o URL do manifesto deste aplicativo.

See About app manifests for a FAQ.

Example manifest

You can copy the following text into a text file, and replace the values with your own information.

{
  "version": "1.0",
  "name": "MozillaBall",
  "description": "Exciting Open Web development action!",
  "icons": {
    "16": "/img/icon-16.png",
    "48": "/img/icon-48.png",
    "128": "/img/icon-128.png"
  },
  "developer": {
    "name": "Mozilla Labs",
    "url": "http://mozillalabs.com"
  },
  "installs_allowed_from": ["*"],
  "appcache_path": "/cache.manifest",
  "locales": {
    "es": {
      "description": "¡Acción abierta emocionante del desarrollo del Web!",
      "developer": {
        "url": "http://es.mozillalabs.com/"
      }
    },
    "it": {
      "description": "Azione aperta emozionante di sviluppo di fotoricettore!",
      "developer": {
        "url": "http://it.mozillalabs.com/"
      }
    }
  },
  "default_locale": "en"
}

Fields

The fields allowed in the manifest include:

name
A human-readable name for the app (maximum length is 128 characters).
description
A human-readable description of the app (maximum length is 1024 characters).
launch_path
(optional) The path within the app's origin that is loaded when the app starts. If not provided, the app's origin is treated as the launch URL. See Path Handling.
icons
(optional) A map of icon sizes to paths (which must be absolute paths). Each must contain square images that visually represent the app.
For Windows 7 and Android, the following icon sizes are supported:
  • 16 x 16
  • 32 x 32
  • 48 x 48
  • 64 x 64
  • 128 x 128
  • 256 x 256

Note that Mozilla Marketplace requires all submitted apps to have at minimum one icon that's at least 128x128.

developer
(optional) Information about the developer of the app, suitable for use in repository and dashboard UIs:
name
The name of the developer.
url
The URL of a site containing more information about the app's developer. This URL is typically rendered when the user clicks on the name of the app's developer while viewing details about an app inside the dashboard (or browser).
locales
(optional) A map of locale-specific overrides of the data contained in the manifest, which UIs use to provide localized views. Each locale entry is keyed on a locale tag and contains a sparse representation of the manifest. Any field that is present in the locale value overrides the matching field in the manifest. Certain fields cannot be overridden, including default_locale, locales itself and installs_allowed_from. A manifest that overrides any of these fields is invalid. When locales is present, default_locale must also be present.
default_locale
(required when locales is present) The locale tag for the "default" translation of manifest properties. That is, the locale of values not included in the locales map.
installs_allowed_from
(optional) An array of origins (scheme+domain, for example ["https://marketplace.mozilla.org"]) that are allowed to trigger installation of this app. This field allows you to explicitly allow only certain sites or stores, with whom you have a relationship, to install your app. The array ["*"] means that installations of this app are allowed from any site. This is the default.  Note that [] would disallow installation from any site, including your own site.
version
(optional) A string that represents the version of the manifest. The repository does not use this value in any way, but you can embed this string into the manifest and extract it to help deal with various update cases. See the section on updating below.
screen_size
(future release) (optional) An object that can contain min_height and min_width properties, which describe the minimum height and width in pixels that the application needs in order to render correctly. Interpretation of these values is left up to the runtime or the app store.
required_features
(future release) (optional) An array that consists of a set of values that describes the mandatory features the app needs in order to run correctly. A full list of valid values is TBD.
orientation
(future release) (optional) Defines the orientation at which the application will initially start. Can be one of "portrait", "landscape", "portrait-secondary" or "landscape-secondary". The options suffixed with "-secondary" imply a 180 degree rotation from the options without the suffix. For instance, holding the phone upside down (but still in a manner where width is less than height), implies the "portrait-secondary" orientation. If this field has a valid value, the runtime will not change the orientation of the view rendering the application even if the device is turned.
fullscreen
(future release) (optional) Set this to "true" or "false" to indicate whether the runtime should launch the app in full-screen mode.
widget
This field has been removed. If it exists in an older manifest, it will be ignored.
appcache_path
(optional) The absolute path to the application cache (AppCache) manifest.  When an Open Web App is installed, the AppCache manifest will be fetched and parsed, and its static assets under the CACHE header will be cached.

Note: Fields other than the ones given here will be ignored.

Path handling

All fields that hold paths in the manifest must be absolute paths (for example, '/images/myicon.png'), and are served from the same origin as the app.

Serving manifests

The app manifest must be served from the same origin that the app is served from.

When served from static files, it is RECOMMENDED that the manifest be stored with a file extension of .webapp.  App manifests MUST be served with a Content-Type header of application/x-web-app-manifest+json (Note: this is currently not enforced by Firefox, but is enforced by Marketplace). Manifests MAY be served over SSL to mitigate certain classes of attacks.

The document is expected to be UTF-8, but another encoding can be specified with a charset parameter on the Content-Type header (i.e. Content-Type: application/x-web-app-manifest+json; charset=ISO-8859-4).

User Agents when possible SHOULD meaningfully message the site identity and TLS status when prompting a user to install an app.

Serving from Apache

In your .htaccess file, add the following:

AddType application/x-web-app-manifest+json .webapp

If you don't have a .htaccess file, create it in the root directory of your server. If this doesn't work, your host may require you to also add AddHandler x-web-app-manifest+json .webapp.

Serving from NGINX

You need to edit your mime.types file in the conf directory. This will probably be located in either /etc/nginx/ or /opt/nginx/.

You should have something similar to below. Add in the bolded section.

types {
  text/html   html htm shtml;
  text/css    css;
  text/xml    xml;
  application/x-web-app-manifest+json   webapp;
}
Serving from GitHub

If you serve your manifest file from GitHub Pages (http://pages.github.com/), GitHub will serve it with the correct header. You must use the .webapp file extension on your manifest file. Example: manifest.webapp.

Updating manifests

An app respects the normal rules for Web caching, and may optionally use advanced mechanisms for improved start-up, like the HTML5 AppCache. Given this, there are no special considerations for updating the normal resources that an app uses.

Web apps are different, however, in the handling of the manifest. Some changes to a manifest may require user approval. Depending on the implementation of the app repository, it may be unclear whether an update has occurred.

As a clean way to deal with this issue, you can provide a version property in the app manifest. You can later check the version by inspecting the return value of the navigator.mozApps.getInstalled() function. If the user's installed version is not up-to-date, you can trigger an update using navigator.mozApps.install().

The value of version is an opaque string to the repository, so you can use whatever versioning scheme you want.

 

Fonte da revisão

<div class="wikistyle">
  <p>Um manifesto de aplicativo contém informação necessário para que o navegador web interaja com um aplicativo. Ele provê tanto elementos para serem lidos por humanos (um nome, um conjunto de ícones, uma descrição; possivelmente em várias línguas) quanto elementos para serem lidos por máquinas, que permite ao navegador exibir e executar aplicativos. O manifesto e a origem do aplicativo (protocolo, host name e número de porta) são em conjunto uma descrição completa do aplicativo instalado. O manifesto é codificado em um arquivo como uma estrutura de dados&nbsp; <a class="external" href="http://www.json.org/" title="http://www.json.org/">JSON</a>. Instalar um aplicativo consiste em prover uma URL deste arquivo para o navegador.</p>
  <p>Para publicar um aplicativo, a partir de uma página sua, você inicia a instalação do aplictivo (por exemplo, ao chamar <a href="/en/DOM/Apps.install" title="en/Apps/Apps_JavaScript_API/navigator.mozApps.install"><code>navigator.mozApps.install()</code></a> usando um botão). Quando uma loja ou diretório publica um aplicativo, isto causa a instalação do aplicativo provendo ao navegador o URL do manifesto deste aplicativo.</p>
  See <a href="/en/Apps/FAQs/About_app_manifests" title="https://developer.mozilla.org/en/Apps/FAQs/About_app_manifests">About app manifests</a> for a FAQ.<br />
  <h2 id="Example_manifest">Example manifest</h2>
  <p>You can copy the following text into a text file, and replace the values with your own information.</p>
  <pre class="brush: js">
{
&nbsp; "version": "1.0",
&nbsp; "name": "MozillaBall",
&nbsp; "description": "Exciting Open Web development action!",
&nbsp; "icons": {
&nbsp;&nbsp;&nbsp; "16": "/img/icon-16.png",
&nbsp;&nbsp;&nbsp; "48": "/img/icon-48.png",
&nbsp;&nbsp;&nbsp; "128": "/img/icon-128.png"
&nbsp; },
&nbsp; "developer": {
&nbsp;&nbsp;&nbsp; "name": "Mozilla Labs",
&nbsp;&nbsp;&nbsp; "url": "http://mozillalabs.com"
&nbsp; },
&nbsp; "installs_allowed_from": ["*"],
&nbsp; "appcache_path": "/cache.manifest",
&nbsp; "locales": {
&nbsp;&nbsp;&nbsp; "es": {
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "description": "¡Acción abierta emocionante del desarrollo del Web!",
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "developer": {
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "url": "http://es.mozillalabs.com/"
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; }
&nbsp;&nbsp;&nbsp; },
&nbsp;&nbsp;&nbsp; "it": {
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "description": "Azione aperta emozionante di sviluppo di fotoricettore!",
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "developer": {
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; "url": "http://it.mozillalabs.com/"
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; }
&nbsp;&nbsp;&nbsp; }
&nbsp; },
&nbsp; "default_locale": "en"
}
</pre>
  <h2 id="Fields">Fields</h2>
  <p>The fields allowed in the manifest include:</p>
  <dl>
    <dt>
      name</dt>
    <dd>
      A human-readable name for the app (maximum length is 128 characters).</dd>
    <dt>
      description</dt>
    <dd>
      A human-readable description of the app (maximum length is 1024 characters).</dd>
    <dt>
      launch_path</dt>
    <dd>
      (optional) The path within the app's origin that is loaded when the app starts. If not provided, the app's origin is treated as the launch URL. See <a href="#path-handling">Path Handling</a>.</dd>
    <dt>
      icons</dt>
    <dd>
      (optional) A map of icon sizes to paths (which must be <a href="#path-handling">absolute paths</a>). Each must contain square images that visually represent the app.</dd>
    <dd>
      For Windows 7 and Android, the following icon sizes are supported:
      <ul>
        <li>16 x 16</li>
        <li>32 x 32</li>
        <li>48 x 48</li>
        <li>64 x 64</li>
        <li>128 x 128</li>
        <li>256 x 256</li>
      </ul>
      <p>Note that Mozilla Marketplace requires all submitted apps to have at minimum one icon that's at least 128x128.</p>
    </dd>
    <dt>
      developer</dt>
    <dd>
      (optional) Information about the developer of the app, suitable for use in repository and dashboard UIs:
      <dl>
        <dt>
          name</dt>
        <dd>
          The name of the developer.</dd>
        <dt>
          url</dt>
        <dd>
          The URL of a site containing more information about the app's developer. This URL is typically rendered when the user clicks on the name of the app's developer while viewing details about an app inside the dashboard (or browser).</dd>
      </dl>
    </dd>
    <dt>
      locales</dt>
    <dd>
      (optional) A map of locale-specific overrides of the data contained in the manifest, which UIs use to provide localized views. Each locale entry is keyed on a <a class="external" href="http://www.ietf.org/rfc/rfc4646.txt">locale tag</a>&nbsp;and contains a sparse representation of the manifest. Any field that is present in the <code>locale</code> value overrides the matching field in the manifest. Certain fields cannot be overridden, including <code>default_locale</code>, <code>locales</code> itself and <code>installs_allowed_from</code>. A manifest that overrides any of these fields is invalid. When <code>locales</code> is present, <code>default_locale</code> must also be present.</dd>
    <dt>
      default_locale</dt>
    <dd>
      (required when <code>locales</code> is present) The locale tag for the "default" translation of manifest properties. That is, the locale of values not included in the <code>locales</code> map.</dd>
    <dt>
      installs_allowed_from</dt>
    <dd>
      (optional) An array of origins (scheme+domain, for example <code>["<a class="link-https" href="https://marketplace.mozilla.org" rel="freelink">https://marketplace.mozilla.org</a>"]</code>) that are allowed to trigger installation of this app. This field allows you to explicitly allow only certain sites or stores, with whom you have a relationship, to install your app. The array [<code>"*"]</code> means that installations of this app are allowed from any site. This is the default.&nbsp; Note that <code>[]</code> would disallow installation from any site, including your own site.</dd>
    <dt>
      version</dt>
    <dd>
      (optional) A string that represents the version of the manifest. The repository does not use this value in any way, but you can embed this string into the manifest and extract it to help deal with various update cases. See the section on updating below.</dd>
    <dt>
      screen_size</dt>
    <dd>
      (future release) (optional) An object that can contain min_height and min_width properties, which describe the minimum height and width in pixels that the application needs in order to render correctly. Interpretation of these values is left up to the runtime or the app store.</dd>
    <dt>
      required_features</dt>
    <dd>
      (future release) (optional) An array that consists of a set of values that describes the mandatory features the app needs in order to run correctly. A full list of valid values is TBD.</dd>
    <dt>
      orientation</dt>
    <dd>
      (future release) (optional) Defines the orientation at which the application will initially start. Can be one of "portrait", "landscape", "portrait-secondary" or "landscape-secondary". The options suffixed with "-secondary" imply a 180 degree rotation from the options without the suffix. For instance, holding the phone upside down (but still in a manner where width is less than height), implies the "portrait-secondary" orientation. If this field has a valid value, the runtime will not change the orientation of the view rendering the application even if the device is turned.</dd>
    <dt>
      fullscreen</dt>
    <dd>
      (future release) (optional) Set this to "true" or "false" to indicate whether the runtime should launch the app in full-screen mode.</dd>
    <dt>
      widget</dt>
    <dd>
      This field has been removed. If it exists in an older manifest, it will be ignored.</dd>
    <dt>
      appcache_path</dt>
    <dd>
      (optional) The absolute path to the application cache (<a href="/en/HTML/Using_the_application_cache" title="https://developer.mozilla.org/en/Offline_resources_in_Firefox">AppCache</a>) manifest.&nbsp; When an Open Web App is installed, the AppCache manifest will be fetched and parsed, and its static assets under the CACHE header will be cached.</dd>
  </dl>
  <div class="note style-wrap">
    <p><strong>Note:</strong> Fields other than the ones given here will be ignored.</p>
  </div>
  <h2 id="Path_handling_">Path handling <a name="path-handling"></a></h2>
  <a name="path-handling"> </a>
  <p><a name="path-handling">All fields that hold paths in the manifest must be absolute paths (for example, '/images/myicon.png'), and are served from the same origin as the app.</a></p>
  <h2 id="Serving_manifests"><a name="path-handling">Serving manifests</a></h2>
  <p><a name="path-handling">The app manifest must be served from the same origin that the app is served from.</a></p>
  <p><a name="path-handling">When served from static files, it is RECOMMENDED that the manifest be stored with a file extension of <code>.webapp</code>.&nbsp; App manifests MUST be served with a <code>Content-Type</code> header of <code>application/x-web-app-manifest+json</code> (Note: this is currently not enforced by Firefox, but is enforced by Marketplace). Manifests MAY be served over SSL to mitigate certain classes of attacks.</a></p>
  <p><a name="path-handling">The document is expected to be UTF-8, but another encoding can be specified with a <code>charset</code> parameter on the <code>Content-Type</code> header (i.e. <code>Content-Type: application/x-web-app-manifest+json; charset=ISO-8859-4</code>).</a></p>
  <p><a name="path-handling">User Agents when possible SHOULD meaningfully message the site identity and TLS status when prompting a user to install an app.</a></p>
  <h5 id="Serving_from_Apache"><a name="path-handling">Serving from Apache</a></h5>
  <p><a name="path-handling">In your .htaccess file, add the following:</a></p>
  <pre>
<a name="path-handling">AddType application/x-web-app-manifest+json .webapp
</a></pre>
  <div class="note">
    <a name="path-handling"><strong>Note:</strong> This assumes you're using .webapp as an extension. If you are using .json or another extension, you will have to update the code to reflect that.</a></div>
  <p><a name="path-handling">If you don't have a .htaccess file, create it in the root directory of your server. If this doesn't work, your host may require you to also add <code>AddHandler x-web-app-manifest+json .webapp</code>.</a></p>
  <h5 id="Serving_from_NGINX"><a name="path-handling">Serving from NGINX</a></h5>
  <p><a name="path-handling">You need to edit your mime.types file in the conf directory. This will probably be located in either /etc/nginx/ or /opt/nginx/.</a></p>
  <p><a name="path-handling">You should have something similar to below. Add in the bolded section.</a></p>
  <pre>
<a name="path-handling">types {
  text/html   html htm shtml;
  text/css    css;
  text/xml    xml;
<strong>  application/x-web-app-manifest+json   webapp;</strong>
}
</a></pre>
  <div class="note">
    <a name="path-handling"><strong>Note:</strong> This assumes you're using .webapp as an extension. If you are using .json or another extension, you will have to update the code to reflect that.</a></div>
  <h5 id="Serving_from_GitHub"><a name="path-handling">Serving from GitHub</a></h5>
  <p><a name="path-handling">If you serve your manifest file from GitHub Pages (</a><a class="external" href="http://pages.github.com/" title="http://pages.github.com/">http://pages.github.com/</a>), GitHub will serve it with the correct header. You must use the <code>.webapp</code> file extension on your manifest file. Example: <code>manifest.webapp</code>.</p>
  <h2 id="Updating_manifests">Updating manifests</h2>
  <p>An app respects the normal rules for Web caching, and may optionally use advanced mechanisms for improved start-up, like the <a class="external" href="http://www.whatwg.org/specs/web-apps/current-work/multipage/offline.html#offline">HTML5 AppCache</a>. Given this, there are no special considerations for updating the normal resources that an app uses.</p>
  <p>Web apps are different, however, in the handling of the manifest. Some changes to a manifest may require user approval. Depending on the implementation of the app repository, it may be unclear whether an update has occurred.</p>
  <p>As a clean way to deal with this issue, you can provide a <code>version</code> property in the app manifest. You can later check the version by inspecting the return value of the <a href="/en/DOM/Apps.getInstalled" title="en/Apps/Apps_JavaScript_API/navigator.mozApps.getInstalled"><code>navigator.mozApps.getInstalled()</code></a> function. If the user's installed version is not up-to-date, you can trigger an update using <code><a href="/en/DOM/Apps.install" title="https://developer.mozilla.org/en/Apps/Apps_JavaScript_API/navigator.mozApps.install">navigator.mozApps.install()</a>.</code></p>
  <p>The value of <code>version</code> is an opaque string to the repository, so you can use whatever versioning scheme you want.</p>
</div>
<p>&nbsp;</p>
Reverter para esta revisão