Adicionar um manifesto de app da Web

O manifesto do app da Web é um arquivo JSON que informa o navegador sobre seu Progressive Web App e como ele deve se comportar quando instalado no computador ou dispositivo móvel do usuário. Um arquivo de manifesto típico inclui o nome do app, os ícones que ele precisa usar e o URL que precisa ser aberto quando o app é iniciado, entre outras coisas.

Compatibilidade com navegadores

  • 39
  • 79
  • x
  • x

Origem

Criar o arquivo de manifesto

O arquivo de manifesto pode ter qualquer nome, mas costuma ser chamado de manifest.json e veiculado pela raiz, que é o diretório de nível superior do site. A especificação sugere que a extensão seja .webmanifest, mas os navegadores também são compatíveis com extensões .json, que podem ser mais fáceis de entender pelos desenvolvedores.

Um manifesto típico tem a seguinte aparência:

{
  "short_name": "Weather",
  "name": "Weather: Do I need an umbrella?",
  "icons": [
    {
      "src": "/images/icons-vector.svg",
      "type": "image/svg+xml",
      "sizes": "512x512"
    },
    {
      "src": "/images/icons-192.png",
      "type": "image/png",
      "sizes": "192x192"
    },
    {
      "src": "/images/icons-512.png",
      "type": "image/png",
      "sizes": "512x512"
    }
  ],
  "id": "/?source=pwa",
  "start_url": "/?source=pwa",
  "background_color": "#3367D6",
  "display": "standalone",
  "scope": "/",
  "theme_color": "#3367D6",
  "shortcuts": [
    {
      "name": "How's weather today?",
      "short_name": "Today",
      "description": "View weather information for today",
      "url": "/today?source=pwa",
      "icons": [{ "src": "/images/today.png", "sizes": "192x192" }]
    },
    {
      "name": "How's weather tomorrow?",
      "short_name": "Tomorrow",
      "description": "View weather information for tomorrow",
      "url": "/tomorrow?source=pwa",
      "icons": [{ "src": "/images/tomorrow.png", "sizes": "192x192" }]
    }
  ],
  "description": "Weather forecast information",
  "screenshots": [
    {
      "src": "/images/screenshot1.png",
      "type": "image/png",
      "sizes": "540x720",
      "form_factor": "narrow"
    },
    {
      "src": "/images/screenshot2.jpg",
      "type": "image/jpg",
      "sizes": "720x540",
      "form_factor": "wide"
    }
  ]
}

Principais propriedades do manifesto

short_name e/ou name

Você precisa fornecer pelo menos a propriedade short_name ou name. Se ambos forem fornecidos, short_name será usado na tela inicial, na tela de início ou em outros lugares do usuário em que o espaço possa ser limitado. name é usado quando o app está instalado.

icons

Quando um usuário instala seu PWA, você pode definir um conjunto de ícones para o navegador usar na tela inicial, no Acesso rápido aos apps, no seletor de tarefas, na tela de apresentação e assim por diante.

A propriedade icons é uma matriz de objetos de imagem. Cada objeto precisa incluir o src, uma propriedade sizes e o type da imagem. Para usar ícones mascaráveis, às vezes chamados de ícones adaptáveis no Android, também é necessário adicionar "purpose": "any maskable" à propriedade icon.

Para o Chromium, você precisa fornecer pelo menos um ícone de 192 x 192 pixels e um de 512 x 512 pixels. Se apenas esses dois tamanhos forem fornecidos, o Chrome redimensiona os ícones automaticamente para caber no dispositivo. Se preferir dimensionar os próprios ícones e ajustá-los para que fiquem perfeitos, forneça ícones em incrementos de 48 dp.

id

A propriedade id permite definir explicitamente o identificador usado para o aplicativo. Adicionar a propriedade id ao manifesto remove a dependência no start_url ou no local do manifesto, possibilitando que eles sejam atualizados no futuro. Para mais informações, consulte Identificação exclusiva de PWAs com a propriedade do ID do manifesto do app da Web.

start_url

O start_url é obrigatório e informa ao navegador onde seu aplicativo precisa ser iniciado quando iniciado. Além disso, ele impede que o app seja iniciado em qualquer página em que o usuário estava quando adicionou o app à tela inicial.

