Manifesto do app da Web

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

Cada PWA precisa incluir um único manifesto por aplicativo, geralmente hospedado na pasta raiz e vinculado em todas as páginas HTML em que a PWA pode ser instalada. A extensão oficial é .webmanifest. Portanto, você pode nomear seu manifesto como app.webmanifest.

Como adicionar um manifesto do 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 é suficiente. O navegador também precisa saber que ele existe.

Vincular ao seu manifesto

Para que o navegador reconheça o manifesto do app da Web, você precisa vincular o manifesto à PWA usando um elemento HTML <link> e o atributo rel definido como manifest em todas as páginas HTML da PWA. Isso é semelhante à vinculação de 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 esteja configurado corretamente, use o Inspector no Firefox e o DevTools em todos os navegadores baseados no Chromium.

Para navegadores Chromium

No DevTools

  1. No painel à esquerda, em Application, selecione Manifest.
  2. Verifique os campos do manifesto conforme analisados pelo navegador.

Para o Firefox

  1. Abra o inspetor.
  2. Acesse a guia "Aplicação".
  3. Selecione a opção "Manifesto" no painel à esquerda.
  4. Verifique os campos do manifesto conforme analisados pelo navegador.

Como projetar sua experiência de PWA

Agora que a PWA está conectada ao manifesto, é hora de preencher o restante dos campos para definir a experiência dos usuários.

Campos básicos

O primeiro conjunto de campos representa as informações principais sobre sua PWA. Eles são usados para criar o ícone e a janela da PWA instalada e determinar como ela é iniciada. São eles:

name
Nome completo da sua PWA. Ele vai aparecer com o ícone na tela inicial, no iniciador, 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 completo do campo name. Mantenha-o com menos de 12 caracteres para minimizar a possibilidade de truncamento.
icons
Matriz de objetos de ícone com campos src, type, sizes e purpose opcionais, que descrevem quais imagens devem representar a PWA.
start_url
O URL que o PWA precisa carregar quando o usuário o inicia pelo ícone instalado. Um caminho absoluto é recomendado. Portanto, se a página inicial da PWA for a raiz do site, defina esse valor como "/" para abrir a página quando o app for iniciado. Se você não fornecer um URL inicial, o navegador poderá usar o URL de instalação da PWA como ponto de partida. Ele pode ser um link direto, como os detalhes de um produto em vez da tela inicial.
display
Um dos valores fullscreen, standalone, minimal-ui ou browser, que descreve como o SO deve desenhar a janela do PWA. Leia mais sobre os diferentes modos de exibição no capítulo de 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 ser hospedados na mesma origem. Se não for definido, o start_url será usado como um valor substituto. Ao mudar o start_url no futuro (por exemplo, ao mudar um valor da string de consulta), você pode remover a capacidade do navegador de detectar que um PWA já está instalado.

Ícones

O ícone da PWA é a identidade visual dela em todos os dispositivos dos usuários quando instalada. 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 vai escolher um ou mais ícones com base nas 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, ele deve ser de 512 x 512 pixels. No entanto, recomendamos fornecer mais tamanhos, incluindo imagens de 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 se os ícones não estiverem nos tamanhos recomendados, em algumas plataformas, não será possível atender aos critérios de instalação. Em outras plataformas, o ícone será gerado automaticamente, por exemplo, a partir de uma captura de tela da PWA ou usando um ícone genérico.

Ícones mascaráveis

Alguns sistemas operacionais, como o Android, adaptam í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 ou quadrados com cantos arredondados. Para oferecer suporte a esses tipos de ícones adaptáveis, forneça um ícone mascarado usando o campo purpose.

Para isso, forneça um arquivo de imagem quadrado com o ícone principal contido em uma "zona segura", um círculo centralizado no ícone com um raio de 40% da largura dele. Confira a imagem abaixo. Os dispositivos compatíveis com ícones mascarados vão mascarar seu ícone conforme necessário.

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

Confira um exemplo de ícone mascarado 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 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 preenchimento.

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

Os ícones mascarados precisam ter pelo menos 512 x 512. Depois de criar uma, você pode adicioná-la à 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 mascarado não estiver sendo exibido corretamente, adicione mais padding para melhorar. Maskable.app é uma ferramenta on-line sem custo financeiro para testar e criar uma versão mascarada do ícone.

Se o ícone tiver finalidades gerais e mascaradas, defina o campo purpose como "any maskable". Consulte a documentação do manifesto de app da Web da MDN para mais detalhes.

O próximo conjunto de campos a serem incluídos são aqueles que vão melhorar a experiência do usuário, mesmo que não sejam necessários para a instalabilidade.

theme_color
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 a ser exibida no plano de fundo do aplicativo antes que a folha de estilos seja carregada. 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 da PWA, permitindo que você defina o que é e o que 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 da PWA. No entanto, isso não muda 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.

A mesma PWA instalada no computador com uma cor de tema diferente.

Ao definir cores no manifesto, como em theme_color e background_color, use cores nomeadas do 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 sobre design de apps para mais informações.

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 inicial com as informações do manifesto, conforme mostrado no diagrama a seguir.

Uma PWA na tela inicial do Android usando 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 abertura. Em vez disso, eles usam uma imagem vinculada de um elemento <link> reservado de forma semelhante à forma como lidam com ícones. Consulte o capítulo de melhorias para mais detalhes.

Campos estendidos

O próximo conjunto de campos oferece mais informações sobre sua 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 suporte a 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 definir isso para solicitar uma orientação somente em modo paisagem. Vários valores são aceitos, mas, se incluídos, geralmente são portrait ou landscape explicitamente.

Campos promocionais

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

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

Esses campos promocionais já estão em uso. No Android, por exemplo, se o PWA puder ser instalado 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 rica, semelhante à de uma app store.

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

Confira como esses campos promocionais funcionam:

Campos de recursos

Por fim, há vários campos relacionados a diferentes recursos que o PWA pode usar em navegadores compatíveis, como os campos shortcuts, share_target e display_override, conforme abordado no capítulo sobre recursos. Há também campos, como related_apps e prefer_related_apps (consulte o capítulo sobre detecção para mais informações), para conectar o PWA a apps instalados, geralmente de uma app store.

Muitos novos campos podem aparecer no futuro, à medida que os navegadores adicionam mais recursos aos apps da Web progressivos.

Recursos