PWA Storefront Pack

Guia completo de instalação, configuração e utilização do PWA Storefront Pack: o plugin que transforma a sua loja WooCommerce numa Progressive Web App instalável, com modo offline e notificações push VAPID nativas (sem Firebase, sem OneSignal e sem subscrição mensal).

Visão geral e princípio de funcionamento

O PWA Storefront Pack acrescenta ao seu WooCommerce três blocos independentes mas complementares:

• Web App Manifest: os seus clientes podem instalar a loja no ecrã principal como uma verdadeira aplicação (ícone, ecrã de arranque, modo standalone sem barra de endereço).
• Service Worker: cache inteligente das páginas e dos recursos, página offline personalizável, exclusões automáticas das zonas sensíveis (carrinho, checkout, a minha conta).
• Notificações push VAPID: implementação completa do protocolo Web Push em PHP puro: ECDSA P-256, JWT ES256 e cifragem aes128gcm. O seu servidor dialoga diretamente com os serviços push dos navegadores.

Requisitos

• WordPress 6.2 ou superior
• WooCommerce 7.0 ou superior
• PHP 7.4 ou superior com a extensão openssl (ativa por predefinição em todos os alojamentos)
• HTTPS obrigatório: os navegadores recusam registar um Service Worker ou gerir notificações push em HTTP (exceto em localhost, para desenvolvimento)

Instalação

1. Descarregue o arquivo pwa-storefront-pack.zip a partir da sua conta DataFirefly.
2. No WordPress, vá a Plugins → Adicionar → Carregar plugin.
3. Selecione o ZIP e clique em Instalar agora e depois em Ativar.
4. Na ativação, o plugin cria três tabelas SQL (wp_pwasp_subscriptions, wp_pwasp_push_log, wp_pwasp_stock_waitlist) e gera automaticamente o seu par de chaves VAPID.
5. Vá a WooCommerce → PWA Storefront para configurar.

Configuração geral

O separador General centraliza a identidade da sua aplicação:

• Enable PWA: interruptor principal. Desative para retirar temporariamente o manifesto e o Service Worker sem desinstalar o plugin.
• App name: nome completo apresentado na instalação e no ecrã de arranque (por exemplo «A Minha Loja Oficial»).
• Short name: texto curto por baixo do ícone do ecrã principal, limitado a 12 carateres por convenção Android.
• Theme color: cor da barra de endereço e do seletor de tarefas (recomendado: a cor principal da sua marca).
• Background color: fundo do ecrã de arranque durante o carregamento da app (muitas vezes branco ou muito claro).

URL dos endpoints

O plugin serve dois endpoints críticos:

• https://o-seu-site.com/pwasp-manifest.json: o Web App Manifest
• https://o-seu-site.com/pwasp-service-worker.js: o Service Worker

Manifesto

O separador Manifest controla o comportamento da app instalada:

• Display mode: standalone por predefinição (recomendado, experiência do tipo app). Outras opções: fullscreen, minimal-ui, browser.
• Orientation: any, portrait ou landscape. Em telemóvel, portrait costuma ser o mais adequado às lojas.
• Start URL: caminho onde a app abre no arranque. Por predefinição /. Pode apontar para /shop para abrir diretamente o catálogo.
• Scope: perímetro de URL controlado pela app. Geralmente /. Só o restrinja se usar a PWA apenas numa subpasta.
• Categories: indicações para as app stores web (Chrome, Edge). Exemplo: shopping,business.
• Shortcuts: ative para gerar atalhos de Loja / Carrinho / A minha conta acessíveis por pressão longa no ícone do ecrã principal.

Ícones da aplicação

O separador Icons permite associar os seus ícones a partir da biblioteca de multimédia do WordPress. São suportados cinco formatos:

• Ícone 192×192 (any purpose): obrigatório. Usado no Android e nos resultados do motor de pesquisa.
• Ícone 512×512 (any purpose): obrigatório. Ícone do ecrã de arranque.
• Maskable 192×192: opcional. Com margem de segurança interna de 10% para os ícones adaptativos do Android (formas redondas, quadradas, em gota).
• Maskable 512×512: opcional. Mesmo princípio para o ecrã de arranque.
• Apple Touch Icon 180×180: para iOS. Sem cantos arredondados (o iOS acrescenta-os automaticamente).

