SW Shopware 6 Shopware Intermédio

DfPwaPush: guia completo

Transformar a sua loja Shopware numa PWA instalável e enviar notificações Web Push auto-alojadas (VAPID, sem Firebase nem dependências Composer) para Shopware 6.5, 6.6 e 6.7.

Atualizado Versão do módulo 1.0.2

O DfPwaPush combina duas funções numa única extensão Shopware: transforma o seu storefront numa Progressive Web App instalável (manifest, service worker, página offline, banner de instalação) e permite-lhe reconquistar os seus clientes com notificações Web Push inteiramente auto-alojadas. Nenhum serviço de terceiros (nem Firebase, nem OneSignal), nenhuma dependência Composer: a cifra Web Push (RFC 8291) e a assinatura VAPID (RFC 8292) estão implementadas nativamente com as extensões OpenSSL e cURL já exigidas pelo Shopware. Todos os dados de subscrição ficam no seu servidor. Este guia cobre a instalação, a configuração PWA e Push, a geração das chaves VAPID, a criação e o envio de campanhas, a execução em segundo plano, e a resolução de problemas.

Instalação

  1. Transfira o arquivo DfPwaPush-1.0.2.zip a partir da sua conta DataFirefly.
  2. Instale-o em Administração → Extensões → As minhas extensões → Carregar extensão, ou copie a pasta descomprimida DfPwaPush para custom/plugins/.
  3. Execute a instalação e a ativação: 
    bin/console plugin:refresh
bin/console plugin:install --activate DfPwaPush
bin/console cache:clear
  4. Na instalação, a extensão cria as suas duas tabelas (df_push_subscription e df_push_campaign) e regista a sua ScheduledTask de envio.

Compatível com Shopware 6.5.x, 6.6.x e 6.7.x numa única base de código. O módulo de administração é entregue pré-compilado e o JavaScript do storefront é injetado por Twig: não é necessário qualquer build, nem build-administration.sh nem build do storefront. Extensões PHP necessárias: openssl e curl, ambas já exigidas pelo Shopware. Sem dependências Composer adicionais.

Pré-requisito HTTPS

Os service workers e a API Web Push só existem numa origem segura. A sua loja tem de ser servida em HTTPS (apenas o localhost é exceção em desenvolvimento). Numa loja em HTTP, a extensão fica silenciosa no frontend e regista-o na consola do navegador.

Onde encontrar a extensão na administração

Depois da ativação, aparece uma entrada Campanhas push no menu Marketing da administração. É aí que cria, agenda e acompanha as suas campanhas. Toda a configuração PWA e Push faz-se na configuração da extensão, por canal de venda, em Extensões → As minhas extensões → DfPwaPush → ⋯ → Configurar.

Se a entrada de menu não aparecer depois de uma atualização, execute bin/console assets:install && bin/console cache:clear e recarregue a administração com uma atualização forçada (Ctrl+Shift+R).

Geração das chaves VAPID

O Web Push assenta num par de chaves VAPID (norma RFC 8292) que autentica o seu servidor junto dos serviços de push dos navegadores. Gere-as num único comando:

bin/console df:pwa-push:vapid:generate

As chaves são escritas diretamente na configuração da extensão. Use a opção --force para as regerar. Também pode colar chaves VAPID existentes nos campos de configuração.

Regerar as chaves VAPID invalida todas as subscrições existentes: os navegadores já subscritos deixam de poder receber notificações e terão de voltar a subscrever. Faça-o apenas com conhecimento de causa.

Configuração PWA

O cartão PWA da configuração (regulável por canal de venda) controla a instalabilidade da sua loja:

  • Ativar a PWA: serve o manifest e o service worker.
  • Nome e nome curto da aplicação: apresentados no ecrã principal depois da instalação.
  • Cor do tema / cor de fundo: por predefinição #0f172a para o tema.
  • Modo de apresentação: standalone, minimal-ui, fullscreen ou browser.
  • Ícones de 192 px e 512 px: uploads em PNG, indispensáveis à instalabilidade.
  • Banner de instalação: ativa o convite «Adicionar ao ecrã principal».

Sem os dois ícones de 192 px e 512 px preenchidos, o Chrome não considera o site instalável e o banner de instalação nunca aparecerá. É a causa número um de uma PWA que «não faz nada» no frontend.

Configuração Push

O cartão Push controla as notificações:

  • Ativar o Web Push: ativa o banner de opt-in e os endpoints de subscrição. Ativo por predefinição.
  • Chave pública / chave privada VAPID: geradas pelo comando acima.
  • Assunto VAPID: um endereço mailto: ou o URL do seu site.
  • Atraso do opt-in: número de segundos antes de o banner de autorização aparecer (8 por predefinição).

O service worker e os endpoints do storefront

Todos os recursos PWA são servidos dinamicamente por um controlador, o que os torna insensíveis à passagem do webpack para o Vite na 6.7:

  • GET /df-pwa/manifest.json: o manifest PWA, gerado por canal de venda.
  • GET /df-pwa/sw.js: o service worker (cabeçalho Service-Worker-Allowed: / para controlar toda a origem).
  • GET /df-pwa/icon/{192|512}: os ícones PWA.
  • GET /df-pwa/offline: a página de recurso offline, colocada em cache pelo service worker.
  • POST /df-pwa/subscribe e POST /df-pwa/unsubscribe: registo e remoção de uma subscrição (XHR).

