Adicionar um manifesto de app da Web

François Beaufort

Pete LePage

Thomas Steiner

Alexey Rodionov

Compatibilidade com navegadores

• 39
• 79,00
• x
• 17

Origem

Um manifesto de app da Web é um arquivo JSON que informa ao navegador como seu O Progressive Web App (PWA) se comporta quando é instalado no computador ou dispositivo móvel. No mínimo, um arquivo de manifesto típico inclui:

• O nome do app
• Os ícones que o app deve usar
• O URL que deve ser aberto quando o app for iniciado

Criar o arquivo de manifesto

O arquivo de manifesto pode ter qualquer nome, mas é comumente chamado de manifest.json e veiculados pela raiz, ou seja, o diretório de nível superior do seu site. A especificação sugere que a extensão deve ser .webmanifest, mas você pode querer usar JSON arquivos, deixando seus manifestos mais claros para a leitura.

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 que você fornecer, name será usado quando o app for instalado e short_name será na tela inicial, na tela de início ou em outros lugares onde há espaço limitada.

Observação: os sistemas operacionais geralmente esperam ter um título para cada janela do app. Isso título é exibido em várias plataformas de alternância de janelas, como alt+tab, o modo de visão geral e a lista de janelas da estante. Para PWAs executados no modo independente, O Chromium adiciona a short_name (ou, se isso não estiver disponível, a name) ao início do <title> do documento HTML para evitar ataques de disfarce em que Apps independentes podem tentar ser confundidos, por exemplo, com caixas de diálogo. Para ajudar a proteger seu app, não repita o nome dele na <title> para o modo independente.

icons

Quando um usuário instala seu PWA, você pode definir um conjunto de ícones para o navegador. para 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 Inclua o src, uma propriedade sizes e o type da imagem. Para usar ícones mascaráveis, às vezes chamados de adaptativos no Android, adicione "purpose": "any maskable" à propriedade icon.

Para o Chromium, é necessário fornecer pelo menos um ícone de 192 x 192 pixels e um Ícone de 512 x 512 pixels. Se apenas esses dois tamanhos de ícone forem fornecidos, o Chrome dimensiona automaticamente os ícones para que se ajustem ao dispositivo. Se você preferir escalonar próprios ícones e ajustá-los para a perfeição de pixel, fornecer ícones em incrementos de 48 dp.

Observação: os navegadores baseados no Chromium também são compatíveis com ícones SVG que podem ser dimensionados arbitrariamente sem parecer pixelado e são compatíveis com recursos avançados, como capacidade de resposta a prefers-color-scheme. No entanto, esses ícones permanecem no estado em que estavam no momento da instalação, em vez de atualizando ao vivo. Para usar ícones SVG com segurança, sempre especifique um ícone rasterizado como substituto para navegadores que não oferecem suporte a ícones SVG.

id

A propriedade id permite definir explicitamente o identificador usado para sua para o aplicativo. Adicionar a propriedade id ao manifesto remove a dependência start_url ou o local do manifesto e possibilita atualizar eles no futuro. Para mais informações, consulte Identificação exclusiva de PWAs com a propriedade do ID do manifesto do app da Web.

start_url

O start_url é uma propriedade obrigatória. Ela informa ao navegador onde seu aplicativo deve iniciar ao iniciar e impede que o aplicativo seja iniciado qualquer página em que o usuário estava quando adicionou seu aplicativo à tela inicial.

O start_url precisa direcionar o usuário diretamente para o app, não para um produto página de destino. Pense no que o usuário vai querer fazer imediatamente depois de abra seu app e coloque-as 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 é exibida quando o app é iniciado. Para Por exemplo, você pode ocultar a barra de endereço e os elementos de interface do usuário do navegador. Jogos e até mesmo em tela cheia. A propriedade display usa uma das os seguintes valores:

Propriedade	Comportamento
fullscreen	Abre o aplicativo da web sem nenhuma interface do navegador e ocupa todo o área de exibição disponível.
standalone	Abre o app da Web para parecer um app independente. O app é executado em sua própria janela, separada do navegador e esconde os padrões elementos de IU do navegador, como a barra de endereço. A interface autônoma.
minimal-ui	Esse modo é semelhante ao standalone, mas fornece a usuário com um conjunto mínimo de elementos de IU para controlar a navegação, como os botões "Voltar" e "Atualizar". A interface mínima.
browser	Uma experiência de navegador padrão.

display_override

Para escolher como seu app da Web vai ser mostrado, defina um modo display no manifesto como explicado anteriormente. Os navegadores não precisam oferecer suporte a todas as campanhas mas são necessários para permitir o cadeia de substitutos definida pela especificação ("fullscreen" → "standalone" → "minimal-ui" → "browser"). Caso contrário, oferecem suporte a um determinado modo, eles passam para o próximo modo de exibição na cadeia. Em casos raros, essas substituições podem causar problemas. Por exemplo, um desenvolvedor não pode solicitar "minimal-ui" sem ser forçado de volta à tela "browser" o modo quando "minimal-ui" não for compatível. O comportamento atual também o torna é impossível introduzir novos modos de exibição de maneira compatível com versões anteriores, porque não têm um lugar na cadeia substituta.