Enquanto não houver ícone configurado, o plugin usa os ícones predefinidos fornecidos (marca DataFirefly). Substitua-os antes de passar a produção.

Modo offline e estratégia de cache

O separador Offline & Cache configura o comportamento do Service Worker:

Estratégias

• Network first (recomendado): o navegador tenta a rede e depois recorre à cache se estiver offline. Frescura máxima dos preços e do stock.
• Cache first: a cache responde de imediato e a rede atualiza em segundo plano. Mais rápido, mas pode apresentar preços ligeiramente desatualizados.

As estratégias aplicam-se apenas às páginas HTML. Os outros tipos de recurso têm estratégias fixas ótimas:

• CSS / JS / tipos de letra → cache-first (só mudam nas atualizações de versão)
• Imagens de produto → stale-while-revalidate (apresentação imediata a partir da cache, atualização em segundo plano)

Âmbito da cache

Três caixas de seleção permitem ativar ou desativar a cache por tipo:

• Cache HTML pages: páginas de produto, de categoria, página inicial, artigos
• Cache CSS / JS / fonts: o esqueleto do seu tema
• Cache images: visuais de produto, imagens dos artigos do blogue

Página offline

Duas opções:

• Usar o ecrã predefinido: ecrã minimalista integrado no plugin (ícone, mensagem, botão Tentar de novo), com as cores da sua marca.
• Usar uma página personalizada: selecione uma página WordPress existente. Fica pré-colocada em cache na instalação do Service Worker e é servida em caso de falha de rede.

Banner de instalação

O separador Install Banner controla a promoção da instalação:

• Delay (page views): número de páginas vistas antes da apresentação. 3 por predefinição: o utilizador manifestou um interesse mínimo sem ser importunado logo na primeira visita.
• Banner title / text / CTA / Dismiss: textos totalmente personalizáveis, traduzíveis através do .pot.

Comportamento:

• No Chrome, Edge, Opera e Samsung Internet: o banner aparece quando o navegador assinala que o site é instalável (beforeinstallprompt). Um clique no CTA abre a caixa nativa de instalação.
• No Safari em iOS: o banner apresenta automaticamente as instruções «Toque em Partilhar e depois em Adicionar ao ecrã principal» (a Apple não oferece uma API de instalação programática).
• Recusa memorizada durante 7 dias: se o utilizador fechar o banner, este não reaparece durante uma semana.
• Deteção automática: se a app já estiver instalada (modo standalone detetado), o banner deixa de aparecer.

Notificações push: as chaves VAPID

As notificações push usam o protocolo VAPID (Voluntary Application Server Identification), padrão do W3C. Na ativação do plugin, é gerado automaticamente um par de chaves ECDSA P-256:

• Chave pública: partilhada com os navegadores dos subscritores (através de JavaScript). 65 bytes, codificada em base64url.
• Chave privada: nunca transmitida, serve para assinar cada envio. 32 bytes.

O separador Push Notifications mostra a sua chave pública em claro e o número de subscrições ativas. Pode copiá-la para eventuais testes externos.

Regeração das chaves

O botão Regenerate keys gera um novo par. Esta operação é destrutiva:

VAPID subject

Campo VAPID subject: endereço de contacto no formato mailto:voce@exemplo.com ou https://exemplo.com/contacto. Alguns serviços push (nomeadamente o da Mozilla) usam-no para o contactar em caso de abuso detetado no seu servidor. Vem pré-preenchido com o e-mail de administração do WordPress.

Pedido de adesão e RGPD

A secção Opt-in prompt configura o pré-convite apresentado antes da caixa de diálogo nativa de permissão:

• Show opt-in prompt: ativa o pré-convite personalizado. Recomendado: a caixa nativa isolada tem uma taxa de recusa elevada e bloqueia qualquer novo pedido durante 30 dias.
• GDPR consent required: nunca apresenta a caixa nativa sem um clique explícito do utilizador no seu CTA. Exigido na Europa para haver conformidade com o RGPD.
• Delay (seconds): espera antes da apresentação. 10 segundos por predefinição: deixar o utilizador explorar antes de pedir a permissão.
• Prompt title / text / CTA / Dismiss: textos totalmente personalizáveis.

Acionadores automáticos

O plugin traz três automatizações ligadas diretamente aos hooks do WooCommerce. Cada uma pode ser ativada de forma independente.

Estado da encomenda

