Manifesto do app da Web

O manifesto do app da Web é um arquivo criado por você que informa ao navegador como você 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, então você pode dar ao manifesto um nome 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"
}

No entanto, 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. Esse 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">

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 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 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 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 ser carregado quando o usuário o inicia pelo ícone de instalação. 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 do seu PWA é a 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 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 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, 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 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 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 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 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. 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 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 vai alterar 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 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.

Um PWA na tela de apresentação do 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 abertura. Em vez disso, eles usam uma imagem vinculada por um elemento <link> reservado de maneira semelhante ao processamento de ícones. Confira 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 exibir campos do manifesto com recursos direcional (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 o PWA pertence. Elas podem ser usadas como dicas para fichas de empresa, opcionalmente na 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 ação. 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 com suporte, como os campos shortcuts, share_target e display_override, conforme abordamos no capítulo Capabilities. Há também campos, como related_apps e prefer_related_apps (consulte o capítulo de detecção para mais informações), para conectar o PWA a 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