Como Configurar Notificações Push do Webpushr para WordPress

Webpushr é uma plataforma de notificações push para web que entrega notificações em tempo real aos utilizadores que optaram por recebê-las, mesmo quando esses utilizadores já navegaram para fora do seu site. Ao contrário do email ou SMS, o push web não requer informações de contacto pessoais — os subscritores recebem notificações diretamente através do sistema de notificações nativo do browser via Web Push Protocol e a Push API.

Este guia percorre o processo de configuração completo: desde a criação de conta e configuração do plugin WordPress até à segmentação avançada, automação baseada em gatilhos e análise de subscritores. Também aborda casos técnicos específicos — conflitos de service worker, requisitos HTTPS, lacunas de compatibilidade com iOS e considerações de desempenho — que a maioria dos tutoriais ignora completamente.

Pré-requisitos Antes de Começar

Antes de aceder ao painel WordPress, verifique se o seu ambiente cumpre os seguintes requisitos obrigatórios:

• HTTPS é obrigatório. A Push API e os service workers estão restritos a origens seguras. Um site a correr em HTTP simples não pode registar um service worker e, portanto, não pode entregar notificações push web. Se o seu site ainda não estiver protegido, precisa de um certificado SSL válido — a AlexHost fornece Certificados SSL que cobrem este requisito.
• WordPress 5.0 ou superior é recomendado para compatibilidade total com o editor de blocos Gutenberg com a meta box do Webpushr.
• PHP 7.4 ou superior no lado do servidor para evitar avisos de funções obsoletas que podem silenciosamente interromper a inicialização do plugin.
• Consciência do suporte de browsers: Chrome, Firefox e Edge em desktop e Android suportam o Web Push Protocol. O Safari no macOS adicionou suporte no Safari 16 (macOS Ventura). O iOS Safari adicionou suporte limitado no iOS 16.4 apenas para PWAs na tela inicial — o push web padrão baseado em browser no iOS continua a ser pouco fiável no momento desta escrita.
• Sem service workers em conflito. Se já utiliza um plugin PWA ou outro serviço de notificações push, os seus service workers podem entrar em conflito com os do Webpushr. Audite os seus service workers ativos em chrome://serviceworker-internals/ antes de prosseguir.

Passo 1: Criar e Configurar a Sua Conta Webpushr

Aceda a webpushr.com e registe uma nova conta. Durante a integração, ser-lhe-á pedido o domínio do seu site. Introduza o domínio exato tal como aparece na barra de endereço do seu browser, incluindo o prefixo www ou a sua ausência — este valor é utilizado para definir o âmbito do service worker e incompatibilidades causarão falhas de subscrição.

Após o registo, o Webpushr fornece duas credenciais críticas:

• API Key — utilizada pelo plugin WordPress para autenticar chamadas à REST API para envio de notificações.
• Auth Token — utilizado para pedidos à API do lado do servidor se posteriormente criar integrações personalizadas.

Localize ambos os valores em Account > API Keys no painel do Webpushr e guarde-os de forma segura. A API Key não é um segredo no sentido tradicional (está incorporada em pedidos do lado do cliente), mas o Auth Token deve ser mantido privado.

Limites do Plano Gratuito vs. Pago do Webpushr

Para a maioria dos pequenos sites WordPress, o nível gratuito é suficiente para validar o canal antes de se comprometer com um plano pago.

Passo 2: Instalar o Plugin WordPress do Webpushr

Inicie sessão no painel de administração do WordPress e siga este caminho:

1. Vá a Plugins > Adicionar Novo.
2. Pesquise por Webpushr.
3. Localize o plugin oficial publicado pela Webpushr Inc. — verifique o nome do editor para evitar instalar um plugin com nome semelhante.
4. Clique em Instalar Agora e depois em Ativar.

Em alternativa, instale via WP-CLI se gerir o WordPress a partir da linha de comandos:

wp plugin install webpushr-web-push-notifications --activate

Após a ativação, um novo item de menu Webpushr aparece na navegação lateral esquerda do WordPress.

