Como testar um PWA no iPhone e no Android: modo standalone, ícone, splash e offline

Um PWA tem duas vidas. Na primeira, é um site aberto no navegador. Na segunda, depois de Adicionar à Tela de Início, abre como app: sem a barra do navegador, com ícone próprio, splash de abertura e, se o service worker deixar, funcionando sem internet. Muitos bugs só aparecem na segunda vida, e é ela que quase ninguém testa antes de publicar.

O que muda quando o PWA é instalado

• Some a barra do navegador. A página passa a ocupar a tela inteira e responde a display-mode: standalone.
• A status bar muda de cor. No Android ela segue o theme_color do manifesto. No iPhone, o apple-mobile-web-app-status-bar-style.
• As safe areas passam a valer. Sem a barra do navegador, o topo e o rodapé da página encostam na ilha e no indicador de início.
• Aparece a splash. No Android, a tela de abertura usa o background_color, o nome e o ícone do manifesto.
• O ícone vira a porta de entrada. No Android, o ícone maskable é recortado no formato do sistema. Sem ele, o ícone vai para dentro de um círculo branco.

1. O manifesto

O manifesto é um arquivo JSON ligado no <head> com <link rel="manifest" href="/manifest.webmanifest">. O mínimo para instalar bem:

{
  "name": "Lume, contas e cartões",
  "short_name": "Lume",
  "start_url": "/",
  "display": "standalone",
  "background_color": "#f1f4f5",
  "theme_color": "#005a5f",
  "icons": [
    { "src": "/icons/icon-192.png", "sizes": "192x192", "type": "image/png" },
    { "src": "/icons/icon-512.png", "sizes": "512x512", "type": "image/png" },
    { "src": "/icons/icon-maskable-512.png", "sizes": "512x512", "type": "image/png", "purpose": "maskable" }
  ]
}

Para o iPhone, acrescente no <head> um <link rel="apple-touch-icon" href="/icons/apple-touch-icon.png"> de 180×180 e a meta apple-mobile-web-app-status-bar-style.

2. Confira no DevTools

No Chrome, abra o DevTools e vá em Application:

• Manifest mostra o que o navegador leu do manifesto e os erros que impedem a instalação.
• Service workers mostra se o service worker está ativo e controla a página.
• Storage permite limpar o cache e começar do zero.

O Lighthouse não tem mais a categoria PWA desde a versão 12, de 2024. A aba Application e o teste no aparelho viraram o caminho principal.

3. Teste o modo standalone

O seu CSS e o seu JavaScript podem se comportar diferente no app instalado:

@media (display-mode: standalone) {
  .barra-de-instalar { display: none; }
}

const instalado = matchMedia('(display-mode: standalone)').matches || navigator.standalone === true;

No Chrome do computador, dá para instalar o PWA pelo ícone na barra de endereço e ver a janela standalone. Só que ela tem o tamanho de uma janela de computador, não de um celular, e não tem safe areas.

4. Teste as safe areas

Se o PWA usa viewport-fit=cover, o conteúdo vai até as bordas e precisa reservar o espaço da ilha e do indicador de início:

.cabecalho { padding-top: env(safe-area-inset-top); }
.rodape { padding-bottom: env(safe-area-inset-bottom); }

Esses valores só existem no aparelho, ou numa ferramenta que reproduza as medidas de cada modelo. No modo celular do navegador eles ficam zerados.

5. Teste o offline

Com o PWA aberto, corte a rede e recarregue. No DevTools, aba Network, escolha Offline. O que o service worker guardou deve abrir. O resto deve mostrar uma tela de erro sua, não a do navegador.

6. Teste no celular

• No localhost o service worker funciona sem HTTPS, porque o navegador trata o localhost como seguro. Isso vale só no próprio computador.
• Pelo IP da rede, como http://192.168.0.12:5173, o service worker não registra sem HTTPS. Use um túnel com HTTPS, como Cloudflare Tunnel ou ngrok, ou um certificado local com mkcert.
• No iPhone, instale pelo Safari: Compartilhar e depois Adicionar à Tela de Início. Desde o iOS 16.4, outros navegadores do iPhone também oferecem a opção.
• No Android, o Chrome mostra o convite de instalação ou a opção Instalar app no menu.

Checklist antes de publicar

• O manifesto abre sem erros na aba Application.
• Ícones de 192 e 512 px, um maskable e o apple-touch-icon de 180 px.
• display: standalone, background_color e theme_color definidos.
• O layout funciona com display-mode: standalone, sem a barra do navegador.
• Topo e rodapé respeitam env(safe-area-inset-*).
• O app abre offline, ou mostra uma tela de erro própria.
• Testado instalado num iPhone e num Android.

Testar sem instalar a cada mudança

Instalar o PWA no celular a cada ajuste é lento. O Breakpane mostra o seu projeto no modo App, como ele fica instalado, dentro de iPhones e Androids com as safe areas reais, enquanto você programa. O diagnóstico aponta o que falta no manifesto, e o modo avião testa o offline. Para a checagem final, continue instalando num aparelho de verdade.