# DataFirefly Push: guia completo

> Apresentação e requisitos O DataFirefly Push transforma a sua loja WooCommerce numa plataforma de notificações Web Push nativa. Sem SDK e sem tracking de terceiros: toda a criptografia (VAPID e…

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

## Apresentação e requisitos

O DataFirefly Push transforma a sua loja WooCommerce numa plataforma de notificações Web Push nativa. Sem SDK e sem tracking de terceiros: toda a criptografia (VAPID e cifragem RFC 8291) corre no seu servidor em PHP puro através do OpenSSL. O plugin cobre uma adesão inteligente com vários estilos, dez acionadores automáticos, campanhas manuais com construtor visual e segmentação, um painel de análises completo, uma página A minha conta dedicada aos seus clientes e uma conformidade RGPD nativa.

- WordPress 6.2 e superior.
- WooCommerce 7.0 e superior, testado até à 9.6, compatível com HPOS e Cart/Checkout Blocks.
- PHP 8.1 e superior.
- Multilingue (FR/EN/ES/DE/IT), compatível com Polylang e WPML.
- Compatível com LiteSpeed Cache, WP Rocket e outros plugins de cache: o Service Worker é servido em PHP autónomo.

Nenhum serviço de terceiros para ligar, nenhuma biblioteca Composer para manter. As chaves VAPID são geradas automaticamente na ativação, e as subscrições e os eventos ficam guardados na sua base de dados.

## Instalação

1. Descarregue o arquivo `df-push.zip` a partir da sua conta de cliente.
2. Na administração do WordPress, vá a **Plugins > Adicionar > Carregar plugin** e envie o arquivo.
3. Clique em **Ativar**.
4. O menu **DF Push** aparece na barra lateral de administração com sete submenus: Dashboard, Campanhas, Subscritores, Acionadores, Adesão, Definições, Webhooks & API.

Na ativação, o plugin cria oito tabelas dedicadas com prefixo `dfpush_`, gera as suas chaves VAPID, agenda o cron diário `df_push_daily_lifecycle` e regista o endpoint de A minha conta. Não é necessária qualquer intervenção manual.

## Primeira configuração: chaves VAPID e adesão

Depois de ativado, o plugin fica imediatamente funcional com as definições predefinidas: o sino flutuante aparece em baixo à direita após cinco segundos, o pré-pedido está ativo e os acionadores automáticos estão prontos. Verifique apenas duas coisas em **DF Push > Definições** antes de comunicar o serviço:

- **Chave pública VAPID**: o bloco mostra a sua chave pública gerada automaticamente (a application server key usada pelo navegador). Pode regerá-la, mas isso invalida todas as subscrições existentes.
- **Manifesto PWA** e **ícone predefinido**: acrescente o seu ícone (192×192 no mínimo) se o `site_icon` não estiver definido no site.

Nenhum serviço externo para registar, nenhuma conta de programador Firebase / OneSignal para criar. As chaves VAPID que o plugin gera chegam: autenticam o seu servidor de aplicação junto dos serviços push FCM, Mozilla Push e WNS.

## Separador Adesão: pedido, estilos e acionadores

Este separador comanda o pedido de subscrição. Cinco estilos disponíveis, cada um posicionável e com tema:

- **Sino flutuante** (predefinido): pastilha discreta em baixo à direita ou em baixo à esquerda.
- **Banner** no topo ou no fundo da página.
- **Modal** centrada com sobreposição.
- **Slide-in** lateral.
- **Barra fixa** no topo.

O **pré-pedido suave** (recomendado) apresenta a sua mensagem personalizada antes do pedido nativo do navegador. Este mecanismo preserva a sua quota de adesão: no Chrome, recusar o pré-pedido não esgota a quota de pedidos nativos (×3 contra 1 sem pré-pedido).

Cinco acionadores configuráveis e combináveis:

- **Atraso** (em segundos) após o carregamento da página.
- **Scroll** em percentagem da página (0 = desativado).
- **Exit-intent** no movimento de saída do rato (apenas em desktop).
- **X páginas vistas** na sessão.
- **Adição ao carrinho** (captura o evento `added_to_cart` do WooCommerce).

Ative o **teste A/B do pedido** com um título e uma mensagem na variante B, e uma divisão configurável. A repartição é guardada em localStorage para garantir coerência entre sessões por visitante.

Depois de recusada, a permissão do navegador não pode voltar a ser pedida por script. Cuide do seu pré-pedido e não encadeie um pedido logo no primeiro scroll: nesse caso observam-se 70% de recusas, contra 20 a 30% com um pré-pedido acionado no momento certo.

## Separador Acionadores: os automatismos

Dez acionadores automáticos, todos ativáveis individualmente a partir do separador **Acionadores**. Cada um assenta no Action Scheduler para os envios diferidos, com um recuo síncrono se o Action Scheduler não estiver disponível.

### Carrinho abandonado

Três lembretes configuráveis, por predefinição 1 hora, 24 horas e 72 horas após o abandono. A deteção captura o evento `added_to_cart` dos utilizadores subscritos ao Push e agenda três ações `df_push_abandoned_cart` em intervalos crescentes. Os lembretes são cancelados automaticamente se a encomenda tiver sido feita entretanto.

### Regresso ao stock (back-in-stock)

Na página de produto, os seus visitantes subscritos podem entrar numa lista de espera por produto. Quando o WooCommerce dispara `woocommerce_product_set_stock_status` com regresso a _instock_, o plugin envia uma notificação à lista de espera do produto e depois esvazia-a.

### Descida de preço

O plugin mantém uma meta `_df_push_last_price` por produto. A cada atualização do produto, compara o preço antigo e o novo. Se a descida ultrapassar o **limiar mínimo em percentagem** configurado, é enviada uma notificação ao tema _Promoções_.

### Confirmação, expedição, avaliação

- **Confirmação de encomenda**: envio imediato em `woocommerce_thankyou` ao subscritor, se o identificador de utilizador corresponder.
- **Expedição**: deteta o número de seguimento na encomenda lendo sucessivamente as metas `_tracking_number`, `_wc_shipment_tracking_items` (WooCommerce Shipment Tracking) e `_aftership_tracking_number` (AfterShip). Se for encontrado um número, a notificação inclui-o na mensagem.
- **Pedido de avaliação**: agendado X dias após a passagem da encomenda ao estado _completed_ (atraso configurável).

### Aniversário, reativação, novo produto

- **Aniversário**: o cron diário `df_push_daily_lifecycle` lê o campo `billing_birthday` do WooCommerce e envia uma notificação aos subscritores que fazem anos nesse dia.
- **Reativação**: envio aos subscritores inativos há 30, 60 e 90 dias (janelas configuráveis em CSV: `30,60,90`).
- **Novo produto**: na publicação de um produto, é enviada uma notificação ao tema _Novidades_.

Cada acionador aceita um payload com modelo: `{firstname}`, `{product_name}`, `{product_price}`, `{old_price}`, `{order_number}`, `{tracking_number}`, `{category}`, `{discount_code}`. As variáveis são resolvidas no momento do envio, não no agendamento.

## Separador Campanhas: construtor visual, segmentação, teste A/B

Construa uma campanha manual em **DF Push > Campanhas > Nova campanha**. O construtor propõe uma pré-visualização em direto da notificação tal como aparecerá no dispositivo do subscritor.

- **Conteúdo**: título, mensagem, URL de destino, imagem principal, até dois botões de ação com etiqueta e URL próprios.
- **Notificação persistente** (opção _requireInteraction_): a notificação fica visível até haver interação.
- **Segmentação** por idioma, país, dispositivo, tema, e por comportamento RFM: encomendas mínimas, valor médio mínimo, dias de inatividade, categoria comprada. Os segmentos comportamentais são calculados com `wc_get_orders` no lançamento.
- **Teste A/B**: ative uma variante B (título e mensagem), com divisão configurável em percentagem. A repartição é aleatória por subscritor e determinística por identificador, para a coerência das análises.
- **Agendamento**: escolha a data e a hora, ou lance de imediato.
- **Modo de teste**: envie a campanha apenas aos administradores, a partir do construtor, antes do lançamento em produção.

O motor de envio fragmenta automaticamente o segmento, respeita as horas de silêncio no fuso horário do subscritor, aplica o limite de frequência configurado e elimina em tempo real os endpoints que devolvem 404 ou 410 (cancelamento do lado do navegador).

## Dashboard e análises

O painel **DF Push > Dashboard** agrega os seus KPI a 30 dias. O Chart.js é incluído localmente (sem dependência de CDN externo).

- **KPI**: subscritores ativos, taxa de adesão, envios, taxa de cliques (CTR), conversões, receita atribuída.
- **Série temporal a 30 dias**: envios versus cliques, uma linha por dia.
- **Mapa de calor 7 × 24**: melhores horários de envio em função dos cliques, cruzando dia da semana e hora do dia.
- **Funil por campanha**: enviada > entregue > clicada > convertida.
- **Receita atribuída**: uma janela de atribuição configurável (72 horas por predefinição) liga cada clique à primeira compra feita dentro da janela por esse subscritor.
- **Exportação CSV** de todos os eventos para auditoria RGPD ou integração BI.

## Página do cliente: A minha conta → Notificações

É acrescentada automaticamente uma página dedicada **A minha conta → Notificações** ao painel do WooCommerce. O cliente dispõe aí de quatro blocos:

- **Este dispositivo**: estado atual (ativado, desativado, bloqueado pelo navegador, não suportado), com botão Ativar ou Desativar neste dispositivo.
- **Todos os seus dispositivos**: lista dos dispositivos subscritos (tipo, navegador, idioma, última atividade), com cancelamento individual ou cancelamento total num clique.
- **As minhas preferências**: caixas de seleção para os temas nativos (Novidades, Promoções, Regresso ao stock). Gravação por REST com confirmação.
- **Histórico de notificações**: as 30 últimas notificações recebidas, com título, corpo, ícone, ligação e data.

O URL é `/my-account/df-push-notifications/`, adaptado à base de A minha conta do seu site. O rewrite endpoint é registado com a máscara `EP_ROOT | EP_PAGES`, com um reparador automático em `init:999` que deteta uma regra em falta (caso de um flush de permalinks concorrente) e volta a fazer flush automaticamente.

As ações do cliente (cancelamento, preferências) passam pelas rotas REST em `df-push/v1/account/*`, autenticadas por cookie e nonce `wp_rest`. Nenhuma ação pode ser feita noutra conta, mesmo em caso de manipulação do identificador do dispositivo no pedido.

## RGPD e registo de consentimento

A conformidade RGPD é tratada nativamente, não como acrescento cosmético. Cada adesão e cada cancelamento fica inscrito na tabela `dfpush_consent_log` com:

- Identificador do subscritor.
- Ação: _subscribe_ ou _unsubscribe_.
- IP com hash SHA-256 (o IP em claro nunca é guardado).
- User-agent.
- Data e hora em UTC.

Os WordPress Privacy Exporters e Erasers nativos estão ligados: um cliente pode pedir a exportação ou o apagamento dos seus dados pessoais a partir de **Ferramentas → Exportar dados pessoais** ou **Ferramentas → Apagar dados pessoais**. O plugin inclui então as subscrições, os temas, a caixa de entrada e o registo de consentimento na resposta, ou elimina-os consoante o pedido.

## Separador Definições: anti-spam e atribuição

Este separador centraliza os parâmetros de respeito pelos subscritores e a janela de atribuição:

- **Horas de silêncio** (quiet hours): intervalo durante o qual não é enviada qualquer notificação. Sensível ao fuso horário do subscritor (lido no dispositivo no momento da adesão através de `Intl.DateTimeFormat().resolvedOptions().timeZone`). Por predefinição, das 22h às 8h locais.
- **Limite de frequência**: número máximo de notificações por dia por subscritor. 0 = ilimitado.
- **Hora de envio inteligente**: otimiza a hora de envio por subscritor com base nos seus horários históricos de clique.
- **Janela de atribuição**: duração em horas entre um clique e uma encomenda para que a encomenda seja atribuída à notificação. 72 horas por predefinição.
- **Caixa de entrada no site**: ativa ou desativa o sino flutuante com o histórico das notificações no front-end.
- **Manifesto PWA**: ativa a geração do manifesto para tornar o site instalável em telemóvel.

## Separador Webhooks e API REST

O separador **Webhooks & API** cobre dois mecanismos de integração.

### Webhooks de saída

Configure um ou vários endpoints HTTP por evento. Três formatos disponíveis:

- **Slack**: payload `{ text }` compatível com os Incoming Webhooks do Slack.
- **Discord**: payload `{ content }` compatível com os Webhooks do Discord.
- **Generic**: payload JSON completo com event, timestamp e data, compatível com Zapier, n8n e Make.

Os eventos disponíveis: `subscriber.created`, `campaign.launched`, `notification.clicked`, `order.attributed`. Os pedidos são não bloqueantes (`wp_remote_post` com `blocking=false`) para nunca atrasar o envio principal.

### API REST

No namespace `df-push/v1`, o plugin expõe uma rota pública de envio com token: `POST /wp-json/df-push/v1/send` com o cabeçalho `X-DF-Push-Token`. O token pode ser regerado num clique a partir da administração.

```
curl -X POST https://o-seu-site.com/wp-json/df-push/v1/send
  -H "Content-Type: application/json"
  -H "X-DF-Push-Token: O_SEU_TOKEN"
  -d '{
    "title": "Promoção relâmpago",
    "body": "20% em todo o catálogo até à meia-noite",
    "url": "https://o-seu-site.com/promocoes",
    "segment": { "lang": "pt", "topic": "promos" }
  }'
```

Guarde este token como uma palavra-passe. Quem o tiver pode enviar notificações aos seus subscritores. Regere-o de imediato se suspeitar de comprometimento.

## Caixa de entrada no site, PWA e multilingue

Três funções complementares cobrem os casos em que o utilizador não autorizou o Push.

- **Caixa de entrada no site**: um sino flutuante (configurável no front-end) abre uma lista das últimas notificações recebidas pelo utilizador, lidas ou não, mesmo que nunca tenha autorizado o Push. Especialmente útil no Safari iOS anterior à 16.4 e nos utilizadores de PWA.
- **Manifesto PWA**: gerado dinamicamente em `/df-push-manifest.json` a partir do `site_icon` ou de um ícone personalizado. Filtro `df_push_manifest` disponível para ajustar theme color, display, scope e start_url.
- **Multilingue**: compatível com Polylang e WPML. As notificações são enviadas no idioma do subscritor (detetado na adesão), com recuo para o idioma predefinido do site. Os ficheiros `.po` e `.mo` em FR, EN, ES, DE e IT estão incluídos.

## Service Worker e arquitetura técnica

O Service Worker é servido por um ficheiro PHP autónomo no URL `/wp-content/plugins/df-push/sw.php`. Esta abordagem contorna por completo o routing do WordPress: sem qualquer hipótese de interferência com um plugin de cache, um canonical redirect ou outro handler de `template_redirect`.

O cabeçalho `Service-Worker-Allowed: /` é enviado na resposta para permitir o registo com o scope raiz (`scope: '/'`), apesar de o script viver em `/wp-content/`.

Do lado da base de dados, oito tabelas com prefixo `dfpush_`:

- `dfpush_subscribers`: subscritores e o respetivo endpoint Push.
- `dfpush_topic_subs`: associações tema ↔ subscritor.
- `dfpush_campaigns`: campanhas manuais com payload, segmento e agendamento.
- `dfpush_notifications`: registo das notificações individuais enviadas.
- `dfpush_events`: eventos em bruto (opt-in, sent, delivered, clicked, converted) para as análises.
- `dfpush_inbox`: cópia persistente das notificações para a caixa de entrada no site.
- `dfpush_stock_waitlist`: listas de espera de regresso ao stock.
- `dfpush_consent_log`: registo RGPD.

A **desinstalação** (remoção completa a partir de Plugins) elimina estas oito tabelas e limpa todas as opções. A simples desativação, essa, conserva os dados para uma reativação posterior.

## Hooks para programadores

O plugin expõe ações e filtros nos pontos-chave para estender o seu comportamento sem alterar o núcleo.

- `df_push_booted` (ação): acionada após o arranque do plugin, útil para registar extensões personalizadas.
- `df_push_payload_build` (filtro): alterar o payload JSON enviado ao serviço push antes da cifragem.
- `df_push_should_send` (filtro): interromper o envio com condições personalizadas (devolver _false_ para saltar).
- `df_push_segment_query` (filtro): enriquecer os critérios de segmentação comportamental.
- `df_push_webhook_payload` (filtro): ajustar os payloads dos webhooks de saída.
- `df_push_manifest` (filtro): alterar o manifesto PWA gerado.
- Ações registadas no Action Scheduler: `df_push_send_one`, `df_push_fan_out`, `df_push_abandoned_cart`, `df_push_review_request`, `df_push_dispatch_campaign`.

## FAQ e resolução de problemas

### O pedido de adesão não aparece

Três causas possíveis: a permissão do navegador já foi recusada (verifique nas definições do navegador), a permissão já foi concedida (o pedido deixa de fazer sentido), ou um acionador não foi atingido (atraso não decorrido, scroll insuficiente). Na consola JavaScript, execute `window.DFPush.isSubscribed()` para verificar o estado atual.

### A administração de Subscritores está vazia apesar de uma adesão bem-sucedida

Verifique na consola de rede que o pedido `POST /wp-json/df-push/v1/subscribe` devolve mesmo um código 200. A partir da versão 1.0.1, o plugin ressincroniza automaticamente qualquer `PushSubscription` existente com o servidor em cada carregamento de página, e regista qualquer erro de inserção na base de dados no `error_log`.

### O Service Worker devolve um erro de registo

Se o erro do navegador for «The script resource is behind a redirect» ou «Unexpected token '<'», teste diretamente o URL `https://o-seu-site.com/wp-content/plugins/df-push/sw.php`. Deve ver o código JavaScript do Service Worker com um `Content-Type: application/javascript` e o cabeçalho `Service-Worker-Allowed: /`. Se vir um HTML 403, verifique as regras htaccess que possam bloquear a execução direta de ficheiros PHP em `wp-content/plugins/`.

### As notificações não são recebidas em iOS

O Safari em iOS só suporta notificações Push desde a versão 16.4 e apenas nos sites instalados como PWA através do botão **Adicionar ao ecrã principal**. O manifesto PWA gerado pelo plugin facilita essa instalação. Se não visa especificamente o iOS, não é um problema: os outros navegadores recebem as notificações normalmente.

### Como migrar do OneSignal ou do Pusher

Os subscritores existentes nesses serviços de terceiros não são portáveis: a criptografia Push liga cada subscrição a um par único (chave VAPID do servidor, endpoint do navegador). Os seus visitantes terão de voltar a subscrever depois da passagem para o DataFirefly Push. Pode preparar a transição desativando o SDK antigo alguns dias antes e comunicando com um banner de pré-anúncio sobre a nova experiência.

### O que acontece na desinstalação?

A **desativação** simples conserva todas as tabelas e opções: pode reativar o plugin e retomar onde ficou. A **remoção completa** a partir de Plugins executa o `uninstall.php`, que elimina as oito tabelas `dfpush_`, limpa todas as opções do plugin (incluindo as chaves VAPID e o token de API) e desagenda os crons. Os permalinks são automaticamente atualizados no pedido seguinte.