Manifesto do app da Web

O manifesto do app da Web é um arquivo que você cria e informa ao navegador como você quer que seu conteúdo da Web apareça como um app no sistema operacional. O manifesto pode incluir informações básicas, como nome, ícone e cor do tema do app; preferências avançadas, como orientação desejada e atalhos do app; e metadados de catálogo, como capturas de tela.

Cada PWA precisa incluir um único manifesto por app, normalmente hospedado na pasta raiz e vinculado a todas as páginas HTML em que o PWA pode ser instalado. A extensão oficial dele é .webmanifest. Portanto, é possível nomear o manifesto como app.webmanifest.

Como adicionar um manifesto de app da Web ao seu PWA

Para criar um manifesto de app da Web, primeiro crie um arquivo de texto com um objeto JSON que contenha pelo menos um campo name com um valor de string:

app.webmanifest:

{
   "name": "My First Application"
}

Mas criar o arquivo não basta, o navegador precisa saber que ele existe também.

Como vincular ao manifesto

Para que o navegador reconheça o manifesto do seu app da Web, você precisa vinculá-lo ao PWA usando um elemento HTML <link> e o atributo rel definido como manifest em todas as páginas HTML do PWA. Esse processo é parecido com a forma de vincular uma folha de estilo CSS a um documento.

index.html:

<html lang="en">
  <title>This is my first PWA</title>
  <link rel="manifest" href="/app.webmanifest">

Como depurar o manifesto

Para garantir que o manifesto seja configurado corretamente, você pode usar o Inspector no Firefox e no DevTools em todos os navegadores baseados no Chromium.

Para navegadores Chromium

No DevTools

  1. No painel à esquerda, em Aplicativo, selecione Manifesto.
  2. Verifique os campos do manifesto conforme analisado pelo navegador.

Para Firefox

  1. Abra o Inspector.
  2. Acesse a guia "Aplicativo".
  3. Selecione a opção "Manifest" no painel à esquerda.
  4. Verifique os campos do manifesto conforme analisado pelo navegador.

Como projetar sua experiência com PWA

Com o PWA conectado ao manifesto, é hora de preencher os outros campos para definir a experiência dos usuários.

Campos básicos

O primeiro conjunto de campos representa as principais informações sobre seu PWA. Eles são usados para criar o ícone e a janela do PWA instalado e determinar como ele é iniciado. São eles:

name
Nome completo do PWA. Ele vai aparecer com o ícone na tela inicial, na tela de início, na base ou no menu do sistema operacional.
short_name
Opcional. Um nome mais curto para o PWA, usado quando não há espaço suficiente para mostrar o valor total do campo name. Use até 12 caracteres para diminuir a possibilidade de truncamento.
icons
Matriz de objetos de ícone com src, type, sizes e campos purpose opcionais, descrevendo quais imagens precisam representar o PWA.
start_url
O URL que o PWA precisa carregar quando o usuário iniciá-lo usando o ícone de instalação. Recomendamos um caminho absoluto. Portanto, se a página inicial do PWA for a raiz do seu site, você poderá definir como "/" para abri-la quando o app for iniciado. Se você não fornecer um URL inicial, o navegador poderá usar como início o URL do qual o PWA foi instalado. Pode ser um link direto, como os detalhes de um produto, em vez da sua tela inicial.
display
Um de fullscreen, standalone, minimal-ui ou browser, que descreve como o SO precisa desenhar a janela do PWA. Leia mais sobre os diferentes modos de exibição no capítulo "Design do app". A maioria dos casos de uso implementa standalone.
id
Uma string que identifica este PWA de forma exclusiva em relação a outros que podem estar hospedados na mesma origem. Se ele não for definido, o start_url será usado como um valor substituto. Se você mudar o start_url no futuro (por exemplo, ao mudar o valor de uma string de consulta), talvez o navegador não consiga detectar se um PWA já está instalado.

Ícones