O Que o Plugin Faz ao Nível do Servidor

Compreender a arquitetura do plugin ajuda-o a resolver problemas de forma inteligente. Na ativação, o plugin:

1. Regista uma regra de reescrita para servir o ficheiro do service worker (webpushr-sw.js) a partir da raiz do site. Isto é crítico — os service workers devem ser servidos a partir do âmbito raiz para controlar toda a origem.
2. Injeta um fragmento de JavaScript em cada página front-end via wp_enqueue_scripts que carrega o SDK do Webpushr e regista o service worker.
3. Conecta-se às ações WordPress publish_post e publish_page para acionar notificações push automáticas quando o conteúdo é publicado.

Se o seu plugin de cache armazena agressivamente o ficheiro do service worker, os subscritores podem receber payloads push desatualizados ou não conseguir registar-se. Exclua webpushr-sw.js das suas regras de cache.

Passo 3: Conectar o Plugin à Sua Conta Webpushr

Navegue até Webpushr > Definições no seu painel WordPress. Verá um campo com o rótulo API Key. Cole a API Key que obteve do painel do Webpushr no Passo 1.

Clique em Guardar Alterações. O plugin fará um pedido de validação à API do Webpushr. Se a chave for válida, aparece uma confirmação de sucesso. Se vir um erro:

• Confirme que não há espaços em branco no início ou no fim da chave colada.
• Verifique se o seu servidor consegue fazer pedidos HTTPS de saída para api.webpushr.com. Algumas configurações de VPS reforçadas bloqueiam ligações de saída por padrão. Num servidor Linux, teste com:

curl -I https://api.webpushr.com

Uma resposta 200 OK ou 301 confirma a conectividade. Se a ligação expirar, verifique as suas regras de firewall com iptables -L OUTPUT ou a ACL de rede do seu fornecedor de alojamento.

Se estiver a correr o WordPress num ambiente de Alojamento VPS, tem controlo total sobre as regras de firewall e pode adicionar o endpoint da API do Webpushr à lista de permissões diretamente.

Passo 4: Configurar o Prompt de Opt-In

O prompt de opt-in é o diálogo de permissão do browser que pede aos utilizadores para permitir notificações. O diálogo de permissão nativo do browser não pode ser estilizado — é renderizado pelo próprio browser. No entanto, o Webpushr fornece um prompt de pré-permissão (uma sobreposição personalizada que aparece antes do diálogo nativo) que pode personalizar completamente.

Configure o prompt de pré-permissão no painel do Webpushr em Settings > Opt-in Prompt:

• Estilo do prompt: Escolha entre um widget de sino, uma barra superior, uma caixa deslizante ou um modal personalizado.
• Texto do prompt: Escreva um texto que comunique claramente o valor de subscrever. Prompts vagos como “Permitir notificações?” têm consistentemente um desempenho inferior a prompts que especificam o que os subscritores receberão, como “Seja notificado instantaneamente quando publicarmos novos avisos de segurança.”
• Atraso do prompt: Defina um atraso (em segundos ou visualizações de página) antes de mostrar o prompt. Mostrá-lo imediatamente no carregamento da página produz taxas de opt-in mais baixas do que esperar até que um utilizador tenha interagido com pelo menos um conteúdo.
• Intervalo de re-prompt: Defina quantos dias devem passar antes de um utilizador que dispensou o prompt o ver novamente. Re-prompts agressivos prejudicam a experiência do utilizador e aumentam a taxa de rejeição.

Referências de Taxa de Opt-In por Tipo de Prompt

Os prompts contextuais — mostrados após um utilizador completar uma ação significativa como ler um artigo até ao fim — superam consistentemente todas as outras abordagens.

Passo 5: Configurar as Definições de Entrega de Notificações

Push Automático na Publicação de Post

Em Webpushr > Definições, o botão Auto-Push Notification controla se uma notificação push é acionada automaticamente sempre que publica um post. Quando ativado, o Webpushr obtém o título do post, o excerto e o URL da imagem em destaque e constrói automaticamente o payload da notificação.

