App manifest

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 aplicativo (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.

Veja Sobre manifestos de aplicativos para ler algumas perguntas frequentes.

Exemplo de manifesto

Você pode copiar o texto seguinte para um arquivo de texto e substituir os valores com as suas próprias informações.

{
  "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": "https://mozillalabs.com"
  },
  "installs_allowed_from": ["*"],
  "appcache_path": "/cache.manifest",
  "locales": {
    "es": {
      "description": "¡Acción abierta emocionante del desarrollo del Web!",
      "developer": {
        "url": "https://es.mozillalabs.com/"
      }
    },
    "it": {
      "description": "Azione aperta emozionante di sviluppo di fotoricettore!",
      "developer": {
        "url": "https://it.mozillalabs.com/"
      }
    }
  },
  "default_locale": "en"
}

Campos

Os campos permitidos em um manifesto são:

name

Um nome legível por humanos para o aplicativo (máximo de 128 caracteres).

description

Uma descrição legível por humanos do aplicativo (máximo de 1024 caracteres).

launch_path

(opcional) O caminho a partir da origem do aplicativo que é carregado quando o aplicativo é executado. Caso não seja incluído, a origem do aplicativo é tratada como o URL de execução. Veja Tratamento dos caminhos.

icons

(opcional) Uma mapeamento de tamanhos de ícones para caminhos (que devem ser caminhos absolutos).Cada um deve conter imagens quadradas que visualmente representam o aplicativo.

Para Windows 7 e Android, os seguintes tamanhos de ícones são suportados:

• 16 x 16
• 32 x 32
• 48 x 48
• 64 x 64
• 128 x 128
• 256 x 256

Note que o Mozilla Marketplace exige que todos aplicativos submetidos tenham no mínimo um ícone com tamanho de pelo menos 128x128.

developer

(opcional) Informação sobre o desenvolvedor do aplicativo, adequada para a visualização em interfaces de dashboard:

name

O nome do desenvolvedor.

url

A URL para um site contendo mais informações sobre o desenvolvedor do aplicativo. Esta URL é tipicamente mostrada quando o usuário clica no nome do desenvolvedor do aplicativo ao visualizar os detalhes sobre o aplicativo dentro do dashboard (ou do navegador).

locales

(opcional) Uma mapeamento para localidades específicas dos dados contidos no manifesto, os quais as interfaces podem usar para mostrar visualizações localizadas. Cada entrada de localização é identificada por uma tag de localidade e contém uma representação esparsa do manifesto. Qualquer campo presente no valor locale substitui o respectivo campo no manifesto. Certos campos não podem ser substituídos, incluindo default_locale, o próprio locales e installs_allowed_from. Um manifesto que substitui qualquer um destes campos é inválido. Quando locales estiver presente, default_locale também deve estar presente.

default_locale

(obrigatório quando locales estiver presente) A tag de localidade para a tradução "padrão" das propriedades do manifesto. Isto é, a localidade dos valores não incluídos no mapeamento de locales.

installs_allowed_from

(opcional) Um array de origens (scheme+domain, por exemplo ["https://marketplace.mozilla.org"]) que tem permissão para iniciar a instalação desse aplicativo. Este campo permite que você explicitamente autorize apenas certos sites ou lojas, com os quais possue um relacionamento, a instalarem seu aplicativo. O array ["*"] significa que instalações deste aplicativo são permitidas a partir de qualquer site. Este é o padrão. Note que [] iria desautorizar a instalação a partir de qualquer site, incluindo seu próprio.

version

(opcional) Uma string que representa a versão do manifesto. O repositório não usa este valor para nada, mas você pode incluir esta string no manifesto e usá-lo para ajudar com situações de atualização. Veja a seção sobre atualizações mais abaixo.

screen_size

(versão futura) (opcional) Um objeto que pode conter propiedades min_height e min_width, que descrevem a altura e largura mínima em pixels que  aplicação precisa de forma a se desenhar corretamente. A interpretação desses valores é deixada a cargo da implementação da loja de aplicativos.

required_features

(versão futura) (opcional) Um array que consiste de um conjunto de valores que descreve funcionalidades específcas que o aplicativo necessita para executar corretamente. Uma lista completa de valores válidos ainda está pendente.