Hook: woocommerce_order_status_changed.
O cliente identificado (não os convidados) recebe uma notificação a cada transição de estado da sua encomenda. Título: «Encomenda #1042 atualizada». Corpo: «Estado: Expedida». Clique → página de seguimento da encomenda.

A notificação usa uma tag única por encomenda (order-1042): as atualizações sucessivas substituem a anterior em vez de se acumularem.

Nova encomenda (administração)

Hook: woocommerce_new_order.
Todos os utilizadores com o perfil administrator ou shop_manager e subscritos ao push recebem uma notificação a cada nova encomenda. Título: «Nova encomenda recebida». Corpo: «Encomenda #1042, 189,00 €». Clique → ecrã de edição da encomenda.

O URL de administração tem consciência do HPOS: se o seu WooCommerce usar o High-Performance Order Storage, a ligação aponta para o novo esquema (admin.php?page=wc-orders). Caso contrário, para o antigo (post.php?post=X).

Regresso ao stock

Hooks: woocommerce_product_set_stock e woocommerce_variation_set_stock.
Quando um produto passa de «esgotado» a «em stock», o plugin envia uma notificação a todos os visitantes que se tinham inscrito na lista de espera. Título: «De volta ao stock!». Corpo: «Ténis de couro premium edição limitada está de novo disponível». Imagem do produto em pré-visualização, se existir.

Cada entrada é marcada com notified_at após o envio bem-sucedido, para evitar duplicados se o stock oscilar.

Compositor de broadcast

Menu: WooCommerce → PWA Broadcast. Interface para enviar uma notificação manual a todos os subscritores ativos (campanhas de marketing, anúncios, etc.).

Campos:

• Title: título da notificação (recomenda-se um máximo de 100 carateres)
• Message: corpo da notificação (recomenda-se um máximo de 200 carateres)
• Open URL: página onde o utilizador chega ao clicar (por predefinição, a página inicial)
• Image URL: imagem grande apresentada na notificação (apenas no Android, o iOS não a apresenta)

Uma pré-visualização em tempo real mostra a apresentação aproximada da notificação à direita do ecrã.

Dois botões:

• Send broadcast: envio a todos os subscritores ativos (exige confirmação)
• Send test to me: envio apenas às suas próprias subscrições. Útil para validar a apresentação antes de um broadcast em massa.

Lista de espera de regresso ao stock (API JavaScript)

Para permitir que os visitantes se inscrevam na lista de espera de um produto esgotado, chame a partir do seu tema:

window.PWASP.addToWaitlist(productId)
  .then(result => {
    if (result.success) {
      alert('Será notificado assim que o produto voltar ao stock!');
    }
  });

Comportamento:

1. Se o utilizador ainda não estiver subscrito ao push, abre-se a caixa nativa de permissão.
2. Assim que a subscrição fica registada no servidor, a entrada é acrescentada à lista de espera do produto.
3. Quando o regresso ao stock é detetado, é enviada automaticamente uma notificação push.

Pode chamar esta API a partir de qualquer botão personalizado ou do hook woocommerce_single_product_summary através de um mu-plugin.

Outras API JS expostas

// Subscrever manualmente (por exemplo a partir de um botão personalizado)
window.PWASP.subscribePush();

// Cancelar a subscrição (botão «Cancelar subscrição»)
window.PWASP.unsubscribePush();

API REST

O plugin expõe seis endpoints no namespace pwasp/v1:

• POST /wp-json/pwasp/v1/subscribe: regista uma subscrição. Corpo: objeto PushSubscription do navegador.
• POST /wp-json/pwasp/v1/unsubscribe: elimina uma subscrição. Corpo: { endpoint: "..." }.
• POST /wp-json/pwasp/v1/test: envio de teste ao utilizador atual (exige autenticação, permissão manage_woocommerce).
• POST /wp-json/pwasp/v1/broadcast: difusão a todos os subscritores (exige autenticação).
• POST /wp-json/pwasp/v1/regenerate-vapid: regera as chaves VAPID (exige autenticação).
• POST /wp-json/pwasp/v1/waitlist: acrescenta a uma lista de espera. Corpo: { subscription_id, product_id }.

Autenticação: nonce do WordPress X-WP-Nonce nos endpoints públicos, permissão manage_woocommerce nos endpoints de administração.

Compatibilidade e casos particulares

HPOS (High-Performance Order Storage)