É possível definir sua própria sequência de substituição usando a propriedade display_override. que o navegador considera antes da propriedade display. Seu valor é um sequência de strings que são consideradas na ordem listada, e a primeira é aplicado. Se nenhum for compatível, o navegador voltará para avaliar o campo display. Se não houver um campo display, o navegador ignora display_override.

Confira abaixo um exemplo de como usar display_override. Os detalhes de "window-control-overlay" estão fora do escopo para esta página.

{
  "display_override": ["window-control-overlay", "minimal-ui"],
  "display": "standalone",
}

Ao carregar este app, o navegador tenta usar "window-control-overlay" primeiro. Se ele não estiver disponível, ele voltará para "minimal-ui" e, em seguida, para "standalone" da propriedade display. Se nenhuma delas estiver disponível, o navegador retorna à cadeia de fallback padrão.

scope

A scope do app é o conjunto de URLs que o navegador considera parte do seu app. scope controla a estrutura do URL que inclui todas as entradas e saídas aponta para o aplicativo, e o navegador o utiliza para determinar quando o usuário saiu o app.

Atenção: se o usuário clicar em um link no app que navegue para fora do scope, o link será aberto e renderizado na janela do PWA atual. Se você quiser o link a ser aberto em uma guia do navegador, adicione target="_blank" à tag <a>. Ativado Android, links com target="_blank" são abertos em uma guia personalizada do Chrome.

Algumas outras observações sobre scope:

• Se você não incluir um scope no manifesto, o padrão implícito scope é 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 nível superior caminho (/) que permitiria 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 atributo scope.
• Um start_url que começa com / sempre será a raiz da origem.

theme_color

O theme_color define a cor da barra de ferramentas e pode ser refletido em a visualização do app nos alternadores de tarefas. O theme_color precisa corresponder Cor do tema meta especificada no cabeçalho do seu documento.

Exemplo de uma janela PWA com theme_color personalizado.

theme_color em consultas de mídia

Compatibilidade com navegadores

• 93
• 93
• 106
• 15

Origem

Você pode ajustar theme_color em uma consulta de mídia usando o atributo media do Elemento de cor do tema meta. Por exemplo, você pode definir uma cor para o modo claro e outra para o modo escuro. No entanto, não é possível definir preferências no manifesto. Para mais informações, consulte o problema do w3c/manifest#975 no GitHub (link em inglês).

<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 atalhos de app. objetos que fornecem acesso rápido às principais tarefas dentro do seu aplicativo. 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 do que isso, o navegador a trunca com um 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, um sizes e o type da imagem. A propriedade form_factor é opcional. Você pode defini-la como "wide" para capturas de tela aplicáveis a telas amplas. ou "narrow" apenas 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 mais de 2,3 vezes o comprimento do mínimo dimensão.
• Todas as capturas de tela que correspondam ao formato adequado precisam ter o mesmo proporção.
  • No Chrome 109, apenas capturas de tela com o form_factor definido como "wide" são exibidos em computadores.
• A partir do Chrome 109, as capturas de tela com o form_factor definido como "wide" são ignoradas no Android. As capturas de tela sem form_factor ainda são exibidas para a compatibilidade com versões anteriores.

O Chrome no computador exibe pelo menos uma e no máximo oito capturas de tela que atendem esses critérios. O restante é ignorado.

O Chrome no Android exibe pelo menos uma e no máximo cinco capturas de tela que atendem esses critérios. O restante é ignorado.

Interface de instalação mais avançada em computadores e dispositivos móveis.

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 App Web Progressivo. Por exemplo:

<link rel="manifest" href="/manifest.json">

A solicitação do manifesto é feita sem credenciais, mesmo que estejam no mesmo domínio. Se o manifesto exigir credenciais, inclua crossorigin="use-credentials" na tag de manifesto.

Testar o manifesto

Para verificar se o manifesto está configurado corretamente, use o painel Manifest na Painel Application do Chrome DevTools.

Teste o manifesto no DevTools.

Esse painel oferece uma versão legível por humanos de muitos dos e permite verificar se todas as imagens estão sendo carregadas corretamente.

Telas de apresentação em dispositivos móveis

Quando seu app é iniciado pela primeira vez em um dispositivo móvel, o navegador pode demorar um pouco para ser aberto e do conteúdo inicial para iniciar a renderização. Em vez de mostrar uma tela branca que pode fazer o usuário pensar que o aplicativo não está funcionando, o navegador mostra uma tela de apresentação até a first paint.

O Chrome cria automaticamente a tela de apresentação usando o name, background_color e icons especificados no manifesto. Para criar uma camada transição da tela de apresentação para o app, faça de você background_color o mesma cor que a página de carregamento.

O Chrome escolhe o ícone que melhor corresponde à resolução do dispositivo para telas de apresentação. Fornecer ícones de 192 e 512 px é suficiente para a maioria dos casos, mas você pode fornecer ícones adicionais para uma melhor correspondência.

Leitura adicional

Para saber mais sobre outras propriedades que podem ser adicionadas ao manifesto do app da Web, consulte a documentação do manifesto do app da Web MDN.