orientation

(versão futura) (opcional) Define a orientação a qual o aplicativo iniciará usando. Pode ser ou "portrait", "landscape", "portrait-secondary" ou "landscape-secondary". As opções sufixadas com "-secondary" implicam uma rotação de 180 graus comparadas com as opções sem este sufixo. Por exemplo, segurar o telefone de cabeça para baixo (mas ainda de maneira à largura ser menor que a altura) implica uma orientação "portrait-secondary". Caso este campo tenha um valor válido, a implementação não irá mudar a orientação do desenho do aplicativo, mesmo se o dispositivo for virado.

fullscreen

(versão futura) (opcional) Marque este valor como "true" ou "false" para indicar se o aplicativo deve ser lançado em modo de tela cheia.

widget

Este campo foi removido. Caso ele seja usado em um manifesto mais antigo, ele será ignorado.

appcache_path

(opcional) O caminho absoluto para o manifesto da cache de aplicação (AppCache).  Quando um aplicativo Open Web é instalado, o manifesto de AppCache será buscado e lido e seus recursos estáticos presentes no header CACHE serão armazenados.

Tratamento dos caminhos

Todos os campos que se referem algum caminho no manifesto devem conter caminhos absolutos (por exemplo, '/images/myicon.png'), e serão servidos a partir da mesma origem que o aplicativo.

Servindo manifestos

O manifesto do aplicativo deve ser servido da mesma origem a qual o aplicativo está sendo servido.

Quando sendo servido a partir de arquivos estáticos, RECOMENDA-SE que o manifesto seja armazenado com uma extensão .webapp.  Manifestos de aplicativos DEVEM ser servidos com um header Content-Type de application/x-web-app-manifest+json (Nota: isto, no momento, não obrigatório para o Firefox, mas é obrigatório para o Marketplace). Manifestos PODEM ser servidos usando SSL para mitigar certas classes de ataques.

Espera-se que o documento seja UTF-8, mas outra codificação pode ser especificada com um parâmetro charset no header Content-Type  (e.g. Content-Type: application/x-web-app-manifest+json; charset=ISO-8859-4).

User Agents, sempre que possível, DEVERIAM identificar de forma significativa a identidade e status TLS do site ao solicitar que o usuário instale o aplicativo.

Servindo a partir do Apache

Em seu arquivo .htaccess, adicione o seguinte:

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

Caso você não tenha um arquivo .htaccess, crie um no diretório raiz do seu servidor. Se isto não funcionar, o seu host pode exigir que você também inclua AddHandler x-web-app-manifest+json .webapp.

Servindo a partir do NGINX

Você precisa editar o seu arquivo mime.types no diretório conf. Ele provavelmente se encontra em /etc/nginx/ ou /opt/nginx/.

Você deve ter algo similar ao mostrado abaixo. Adicione o texto mostrado em negrito.

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

Servindo a partir do GitHub

Caso você sirva seu arquivo de manifesto a partir das páginas hospedadas no GitHub (https://pages.github.com/), o GitHub irá serví-la com o header correto. Você deve usar a extensão .webapp para seu arquivo manifesto. Examplo: manifest.webapp.

Atualizando manifestos

Um aplicativo respeita as regras normais de Web caching e pode, opcionalmente, utilizar mecanismos avançados para acelerar sua inicialização, como o HTML5 AppCache. Dito isto, não existem considerações especiais para atualizar os recursos normais que um aplicativo usa.

Aplicativos Web são differentes, entretanto, na gerencia do manifesto. Algumas mudanças feitas ao manifesto podem requerir aprovação do usuário. Dependendo da implementação do repositório de aplicativos, pode não ficar claro se uma atualização aconteceu.

Para lidar de uma maneira limpa com esta situação, você pode prover um campo version no manifesto do aplicativo. Depois disto você pode checar a versão utilizando o retorno da função navigator.mozApps.getInstalled(). Caso a versão instalada pelo usuário não seja a mais atual, você pode iniciar uma atualização usando a função navigator.mozApps.install().

O valor de version é uma string opaca ao repositório, então você pode usar qualquer esquema de versionamento que você quiser.