# DfPwaPush: guia completo

> 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…

- Página: <https://www.datafirefly.com/pt/documentation/dfpwapush/>
- Idioma: pt
- Atualizado em: 2026-09-02
- Outros idiomas: [fr](https://www.datafirefly.com/documentation/dfpwapush/index.md), [en](https://www.datafirefly.com/en/documentation/dfpwapush/index.md), [es](https://www.datafirefly.com/es/documentation/dfpwapush/index.md), [de](https://www.datafirefly.com/de/documentation/dfpwapush/index.md), [it](https://www.datafirefly.com/it/documentation/dfpwapush/index.md), [pl](https://www.datafirefly.com/pl/documentation/dfpwapush/index.md), [nl](https://www.datafirefly.com/nl/documentation/dfpwapush/index.md)
- Índice: <https://www.datafirefly.com/pt/documentation/llms.txt>

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.