Caso específico: Se utilizar um fluxo de trabalho de staging para produção onde os posts são importados ou o seu estado é alterado programaticamente (por exemplo, via WP-CLI ou um script de migração), o hook publish_post será acionado para cada post importado, potencialmente inundando os seus subscritores com dezenas de notificações em segundos. Desative o auto-push antes de executar importações em massa:

wp option update webpushr_auto_push 0

Reative-o após a conclusão da importação.

Push Manual a partir do Editor de Posts

Para controlo granular, desative o auto-push globalmente e utilize a meta box do Webpushr por post no editor de posts. Esta meta box aparece abaixo do editor de conteúdo principal e expõe os seguintes controlos:

• Enviar notificação push: Uma caixa de verificação que, quando marcada, coloca uma notificação em fila na publicação ou atualização.
• Título personalizado da notificação: Substitua o título do post por um título mais apelativo para a notificação.
• Mensagem personalizada da notificação: Substitua o excerto gerado automaticamente.
• URL personalizado da notificação: Redirecione os subscritores para uma página de destino específica em vez do permalink do post — útil para campanhas promocionais.
• Ícone personalizado da notificação: Substitua o ícone padrão do site por uma imagem específica da campanha.

Anatomia do Payload de Notificação

Um payload de notificação push web consiste em:

• title — exibido a negrito no topo da notificação.
• body — o texto descritivo abaixo do título.
• icon — uma imagem quadrada (recomendado 192×192 px) mostrada ao lado da notificação.
• image — uma imagem de banner grande mostrada abaixo do corpo em plataformas suportadas (Chrome no Android, Chrome no Windows).
• badge — um pequeno ícone monocromático mostrado na barra de estado do Android.
• url — o URL de destino quando o utilizador clica na notificação.
• actions — até dois botões de ação com rótulos e URLs personalizados (suportado no Chrome e Edge).

Manter o title abaixo de 50 caracteres e o body abaixo de 120 caracteres evita truncagem na maioria das plataformas.

Passo 6: Testar Notificações Push de Ponta a Ponta

Testar na mesma sessão de browser onde está autenticado no WordPress não lhe dará uma imagem precisa da experiência do subscritor. Utilize um perfil de browser separado ou uma janela de navegação privada:

1. Abra o seu site numa janela privada/de navegação anónima.
2. O prompt de pré-permissão deve aparecer após o atraso configurado.
3. Clique na chamada para ação do prompt e depois clique em Permitir no diálogo de permissão nativo do browser.
4. Regresse ao seu painel WordPress e publique um post de teste, ou utilize o botão Send Test Notification no painel do Webpushr.
5. Verifique se a notificação aparece com o título, corpo, ícone corretos e que ao clicar nela navega para o URL correto.

Modos de falha comuns durante os testes:

