🔧 PWA Troubleshooting - Tools Artes do Sul

✅ Correções Implementadas

1. Arquivos Criados

  • ✅ manifest-tools.json - Manifest para o site principal
  • ✅ sw-tools.js - Service Worker para o site principal
  • ✅ diagnostico-pwa.html - Ferramenta de diagnóstico
  • ✅ Referências PWA adicionadas no index.html

2. Configurações no index.html

  • ✅ <link rel="manifest" href="/manifest-tools.json">
  • ✅ Meta tags: theme-color, description
  • ✅ Ícones: apple-touch-icon, favicon
  • ✅ Código de registro do Service Worker
  • ✅ Handler para beforeinstallprompt

🚨 Problemas Comuns e Soluções

Problema: PWA não ativa / Manifest não encontrado

Verificações:

  1. ✅ Arquivo manifest-tools.json existe na raiz do servidor?
  2. ✅ Arquivo está acessível? Teste: https://tools.artesdosul.com/manifest-tools.json
  3. ✅ Content-Type correto? Deve ser application/manifest+json

Solução Alternativa (se preferir usar manifest.json):

# No servidor, renomear:
mv manifest-tools.json manifest.json

# E atualizar index.html linha 11:
# De: <link rel="manifest" href="/manifest-tools.json">
# Para: <link rel="manifest" href="/manifest.json">

Problema: Service Worker não registra

Verificações:

  1. ✅ Arquivo sw-tools.js existe na raiz?
  2. ✅ Arquivo está acessível? Teste: https://tools.artesdosul.com/sw-tools.js
  3. ✅ Está usando HTTPS? (obrigatório em produção)
  4. ✅ Console do navegador mostra erros?

Como verificar no Chrome DevTools:

  1. Abrir DevTools (F12)
  2. Ir em Application > Service Workers
  3. Verificar se aparece registrado
  4. Verificar console para erros

Problema: Ícones não aparecem

Verificações:

  1. ✅ Pasta icons/ existe na raiz?
  2. ✅ Todos os arquivos PNG existem?
  3. ✅ Testar acesso: https://tools.artesdosul.com/icons/icon-192x192.png
  4. ✅ Permissões de arquivo no servidor estão corretas?

Ícones obrigatórios:

  • icon-192x192.png (mínimo)
  • icon-512x512.png (recomendado)

Problema: Botão de instalação não aparece

Possíveis causas:

  1. ❌ Manifest inválido (JSON com erros)
  2. ❌ Falta ícone 192x192 ou 512x512
  3. ❌ Não está em HTTPS
  4. ❌ Service Worker não registrado
  5. ✅ Já está instalado (verificar em modo standalone)

Como verificar:

// No console do navegador:
window.matchMedia('(display-mode: standalone)').matches
// Se retornar true, já está instalado

🔍 Ferramenta de Diagnóstico

Use diagnostico-pwa.html para verificar automaticamente:

  1. Acesse: https://tools.artesdosul.com/diagnostico-pwa.html
  2. A ferramenta verificará:
    • ✅ HTTPS ativo
    • ✅ Service Worker API disponível
    • ✅ Manifest carregando
    • ✅ Service Worker registrado
    • ✅ Ícones acessíveis
    • ✅ Pronto para instalar

📋 Checklist de Deploy

Arquivos que DEVEM estar no servidor:

/
├── index.html                    ✅
├── manifest-tools.json          ✅ (ou manifest.json)
├── sw-tools.js                  ✅
├── icons/
│   ├── icon-16x16.png          ✅
│   ├── icon-32x32.png          ✅
│   ├── icon-72x72.png          ✅
│   ├── icon-96x96.png          ✅
│   ├── icon-128x128.png        ✅
│   ├── icon-144x144.png        ✅
│   ├── icon-152x152.png        ✅
│   ├── icon-192x192.png        ✅ OBRIGATÓRIO
│   ├── icon-384x384.png        ✅
│   └── icon-512x512.png        ✅ OBRIGATÓRIO

Verificações Pós-Deploy:

  1. Manifest acessível: 
    curl -I https://tools.artesdosul.com/manifest-tools.json
# Deve retornar: HTTP/1.1 200 OK
# Content-Type: application/manifest+json
  2. Service Worker acessível: 
    curl -I https://tools.artesdosul.com/sw-tools.js
# Deve retornar: HTTP/1.1 200 OK
# Content-Type: application/javascript
  3. Ícones acessíveis: 
    curl -I https://tools.artesdosul.com/icons/icon-192x192.png
curl -I https://tools.artesdosul.com/icons/icon-512x512.png

🛠️ Comandos de Verificação no Navegador

Chrome DevTools:

  1. Application > Manifest:
    • Verificar se manifest está carregado
    • Verificar erros
    • Verificar ícones encontrados
  2. Application > Service Workers:
    • Verificar se está registrado
    • Verificar se está ativo (activated)
    • Verificar erros no console
  3. Console:
    • Procurar por [SW] para mensagens do Service Worker
    • Verificar erros 404

Lighthouse Audit:

  1. Abrir DevTools (F12)
  2. Ir em Lighthouse
  3. Selecionar Progressive Web App
  4. Clicar em Generate report
  5. Verificar score e problemas

🎯 Solução Rápida

Se o PWA ainda não estiver funcionando após o deploy:

  1. Limpar cache do navegador:
    • DevTools > Application > Clear Storage > Clear site data
  2. Desregistrar Service Workers antigos:
    • DevTools > Application > Service Workers > Unregister
  3. Recarregar a página:
    • Ctrl+Shift+R (hard refresh)
  4. Verificar console:
    • Procurar por erros relacionados a manifest ou service worker
  5. Usar ferramenta de diagnóstico:
    • Acessar diagnostico-pwa.html

📝 Notas Importantes

  1. HTTPS é obrigatório em produção
  2. Service Worker só funciona via HTTP/HTTPS
  3. Ícones 192x192 e 512x512 são obrigatórios
  4. Manifest deve ser JSON válido
  5. Scope deve ser / para funcionar em todo o site

🔗 Links Úteis