Manifesto do app da Web

O manifesto de app da Web é um arquivo que você cria e informa ao navegador como quer que o conteúdo da Web seja exibido 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 e atalhos de apps desejados; e metadados de catálogo, como capturas de tela.

Cada PWA deve incluir um único manifesto por aplicativo, 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, então você pode dar ao manifesto um nome como app.webmanifest.

Como adicionar um manifesto de app da Web ao 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 é suficiente, o navegador também precisa saber que ele existe.

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. O processo é semelhante à forma como você vincula 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">

Depuração do 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 esquerdo, em Aplicativo, selecione Manifesto.
  2. Verifique os campos do manifesto conforme analisados pelo navegador.

Para Firefox

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

Como criar sua experiência de 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 o PWA. Eles são usados para criar o ícone e a janela do PWA instalado e determinar como ele será iniciado. São eles:

name
Nome completo do PWA. Ele vai aparecer junto 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 do seu PWA, usado quando não há espaço suficiente para exibir o valor total do campo name. Use menos de 12 caracteres para minimizar a possibilidade de truncamento.
icons
Matriz de objetos de ícone com src, type, sizes e campos purpose opcionais, descrevendo quais imagens devem representar o PWA.
start_url
O URL que o PWA precisa ser carregado quando o usuário o inicia pelo ícone de instalação. Recomendamos um caminho absoluto. Portanto, se a página inicial do PWA for a raiz do site, defina-o como "/" para abri-lo quando o app for iniciado. Se você não fornecer um URL de início, o navegador poderá usar o URL a partir do qual o PWA foi instalado. Pode ser um link direto, como os detalhes de um produto, em vez da tela inicial.
display
Um de fullscreen, standalone, minimal-ui ou browser, descrevendo como o SO deve desenhar a janela do PWA. Leia mais sobre os diferentes modos de exibição no capítulo Design de apps. A maioria dos casos de uso implementa standalone.
id
Uma string que identifica exclusivamente esse PWA em relação a outros que podem estar hospedados na mesma origem. Se ele não for definido, o start_url vai ser usado como valor substituto. Lembre-se de que, ao mudar o start_url no futuro (por exemplo, ao mudar o valor de uma string de consulta), a capacidade do navegador de detectar se um PWA já está instalado poderá ser eliminada.
.
.

Ícones

O ícone do seu PWA é a identidade visual na página quando instalados. Por isso, é importante definir pelo menos um deles. Como a propriedade icons é um conjunto de objetos de ícone, é possível definir vários ícones em formatos diferentes para oferecer a melhor experiência aos usuários. Cada navegador escolherá um ou mais ícones com base em suas necessidades e no sistema operacional em que está instalado, os ícones mais próximos das especificações necessárias.

Se você precisar escolher apenas um tamanho de ícone, use 512 por 512 pixels. No entanto, é recomendável fornecer mais tamanhos, incluindo também imagens de 192 por 192, 384 por 384 e 1024 por 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 se ele não estiver nos tamanhos recomendados, em algumas plataformas, você não atenderá aos critérios de instalação. Em outras plataformas, o ícone será gerado automaticamente, por exemplo, em uma captura de tela do PWA ou usando um ícone genérico.

Ícones mascaráveis

Alguns sistemas operacionais, como o Android, adaptam os ícones a 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 para quadrados com cantos arredondados. Para oferecer suporte a esses tipos de ícones adaptativos, você pode 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 compatíveis com ícones mascaráveis mascararão seu ícone conforme necessário.

A área segura marcada como um círculo centralizado com raio de 40% 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 usar o ícone à esquerda como um ícone mascarável, você terá resultados ruins nos dispositivos quando uma máscara de forma for aplicada.

Um ícone que não é adequado para um ícone mascarável.

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 x 512. Com uma conta criada, você pode adicioná-la à sua coleção de icons para melhorar a experiência nos dispositivos com suporte:

"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 estiver sendo exibido corretamente, é possível melhorá-lo adicionando mais padding. O Maskable.app é uma ferramenta on-line sem custo financeiro para testar e criar uma versão mascarável do seu ícone.

O próximo conjunto de campos a incluir são aqueles que melhoram a experiência do usuário, mesmo que não sejam necessários para a instalação.

theme_color
Cor padrão do aplicativo, às vezes afetando 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 aplicativo antes que a folha de estilo seja carregada. No momento, o Safari no iOS e iPadOS e a maioria dos navegadores para computador ignoram esse campo.
scope
Altera o escopo da 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 próxima imagem mostra como o campo theme_color é usado para a barra de título em um dispositivo desktop quando você instala 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 com nomes 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 de apps para mais informações.

Testar

Telas de apresentação

Em alguns dispositivos, uma imagem estática é renderizada enquanto o PWA é 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 manifesto, como mostrado no diagrama a seguir.

Um PWA na tela de apresentação do Android com valores diferentes do manifesto.

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

Campos estendidos

O próximo conjunto de campos oferece mais informações 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 do manifesto com recursos 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
Orientação desejada para o app após a instalação. Um jogo pode configurar esse recurso para solicitar uma orientação somente paisagem. Vários valores são aceitos, mas, se incluídos, normalmente são portrait ou landscape explicitamente.
.

Campos promocionais

O quarto conjunto de campos permite fornecer informações promocionais sobre o 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) para mostrar o PWA. Não há restrições de tamanho.
categories
Matriz de categorias a que o PWA pertence. Elas podem ser usadas como dicas para fichas de empresa, opcionalmente na lista de categorias conhecidas. Normalmente, esses valores ficam em letras minúsculas.
iarc_rating_id
O código da certificação da Coalizão Internacional de Classificação Indicativa para o PWA, se houver. Ele é usado para determinar para quais idades seu PWA é adequado.
.

É possível ver esses campos promocionais em ação hoje. 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 se transformar de um simples "Adicionar à tela inicial". barra de informações para uma caixa de diálogo de instalação mais rica, semelhante à de uma app store.

No Android, você terá uma interface de instalação melhor se fornecer valores para os campos promocionais, como você pode ver no próximo vídeo.

Veja esses campos promocionais em ação:

Campos dos recursos

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 abordamos no capítulo Capabilities. Também há campos, como related_apps e prefer_related_apps (consulte o capítulo Detecção para mais informações) para conectar seu PWA aos apps instalados, geralmente de uma app store.

Muitos campos novos poderão aparecer no futuro, enquanto os navegadores adicionarão mais recursos aos Progressive Web Apps.

Recursos