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. |
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".
|
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, oscope
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 atributoscope
. - 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.
theme_color
em consultas de mídia
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.
- A partir do Chrome 109, apenas capturas de tela com o
- No Chrome 109, as capturas de tela com
form_factor
definido como"wide"
são ignoradas no Android. As capturas de tela semform_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.
Adicionar o manifesto do app da Web às suas páginas
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.
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.