O ícone do PWA é uma identidade visual nos dispositivos dos usuários quando instalado. Por isso, é importante definir pelo menos um. Como a propriedade icons é uma coleção de objetos de ícone, é possível definir vários ícones em formatos diferentes para oferecer a melhor experiência aos usuários. Cada navegador escolhe um ou mais ícones com base nas necessidades e no sistema operacional em que está instalado. Os ícones mais próximos às especificações necessárias.

Caso você precise escolher apenas um tamanho de ícone, ele deve ser de 512 por 512 pixels. No entanto, é recomendável fornecer mais tamanhos, incluindo imagens com 192 x 192, 384 x 384 e 1024 x 1024 pixels.

"icons": [
   {
      "src": "icons/512.png",
      "type": "image/png",
      "sizes": "512x512"
   },
   {
      "src": "icons/1024.png",
      "type": "image/png",
      "sizes": "1024x1024"
   }
]

Se você não fornecer um ícone ou os ícones não estiverem nos tamanhos recomendados, você não transmitirá os critérios de instalação em algumas plataformas. Em outras plataformas, o ícone será gerado automaticamente, por exemplo, com base em uma captura de tela do PWA ou usando um ícone genérico.

Ícones mascaráveis

Alguns sistemas operacionais, como o Android, adaptam ícones para diferentes tamanhos e formas. Por exemplo, no Android 12, diferentes fabricantes ou configurações podem mudar a forma dos ícones de círculos para quadrados e quadrados com cantos arredondados. Para oferecer suporte a esses tipos de ícones adaptativos, é possível fornecer um ícone mascarável usando o campo purpose.

Para isso, forneça um arquivo de imagem quadrada que tenha o ícone principal dentro de uma "zona segura", um círculo centralizado no ícone com um raio de 40% da largura do ícone. Veja a imagem abaixo. Os dispositivos com suporte a ícones mascaráveis vão mascarar o ícone conforme necessário.

A área segura marcada como um círculo centralizado de 40% no raio dentro do ícone quadrado

Confira um exemplo de ícone mascarável renderizado em várias formas usadas com frequência:

Na imagem a seguir, se você usar o ícone à esquerda como um ícone mascarável, terá resultados ruins em dispositivos quando uma máscara de forma for aplicada.

Ícone não adequado para mascarar.

Essa imagem pode ser usada com mais padding.

O ícone com mais padding é adequado para máscaras.

Os ícones mascaráveis precisam ter pelo menos 512 por 512. Depois de criar um, você pode adicioná-lo à sua coleção icons para melhorar a experiência em dispositivos compatíveis:

"icons": [
   {
      "src": "/icons/512.png",
      "type": "image/png",
      "sizes": "512x512"
   },
   {
      "src": "/icons/1024.png",
      "type": "image/png",
      "sizes": "1024x1024"
   },
   {
      "src": "/icons/512-maskable.png",
      "type": "image/png",
      "sizes": "512x512",
      "purpose": "maskable"
   },
]

Na maioria dos casos, se o ícone mascarável não for exibido corretamente, é possível melhorá-lo adicionando mais padding. Maskable.app é uma ferramenta on-line sem custo financeiro para testar e criar uma versão mascarável do ícone.

O próximo conjunto de campos a incluir é aquele que vai melhorar a experiência do usuário, mesmo que não seja necessário para instalação.

theme_color
A cor padrão do aplicativo, que às vezes afeta a forma como o SO exibe o site. Por exemplo, a cor da janela e da barra de título no computador ou a cor da barra de status em dispositivos móveis. Essa cor pode ser substituída pelo elemento HTML theme-color <meta>.
background_color
Cor do marcador de posição que será exibida no plano de fundo do app antes do carregamento da folha de estilo. No momento, o Safari no iOS e iPadOS e a maioria dos navegadores para computador ignoram esse campo.
scope
Altera o escopo de navegação do PWA, permitindo que você defina o que é ou não exibido na janela do app instalado. Por exemplo, se você vincular a uma página fora do escopo, ela será renderizada em um navegador no app, e não na janela do PWA. No entanto, isso não altera o escopo do service worker.

