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

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.

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.

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.

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.

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" }
  }'

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.