Adicionar um manifesto de app da Web

Compatibilidade com navegadores

  • 39
  • 79
  • x
  • x

Origem

Um manifesto de app da Web é um arquivo JSON que informa ao navegador como seu Progressive Web App (PWA) se comportará quando instalado no computador ou no dispositivo móvel do usuário. Um arquivo de manifesto típico inclui, no mínimo:

  • O nome do app
  • Os ícones que o app precisa usar
  • O URL que deve ser aberto quando o aplicativo for iniciado

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 precisa ser .webmanifest, mas é recomendável usar arquivos JSON para deixar a leitura dos manifestos mais clara.

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 the 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 the 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 name

Forneça pelo menos short_name ou name no manifesto. Se você fornecer ambos, name será usado quando o app estiver instalado, e short_name será usado na tela inicial, na tela de início ou em outros lugares do usuário em que o espaço é limitado.

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 em outros lugares.

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, adicione "purpose": "any maskable" à propriedade icon.

Para o Chromium, é necessário fornecer um ícone de pelo menos 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 de start_url ou do local do manifesto, possibilitando a atualização delas no futuro. Para mais informações, consulte Como identificar exclusivamente PWAs com a propriedade do ID do manifesto do app da Web.

start_url

O start_url é uma propriedade obrigatória. Ele informa ao navegador onde seu app precisa começar quando for iniciado e impede que o app comece em qualquer página em que o usuário estava quando adicionou o app à tela inicial.

A start_url precisa direcionar o usuário diretamente para o app, não para a página de destino do produto. Pense no que o usuário vai querer fazer imediatamente após abrir seu app e coloque-o lá.

background_color

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

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 criados para serem iniciados em tela cheia. A propriedade display usa um dos seguintes valores:

Propriedade Comportamento
fullscreen Abre o app da Web sem qualquer interface do navegador e ocupa toda a área de exibição disponível.
standalone Abre o app da Web para parecer um app independente. O app é executado na própria janela, separado do navegador, e oculta elementos padrão da IU do navegador, como a barra de endereço.
Exemplo de uma janela de PWA com tela independente.
A interface independente.
minimal-ui Esse modo é semelhante ao standalone, mas fornece ao usuário um conjunto mínimo de elementos da interface para controlar a navegação, como os botões "Voltar" e "Atualizar".
Um exemplo de janela de PWA com exibição de interface mínima.
A interface mínima.
browser Uma experiência padrão no navegador.

display_override

Para escolher como o app da Web será exibido, defina um modo display no manifesto, conforme explicado anteriormente. Os navegadores não precisam oferecer suporte a todos os modos de exibição, mas eles são necessários para 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 retornarão para o próximo modo de exibição na cadeia. Em casos raros, esses substitutos podem causar problemas. Por exemplo, um desenvolvedor não pode solicitar "minimal-ui" sem ser forçado a voltar ao modo de exibição "browser" quando "minimal-ui" não tem suporte. O comportamento atual também torna impossível introduzir novos modos de exibição de maneira compatível com versões anteriores, porque eles não têm lugar na cadeia de substituto.

É possível definir sua própria sequência de substituição usando a 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. Se não houver nenhum campo display, o navegador vai ignorar display_override.

Confira abaixo um exemplo de como usar o display_override. Os detalhes de "window-control-overlay" estão fora do escopo desta página.

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

Ao carregar este app, o navegador tenta usar "window-control-overlay" primeiro. Se isso não estiver disponível, ele vai voltar para "minimal-ui" e, em seguida, para "standalone" da propriedade display. Se nenhum deles estiver disponível, o navegador retornará à cadeia de substituto padrão.

scope

A scope do app é o conjunto de URLs que o navegador considera parte do seu app. O scope controla a estrutura do URL que inclui todos os pontos de entrada e saída do app, e o navegador a usa para determinar quando o usuário saiu do app.

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 (/) que permita 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.

theme_color em consultas de mídia

Compatibilidade com navegadores

  • 93
  • 93
  • 106
  • 15

Origem

Você pode ajustar theme_color em uma consulta de mídia usando o atributo media do elemento de cor do tema meta. Por exemplo, é possível definir uma cor para o modo claro e outra para o modo escuro dessa maneira. No entanto, não é possível definir essas preferências no manifesto. Para saber mais, consulte o problema 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 que fornecem 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.

No Chrome, o tamanho máximo da descrição é de 300 caracteres em todas as plataformas. Se a descrição for mais longa que isso, o navegador a truncará com um caractere de reticências. No Android, a descrição também precisa usar no máximo sete linhas de texto.

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 atender aos seguintes 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 maior que 2,3 vezes o comprimento da 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 a esses critérios. O restante é ignorado.

O Chrome no Android mostra pelo menos uma e no máximo cinco capturas de tela que atendem a esses critérios. O restante é 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.

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 permite verificar se 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 tempo para que o navegador seja iniciado e o conteúdo inicial comece a ser renderizado. Em vez de mostrar uma tela branca que pode fazer o usuário pensar que o app não está funcionando, o navegador mostra uma tela de apresentação até a primeira exibição.

O Chrome cria a tela de apresentação automaticamente a partir de name, background_color e icons especificados no manifesto. Para criar uma transição tranquila da tela de apresentação para o app, use background_color com a mesma cor da página de carregamento.

O Chrome escolhe o ícone que melhor corresponde à resolução do dispositivo para as telas de apresentação. Fornecer ícones de 192 e 512 pixels é suficiente na maioria dos casos, mas você pode fornecer ícones adicionais para uma correspondência melhor.

Leia mais

Para saber mais sobre outras propriedades que podem ser adicionadas ao manifesto do seu app da Web, consulte a documentação do manifesto do app da Web do MDN.