A imagem a seguir mostra como o campo theme_color é usado para a barra de título em um dispositivo desktop ao instalar um PWA.

O mesmo PWA instalado no computador com uma cor de tema diferente.

Ao definir cores no manifesto, como em theme_color e background_color, use cores nomeadas CSS, como salmon ou orange, cores RGB, como #FF5500, ou funções de cor sem transparência, como rgb() ou hsl(). Consulte o capítulo Design do app para saber mais.

Testar

Telas de apresentação

Em alguns dispositivos, uma imagem estática é renderizada enquanto o PWA está sendo carregado para fornecer feedback imediato ao usuário.

O Android usa os valores theme_color, background_color e icon para gerar a tela de apresentação.

Quando você instala um PWA no Android, o dispositivo gera uma tela de apresentação com as informações do seu manifesto, como mostrado no diagrama a seguir.

Um PWA no Android com valores diferentes do manifesto.

Por outro lado, o Safari no iOS e no iPadOS não usa o manifesto do app da Web para gerar telas de apresentação. Em vez disso, eles usam uma imagem vinculada de um elemento <link> reservado da mesma forma que gerencia ícones. Consulte o capítulo "Melhorias" para mais detalhes.

Campos estendidos

O próximo conjunto de campos oferece informações adicionais sobre o PWA. Elas são todas opcionais.

lang
Uma tag de idioma que especifica o idioma principal dos valores do manifesto, como en para inglês, pt-BR para português do Brasil ou in para hindi.
dir
A direção para mostrar campos de manifesto com recurso de direção (como name, short_name e description). Os valores válidos são auto, ltr (da esquerda para a direita) e rtl (da direita para a esquerda).
orientation
É a orientação que você quer para o app depois de instalado. Um jogo pode configurar isso para solicitar a orientação apenas de paisagem. Vários valores são aceitos, mas, se incluídos, normalmente serão portrait ou landscape explicitamente.

Campos promocionais

O quarto conjunto de campos permite fornecer informações promocionais sobre seu PWA, por exemplo, em fluxos de instalação, listagens e resultados de pesquisa.

description
Uma explicação do que o PWA faz.
screenshots
Matriz de objetos de captura de tela com src, type e sizes (semelhante ao objeto icons) destinados a mostrar o PWA. Não há restrições de tamanho.
categories
Matriz de categorias a que o PWA deve pertencer para ser usada como dicas para listagens, opcionalmente na lista de categorias conhecidas. Esses valores geralmente são minúsculas.
iarc_rating_id
O código de certificação da Coalizão Internacional de Classificação Indicativa para o PWA, se você tiver um. Ele serve para determinar para qual faixa etária seu PWA é apropriado.

Confira esses campos promocionais em ação hoje mesmo. No Android, por exemplo, se o PWA for instalável e você fornecer valores para pelo menos os campos description e screenshots, a experiência da caixa de diálogo de instalação vai mudar de uma simples barra de informações "Adicionar à tela inicial" para uma caixa de diálogo de instalação mais completa, semelhante à de uma app store.

No Android, você pode obter uma interface de instalação mais agradável se fornecer valores para os campos promocionais, como é possível ver no próximo vídeo.

Veja esses campos promocionais em ação:

Campos das capacidades

Por fim, há vários campos relacionados a diferentes recursos que o PWA pode usar em navegadores com suporte, como os campos shortcuts, share_target e display_overrides, conforme o capítulo Recursos. Há também campos, como related_apps e prefer_related_apps (consulte o capítulo "Detecção" para mais informações) para conectar seu PWA a apps instalados, geralmente de uma app store.

Muitos campos novos podem aparecer no futuro, enquanto os navegadores adicionam mais recursos aos Progressive Web Apps.

Recursos