O start_url precisa direcionar o usuário diretamente para o app, em vez de direcionar para a página de destino do produto. Pense no que o usuário vai querer fazer assim que abrir o app e coloque-o lá.

background_color

A propriedade background_color é usada na tela de apresentação quando o aplicativo é iniciado pela primeira vez em um dispositivo móvel.

display

É possível personalizar a interface do navegador que será exibida quando seu app for iniciado. Por exemplo, você pode ocultar a barra de endereço e os elementos da interface do usuário do navegador. Os jogos podem até ser feitos para iniciar em tela cheia. A propriedade display usa um destes valores:

Propriedade Uso
fullscreen Abre o aplicativo da Web sem qualquer IU do navegador e ocupa toda a área de exibição disponível.
standalone Abre o app da Web para parecer um app autônomo. O app é executado na própria janela, separado do navegador, e oculta elementos padrão da IU do navegador, como a barra de URL.
Exemplo de uma janela de PWA com tela independente.
minimal-ui Esse modo é semelhante ao standalone, mas fornece ao usuário um conjunto mínimo de elementos da IU para controlar a navegação (como voltar e recarregar).
Um exemplo de janela de PWA com exibição de interface mínima.
browser Uma experiência padrão no navegador.

display_override

Os apps da Web podem escolher como serão exibidos definindo um modo display no manifesto, conforme explicado acima. Os navegadores não precisam oferecer suporte a todos os modos de exibição, mas precisam oferecer suporte à cadeia de substituição definida pela especificação ("fullscreen""standalone""minimal-ui""browser"). Se eles não oferecerem suporte a um determinado modo, eles vão voltar para o próximo modo de exibição na cadeia. Em casos raros, esse comportamento inflexível pode ser problemático. Por exemplo, um desenvolvedor não pode solicitar "minimal-ui" sem ser forçado de volta ao modo de exibição "browser" quando "minimal-ui" não tem suporte. Outro problema é que o comportamento atual impossibilita a introdução de novos modos de exibição de maneira compatível com versões anteriores, já que análises detalhadas como o modo de aplicativo com guias não têm um lugar natural na cadeia de substituto.

Esses problemas são resolvidos pela propriedade display_override, que o navegador considera antes da propriedade display. O valor dela é uma sequência de strings consideradas na ordem listada, e o primeiro modo de exibição compatível é aplicado. Se nenhum for compatível, o navegador voltará a avaliar o campo display.

Veja o exemplo abaixo. Os detalhes de "window-control-overlay" estão fora do escopo deste artigo.

{
  "display_override": ["window-control-overlay", "minimal-ui"],
  "display": "standalone",
}

Como indicado, o navegador vai analisar display_override primeiro.

  1. "window-control-overlay"
  2. "minimal-ui"

Se nenhuma opção estiver disponível, ela vai voltar para display. Se "standalone" não estiver disponível, ele retomará a cadeia de outono, definida pela especificação, a partir desse ponto.

  1. "standalone"
  2. "minimal-ui"
  3. "browser"

scope

A scope define o conjunto de URLs que o navegador considera estar no app e é usada para decidir quando o usuário saiu do app. O scope controla a estrutura do URL que abrange todos os pontos de entrada e saída no app da Web. O start_url precisa residir no scope.

Mais algumas observações sobre scope:

  • Se você não incluir um scope no manifesto, o scope implícito padrão será o URL inicial, mas com o nome de arquivo, a consulta e o fragmento removidos.
  • O atributo scope pode ser um caminho relativo (../) ou qualquer caminho de nível superior (/), o que permitiria um aumento na cobertura de navegações no seu app da Web.
  • O start_url precisa estar no escopo.
  • O start_url é relativo ao caminho definido no atributo scope.
  • Um start_url que começa com / sempre será a raiz da origem.

theme_color

A theme_color define a cor da barra de ferramentas e pode ser refletida na visualização do app em seletores de tarefas. O theme_color precisa corresponder à cor do tema meta especificada no cabeçalho do documento.

Um exemplo de janela de PWA com theme_color personalizado.
Exemplo de uma janela de PWA com theme_color personalizado.