O plugin declara formalmente a compatibilidade HPOS ao WooCommerce através do FeaturesUtil::declare_compatibility. Verá a caixa assinalada em WooCommerce → Definições → Avançado → Funcionalidades.

Plugins de cache

Acrescente as seguintes exclusões no seu plugin de cache:

• /pwasp-manifest.json
• /pwasp-service-worker.js

Alguns plugins (WP Rocket, LiteSpeed) oferecem também uma opção para não colocar em cache os ficheiros JavaScript assinados como Service Worker. Ative-a se estiver disponível.

iOS e Safari

Suporte por versão:

• iOS 16.4 e superior: instalação através de «Adicionar ao ecrã principal» e notificações push (apenas nas PWA instaladas)
• iOS 15 e 16.3: instalação possível, notificações push indisponíveis
• iOS 14 e inferior: instalação possível, sem notificações

Em iOS, o push só funciona se o utilizador tiver primeiro instalado a PWA no ecrã principal. É uma imposição da Apple, não do plugin.

Multilingue: WPML e Polylang

O plugin é compatível com o WPML (incluindo o WooCommerce Multilingual) e com o Polylang / Polylang Pro, em modo subdiretórios (/en/, /it/), subdomínios ou parâmetro de idioma:

• Service Worker: registado sempre a partir da raiz do site (/pwasp-service-worker.js) com um scope /, pelo que um único SW cobre todos os idiomas.
• Manifesto: servido em cada idioma (/en/pwasp-manifest.json) com nome, descrição e start_url desse idioma. O campo id é idêntico em todo o lado: a app instalada a partir de /it/ e a partir de /pt/ é a mesma app.
• Textos de administração (banner de instalação, pré-convite de push, mensagem offline, nome e nome curto da app): registados automaticamente em WPML → String Translation (domínio «PWA Storefront Pack») e em Idiomas → Traduções de cadeias no Polylang. Introduza-os no idioma predefinido e traduza-os aí.
• Notificações push: enviadas no idioma de cada subscritor (locale memorizada na inscrição). O alerta de regresso ao stock usa o nome e o URL do produto traduzido.
• Ecrã offline: pré-colocado em cache para cada idioma e servido no idioma da página pedida.
• Carrinho / Encomenda / A minha conta: excluídos da cache seja qual for a tradução do slug (resolvidos por idioma no servidor).

Subpastas e multisite

O plugin funciona com o WordPress instalado na raiz (example.com) ou numa subpasta (example.com/shop/). Os endpoints são resolvidos dinamicamente através do home_url(). Em multisite, ative o plugin site a site: cada site terá o seu próprio par de chaves VAPID e a sua própria base de subscritores.

Resolução de problemas

«O Service Worker não está registado»

1. Verifique que o seu site está mesmo em HTTPS (https:// e não http://).
2. Abra a consola do navegador (F12 → separador Application → Service Workers). Existe alguma mensagem de erro?
3. Teste o URL https://o-seu-site.com/pwasp-service-worker.js num separador. O ficheiro tem de devolver JavaScript, não uma página 404 nem a página inicial do WordPress.
4. Se der 404: vá a Definições → Permalinks e clique em Guardar alterações para atualizar as regras de reescrita.

«As notificações não chegam»

1. Verifique em WooCommerce → PWA Subscribers que a sua subscrição está listada e no estado active.
2. Use o botão Send test to me no compositor de broadcast. Recebe a notificação?
3. Se não: a caixa de permissão pode ter sido recusada. No Chrome: abra o cadeado na barra de endereço → Notificações → Permitir.
4. Em Windows/macOS: verifique que o Chrome ou o Firefox não estão em modo «Não incomodar».

«A regeração das chaves VAPID falhou»

Causa provável: a extensão PHP openssl não está disponível no seu alojamento, ou a geração de chaves ECDSA está bloqueada. Verifique num ficheiro phpinfo.php que a secção openssl está presente e que a curva prime256v1 é suportada. Contacte o seu alojamento se for necessário.

Desinstalação

Remoção através de Plugins → Plugins instalados → Eliminar:

• As três tabelas SQL são eliminadas
• As opções do plugin são eliminadas
• As tarefas cron agendadas são canceladas
• Os ícones carregados para a biblioteca de multimédia mantêm-se (podem ser úteis noutro lado)

Suporte

Para qualquer questão ou anomalia, abra um pedido a partir da sua conta DataFirefly. Resposta em 24 horas úteis.