• A notificação não aparece: Verifique se as notificações do browser não estão bloqueadas ao nível do sistema operativo (Windows Focus Assist, macOS Não Incomodar, canais de notificação Android).
• Service worker não está a registar: Abra DevTools > Application > Service Workers e confirme que webpushr-sw.js está listado como ativo. Se aparecer como “em espera”, outro service worker está a bloquear a ativação.
• Ícone não está a carregar: O URL do ícone deve ser absoluto (começando com https://) e a imagem deve ser servida com cabeçalhos CORS permissivos se alojada numa CDN.

Passo 7: Funcionalidades Avançadas — Segmentação, Agendamento e Gatilhos

Segmentação de Audiência

O motor de segmentação do Webpushr permite-lhe etiquetar subscritores com base em:

• Segmentos baseados em URL: Etiquete automaticamente subscritores que visitam URLs ou padrões de URL específicos (por exemplo, todos os utilizadores que visitam /category/security/ são etiquetados como security-readers).
• Atributos personalizados: Passe pares chave-valor arbitrários via SDK JavaScript para construir segmentos baseados em propriedades do utilizador que a sua aplicação já rastreia.
• Segmentos de envolvimento: O Webpushr rastreia automaticamente os timestamps da última visita, permitindo-lhe criar campanhas de reengajamento direcionadas a subscritores que não receberam uma notificação há 30+ dias.

A segmentação requer um plano pago e é configurada no painel do Webpushr em Segments.

Notificações Agendadas

O agendamento permite-lhe compor uma notificação agora e entregá-la numa data e hora futuras, com suporte de fuso horário. Isto é particularmente valioso para:

• Promoções sensíveis ao tempo com um prazo fixo.
• Conteúdo publicado fora dos horários de pico de tráfego que pretende entregar durante janelas de alto envolvimento.
• Notificações de resumo recorrentes (por exemplo, resumos semanais).

Notificações Personalizadas Baseadas em Gatilhos

Os gatilhos personalizados acionam notificações com base em eventos JavaScript no seu site. Por exemplo, pode acionar uma notificação 24 horas após um utilizador abandonar um carrinho de compras, ou quando um utilizador atinge uma profundidade de scroll específica. Os gatilhos são configurados via SDK JavaScript do Webpushr e requerem trabalho de desenvolvimento personalizado além das capacidades padrão do plugin WordPress.

Testes A/B do Texto de Notificação

Nos planos pagos, o Webpushr suporta testes divididos de títulos e corpo de notificações em segmentos de subscritores. Execute testes A/B para determinar qual mensagem gera taxas de clique mais elevadas antes de lançar uma campanha completa.

Passo 8: Monitorizar Análises de Subscritores

O painel do Webpushr fornece as seguintes métricas:

• Total de subscritores: Contagens de endpoints ativos, cancelados e expirados.
• Taxa de entrega: Percentagem de notificações enviadas que foram entregues com sucesso ao serviço push do browser (FCM para Chrome/Edge, Mozilla Autopush para Firefox).
• Taxa de clique (CTR): Percentagem de notificações entregues que resultaram num clique.
• Crescimento de subscritores ao longo do tempo: Tendências diárias e semanais de aquisição de subscritores.

Nota técnica importante sobre “entregue” vs. “recebido”: Uma notificação é marcada como entregue quando o serviço push do browser (por exemplo, FCM da Google) aceita o payload. Se o dispositivo do utilizador estiver offline, o FCM coloca a notificação em fila e entrega-a quando o dispositivo se reconectar — mas apenas dentro da janela TTL (Time to Live) que configurar. O TTL padrão é 28 dias. Para notificações sensíveis ao tempo, defina um TTL mais curto para evitar entregar conteúdo desatualizado.

Matriz de Compatibilidade de Plataformas e Browsers

“Suporte total” significa que o Web Push Protocol, os service workers e as ações de notificação são todos suportados. Os utilizadores iOS em sessões de browser padrão permanecem fora do alcance do push web, o que representa uma lacuna significativa de audiência para sites com forte presença móvel.

Considerações de Infraestrutura de Alojamento

A entrega de notificações push web é em grande parte gerida por serviços push de terceiros (FCM, Mozilla Autopush), pelo que o débito bruto do seu servidor não é um bottleneck para a entrega. No entanto, o seu ambiente de alojamento afeta:

• Velocidade de servir o service worker: O ficheiro webpushr-sw.js deve ser obtido rapidamente em cada carregamento de página para que os browsers verifiquem se o service worker está atualizado. Um servidor lento aumenta o Time to First Byte (TTFB) para este ficheiro.
• Tempo de resposta da API: Quando um novo post é publicado, o plugin faz uma chamada API síncrona ao Webpushr. Em alojamento partilhado com limites restritivos de ligações de saída, esta chamada pode expirar e falhar silenciosamente.
• Fiabilidade de webhooks: Se configurar webhooks do Webpushr para notificar o seu servidor de eventos de subscrição, o seu servidor deve aceitar de forma fiável pedidos POST de entrada.

Correr o WordPress num VPS com cPanel dá-lhe o controlo para ajustar os timeouts de execução PHP, configurar regras de firewall de saída e monitorizar a entrega do service worker sem as restrições dos ambientes partilhados. Para sites de alto tráfego onde as campanhas de notificações push geram picos significativos de tráfego concorrente, um Servidor Dedicado garante que a sua origem consegue absorver a carga resultante dos cliques sem throttling.

Para equipas que gerem múltiplas propriedades WordPress, o Alojamento de Email combinado com o Webpushr cria uma estratégia de reengajamento em dois canais — push para imediatismo, email para profundidade.

Matriz de Decisão Técnica: Quando Usar Webpushr vs. Alternativas

O nível gratuito do Webpushr é mais limitado do que o do OneSignal, mas a sua implementação de service worker é notavelmente mais limpa e menos propensa a conflitos com outros plugins WordPress — uma vantagem prática em instalações WordPress complexas.

Lista de Verificação Prática Antes de Entrar em Produção

• HTTPS está ativo e o certificado SSL é válido e não é autoassinado.
• O service worker webpushr-sw.js está acessível em https://yourdomain.com/webpushr-sw.js e retorna um estado 200.
• O ficheiro do service worker está excluído das regras de cache do seu plugin de cache.
• O atraso do prompt de opt-in está definido para pelo menos 5 segundos ou uma visualização de página.
• O auto-push está desativado se executar importações em massa agendadas ou migrações de conteúdo.
• Uma notificação de teste foi recebida de ponta a ponta numa sessão de browser limpa.
• As dimensões do ícone de notificação são 192×192 px e o URL é HTTPS absoluto.
• O TTL está configurado adequadamente para a sensibilidade temporal do seu conteúdo.
• A linha de base de análise está registada antes da sua primeira campanha para ter um ponto de comparação significativo.
• Política de privacidade/GDPR atualizada para divulgar a recolha de dados de notificações push.

FAQ

O Webpushr funciona sem HTTPS?

Não. A Web Push API e os service workers estão restritos a origens seguras pela especificação do browser. Qualquer site a correr em HTTP não pode registar um service worker e, portanto, não pode enviar ou receber notificações push web. Um certificado SSL é um requisito técnico obrigatório, não uma boa prática opcional.

Por que razão as minhas notificações push não estão a ser entregues a alguns subscritores?

As causas mais comuns são: o dispositivo do subscritor estava offline além da janela TTL da notificação; o utilizador revogou as permissões de notificação ao nível do browser ou do sistema operativo; ou o endpoint do serviço push do browser (FCM, Mozilla Autopush) retornou um registo expirado ou inválido. O painel do Webpushr marca estes como entregas “falhadas” e remove automaticamente os endpoints que retornam uma resposta 410 Gone, que é o comportamento correto de acordo com a especificação do Web Push Protocol.

Posso enviar notificações push para utilizadores iOS?

A partir do iOS 16.4, o push web é suportado apenas para Progressive Web Apps (PWAs) que foram adicionadas ao ecrã inicial. Os utilizadores que navegam no seu site no Safari ou em qualquer outro browser iOS sem o adicionar ao ecrã inicial não receberão notificações push web. Esta é uma restrição ao nível da plataforma imposta pela Apple, não uma limitação do Webpushr.

O service worker do Webpushr vai entrar em conflito com o meu PWA existente ou plugin de cache?

Pode. Apenas um service worker pode controlar um determinado âmbito de cada vez. Se um plugin PWA (por exemplo, Super PWA) ou outro serviço push já registou um service worker no âmbito raiz, o service worker do Webpushr ficará em fila num estado “em espera” e nunca será ativado. A resolução é utilizar um service worker que importe ambos os scripts, ou escolher um único fornecedor de push e desativar os outros. Verifique chrome://serviceworker-internals/ para auditar todos os workers registados no seu domínio.

Desativar o plugin Webpushr cancela a subscrição dos meus subscritores existentes?

Não. Desativar o plugin remove o SDK JavaScript do seu front-end, o que impede novas subscrições e para as notificações automáticas. No entanto, os registos de endpoints push existentes permanecem válidos no browser até que o utilizador revogue explicitamente a permissão ou o endpoint expire. Se reativar o plugin com a mesma API Key, esses subscritores serão imediatamente acessíveis novamente.