No Chromium 93 e no Safari 15, é possível ajustar essa cor em uma consulta de mídia com o atributo media do elemento de cor do tema meta. A primeira correspondência será selecionada. Por exemplo, é possível ter uma cor para o modo claro e outra para o modo escuro. No momento, não era possível defini-las no manifesto. Consulte o problema do w3c/manifest#975 no GitHub.

<meta name="theme-color" media="(prefers-color-scheme: light)" content="white">
<meta name="theme-color" media="(prefers-color-scheme: dark)"  content="black">

shortcuts

A propriedade shortcuts é uma matriz de objetos de atalho do app com o objetivo de fornecer acesso rápido às principais tarefas do app. Cada membro é um dicionário que contém pelo menos um name e um url.

description

A propriedade description descreve a finalidade do app.

screenshots

A propriedade screenshots é uma matriz de objetos de imagem que representam seu app em cenários de uso comuns. Cada objeto precisa incluir o src, uma propriedade sizes e o type da imagem. A propriedade form_factor é opcional. Você pode defini-la como "wide" para capturas de tela aplicáveis apenas a telas grandes ou "narrow" para capturas de tela estreitas.

No Chrome, a imagem precisa responder a determinados critérios:

  • A largura e a altura precisam ter pelo menos 320 px e, no máximo, 3.840 px.
  • A dimensão máxima não pode ser mais de 2,3 vezes maior que a dimensão mínima.
  • Todas as capturas de tela que correspondem ao formato apropriado precisam ter a mesma proporção.
    • A partir do Chrome 109, apenas capturas de tela com o form_factor definido como "wide" são exibidas no computador.
  • No Chrome 109, as capturas de tela com form_factor definido como "wide" são ignoradas no Android. As capturas de tela sem form_factor ainda são exibidas para compatibilidade com versões anteriores.

O Chrome no computador mostra pelo menos uma e no máximo oito capturas de tela que atendem aos critérios acima. O restante será ignorado.

O Chrome no Android mostra pelo menos uma e no máximo cinco capturas de tela que atendem aos critérios acima. O restante será ignorado.

Capturas de tela de uma interface de instalação mais avançada em computadores e dispositivos móveis.
Interface de instalação aprimorada em computadores e dispositivos móveis.

Depois de criar o manifesto, adicione uma tag <link> a todas as páginas do seu Progressive Web App. Por exemplo:

<link rel="manifest" href="/manifest.json">

Testar o manifesto

Para verificar se o manifesto está configurado corretamente, use o painel Manifest no painel Application do Chrome DevTools.

No Chrome, o tamanho máximo da descrição é limitado a 300 caracteres em todas as plataformas. Se a descrição for mais longa que isso, ela será truncada com um caractere de reticências. No Android, há um limite adicional de no máximo sete linhas.

O painel do aplicativo no Chrome Devtools com a guia de manifesto selecionada.
Teste seu manifesto no DevTools.

Esse painel fornece uma versão legível por humanos de muitas das propriedades do manifesto e facilita a verificação de que todas as imagens estão sendo carregadas corretamente.

Telas de apresentação em dispositivos móveis

Quando o app é iniciado pela primeira vez em um dispositivo móvel, pode levar um momento para o navegador ativar e o conteúdo inicial começar a ser renderizado. Em vez de mostrar uma tela branca que pode parecer para o usuário como se o app esteja parado, o navegador mostrará uma tela de apresentação até a primeira exibição.

O Chrome cria a tela de apresentação automaticamente usando as propriedades do manifesto, especificamente:

  • name
  • background_color
  • icons

A background_color precisa ter a mesma cor da página de carregamento para proporcionar uma transição tranquila da tela de apresentação para o app.

O Chrome escolherá o ícone mais próximo da resolução do dispositivo. Fornecer ícones de 192 e 512 pixels é suficiente na maioria dos casos, mas você pode fornecer ícones adicionais para ter pixels perfeitos.

Sugestões de leitura

Há várias outras propriedades que podem ser adicionadas ao manifesto do app da Web. Consulte a documentação do manifesto do app da Web MDN para saber mais.