O service worker coloca a página offline em cache na instalação, serve uma alternativa para as navegações falhadas, e apresenta as notificações recebidas através do evento push, com reencaminhamento ao clique para o URL da campanha.

Criar e enviar uma campanha

  1. Vá a Marketing → Campanhas push → Criar uma campanha.
  2. Preencha o título, a mensagem, e eventualmente um URL de destino e um ícone.
  3. Restrinja, se necessário, a campanha a um canal de venda (caso contrário todos os subscritores são visados).
  4. Ou define uma data de agendamento e guarda, ou clica em Enviar agora.

«Enviar agora» coloca a campanha em fila imediata (estado scheduled com uma data de envio no instante presente); a tarefa agendada trata dela nos minutos seguintes. Uma campanha passa pelos estados draft → scheduled → sending → sent (ou failed), e a ficha mostra os contadores de envios com sucesso e de falhas.

Envio em segundo plano: ScheduledTask e CLI

O envio das campanhas é assegurado pela ScheduledTask df_pwa_push.send_campaigns, executada a cada 300 segundos. Recolhe as campanhas agendadas que chegaram à data e envia-as por lotes. Também pode acionar o envio manualmente:

bin/console df:pwa-push:send

Como qualquer ScheduledTask do Shopware, o envio depende de um worker ativo. Confirme que há um consumidor Messenger a correr (bin/console messenger:consume) ou que o scheduler do Shopware é acionado regularmente, caso contrário as campanhas agendadas não serão enviadas.

Web Push nativo, sem dependências

O DfPwaPush implementa a pilha Web Push completa em PHP puro, sem bibliotecas externas:

  • VAPID / ES256 (RFC 8292): geração de chaves P-256 com OpenSSL e assinatura JWT ES256 para autenticar o servidor.
  • Cifra aes128gcm (RFC 8291): ECDH efémero, derivação HKDF e cifra AES-128-GCM da mensagem para cada subscritor.
  • Envio paralelo com curl_multi por lotes, com tratamento dos códigos de retorno dos serviços de push.

A implementação é validada byte a byte contra o vetor de teste oficial do RFC 8291, o que garante a interoperabilidade com o Chrome, o Firefox, o Edge e o Safari.

Limpeza automática das subscrições

Quando um serviço de push responde que uma subscrição deixou de existir (códigos HTTP 404 ou 410), a subscrição correspondente é automaticamente desativada. As subscrições que falham repetidamente (5 falhas consecutivas) também são desativadas. A sua base de subscritores mantém-se assim limpa sem intervenção.

Compatibilidade com iOS e Safari

Em iOS, o Web Push exige iOS 16.4 ou superior e que a PWA esteja instalada no ecrã principal: o Safari não entrega notificações push a um simples separador. A extensão trata este caso corretamente: o banner de opt-in só aparece quando a API Push está realmente disponível, pelo que não é feita qualquer promessa falsa aos seus visitantes em iOS.

FAQ e resolução de problemas

A instalação por ZIP falha com «package minishlink/web-push em falta». Este erro dizia respeito às versões anteriores. Desde a 1.0.1, o Web Push é nativo e a extensão deixou de ter qualquer dependência Composer: a versão atual instala-se em qualquer alojamento, incluindo partilhado.

Não aparece nada para criar campanhas no back-office. O módulo de administração é pré-compilado desde a 1.0.1. Depois de atualizar, execute bin/console assets:install && bin/console cache:clear e recarregue a administração forçando a cache (Ctrl+Shift+R). A entrada encontra-se em Marketing → Campanhas push.

O URL /df-pwa/manifest.json devolve um erro 500. Corrigido na 1.0.2: o método setTwig() do controlador pai foi removido no Shopware 6.7, o que fazia falhar todas as rotas /df-pwa/*. Atualize para a 1.0.2 ou posterior.

Não acontece nada no storefront. Abra a consola do navegador: a extensão regista cada decisão com o prefixo [DfPwaPush] (service worker registado ou não, chave VAPID em falta, permissão recusada, iOS sem PWA instalada, e outros). Verifique também que a loja está em HTTPS.

O banner de instalação da PWA não aparece. O Chrome só emite o evento beforeinstallprompt se o site for instalável, o que exige os ícones de 192 px e 512 px preenchidos na configuração e um service worker ativo. Sem ícones, não há banner.

O banner de notificações não aparece. Verifique que as chaves VAPID estão geradas, que o Web Push está ativo, e que o utilizador ainda não recusou as notificações. A consola mostrará a razão exata.

O que acontece na desinstalação? Com a opção de eliminação dos dados, as tabelas df_push_subscription e df_push_campaign são eliminadas. Sem essa opção, são conservadas para preservar os seus subscritores e o histórico de campanhas.

Esta página foi útil?

Ainda com dúvidas? Contacte o suporte