Skip to main content
Este guia abrangente orienta você através da configuração e personalização de notificações web push usando o plugin WordPress do OneSignal versões 2.x.x. Se você está usando versão 3 ou superior, veja nosso guia WordPress v3+.
Este guia é especificamente para o plugin WordPress do OneSignal versão 2.x.x. Para versão 3+, consulte nossa documentação WordPress atualizada.

Pré-requisitos

  • Website WordPress com acesso de admin
  • HTTPS habilitado (necessário para notificações web push)
  • Conta OneSignal (gratuita em onesignal.com)

Passo 1: Escolha a Integração

Crie sua conta OneSignal em onesignal.com. Se este não for seu primeiro app, selecione New App/Website, nomeie seu app, selecione Web, e clique em “Next”.

Interface de seleção de plataforma mostrando opção Web

Selecione WordPress Plugin or Website Builder para continuar:

Opções de integração de web push com WordPress Plugin destacado

Passo 2: Configuração do Site

Configure as informações do seu site cuidadosamente pois estas configurações afetam todas as notificações:

Formulário de configuração de Site Setup com campos obrigatórios

FieldDescriptionRequirements
Site NameNome padrão exibido em notificações pushMantenha conciso para melhor exibição
Site URLURL completa do seu websiteDeve incluir http:// ou https:// e corresponder ao formato real da sua URL
Auto ResubscribeReinscreve automaticamente usuários que retornam (apenas HTTPS)Recomendado - Reduz atrito para usuários que limparam dados do navegador
Default Icon URLÍcone para prompts e notificaçõesDeve ser HTTPS, quadrado 256x256 pixels, formato PNG/JPG/GIF
Formato de URL Importante: Garanta que sua URL do Site corresponda exatamente a como usuários acessam seu site. URLs incompatíveis (www vs não-www, http vs https) podem causar problemas de subscription.

Passo 3: Configurações Avançadas de Push (Opcional)

OneSignal fornece certificados Safari Web Push sem custo. Apenas faça upload de certificados personalizados se você tiver requisitos específicos.

Configurações avançadas de push mostrando opções de upload de certificado Safari

Quando Usar Certificados Personalizados:
  • Você tem certificados Safari existentes
  • Sua organização requer gerenciamento específico de certificado
  • Você precisa de marca personalizada de certificado

Passo 4: Configure o Plugin WordPress

Instale o Plugin

Adicione o Plugin WordPress OneSignal do seu admin WordPress ou procurando “OneSignal” no diretório de plugins.

Configure Chaves API

Copie seu App ID e API Key do dashboard OneSignal:

Dashboard OneSignal mostrando localizações de App ID e API Key

Navegue para seu admin WordPress → OneSignal Push → aba Configure e cole as chaves:

Configuração do plugin WordPress mostrando campos de entrada de chave API

Habilite Prompts de Push

Ative o Slide Prompt e Subscription Bell para solicitar permissão dos visitantes:

Configurações de prompt mostrando opções de Slide Prompt e Subscription Bell

Salve sua configuração - isto é crítico para o plugin funcionar adequadamente.

Localização do botão Salvar na parte inferior da página de configuração

Passo 5: Teste Sua Configuração

Verifique a Instalação

  1. Visite seu website (você pode precisar limpar plugins de cache)
  2. Procure pelo OneSignal Slide Prompt e Subscription Bell
  3. Inscreva-se para testar o fluxo
  4. Verifique OneSignal Dashboard → Audience → Users para confirmar sua subscription

Envie Notificação de Teste

Navegue para OneSignal Dashboard → Messages → New Push para enviar sua primeira notificação e verificar que tudo funciona.
Solução de Problemas: Se prompts não aparecerem, verifique se notificações push estão habilitadas nas configurações do seu dispositivo e tente limpar o cache do seu navegador.

Passo 6: Configure Prompts de Notificação

Configure como e quando usuários veem prompts de subscription na seção Configure:

Subscription Bell

Um ícone persistente (geralmente no canto) que usuários podem clicar a qualquer momento para gerenciar seu status de subscription.

Slide Prompt

Um diálogo modal que aparece baseado nas suas configurações de tempo para solicitar permissão. Próximos Passos: Usuários tipicamente querem personalizar tempo e aparência do prompt. Veja a seção Personalizações Avançadas abaixo.

Passo 7: Notificações Automáticas de Post

Configuração Básica

Ao criar posts, você verá uma seção OneSignal. Marque Send notification on post publish para notificar inscritos:

Editor de post mostrando checkbox de notificação OneSignal

Auto-Habilitar Notificações

Para marcar automaticamente esta caixa para todos os novos posts:
  1. Vá para OneSignal PushAutomatic Notification Settings
  2. Habilite Automatically send a push notification when I create a post
  3. Salve configurações

Configurações de notificação automática mostrando opção de envio automático

Notificações de Boas-Vindas

Configure mensagens de boas-vindas opcionais enviadas imediatamente após usuários se inscreverem. Edite ou desabilite estas na seção Configure do seu plugin.
Limitação de Taxa: Múltiplas notificações para o mesmo post são limitadas a uma por minuto para prevenir spam.

Personalizações Avançadas

O plugin WordPress OneSignal carrega nosso Web Push SDK com suas opções configuradas. Você pode usar quaisquer APIs JavaScript do Web Push SDK para personalizar ainda mais a experiência.
Nota para Desenvolvedores: Esta seção requer conhecimento de JavaScript e PHP. Se você precisa de ajuda adicionando código ao seu site, considere usar plugins como Insert Headers and Footers ou Custom CSS & JS.

Personalizando Prompts de Subscription

Configuração Avançada de Prompt

Para personalização sofisticada de prompt incluindo atrasos, categorias e coleta de email:
Passo 1: Desabilite Prompts Padrão
Em OneSignal WordPress Plugin → Prompt Settings, DESLIGUE o Slide e Native Prompt (você pode manter o Bell habilitado).

Configurações de prompt mostrando Slide e Native prompts desabilitados

Passo 2: Habilite Inicialização Manual
Role para Advanced Settings e ative “Disable OneSignal initialization”, então Salve.

Configurações avançadas mostrando toggle de inicialização manual

Passo 3: Adicione JavaScript Personalizado
Adicione este código ao seu site (após o atraso de 3 segundos mostrado nos exemplos):
// Basic Delayed Prompt
setTimeout(function(){
  window._oneSignalInitOptions.promptOptions = {
    slidedown: {
      prompts: [
        {
          type: "push",
          autoPrompt: true,
          text: {
            actionMessage: "Get notified of new posts and updates!",
            acceptButton: "Yes",
            cancelButton: "No thanks",
          },
          delay: {
            timeDelay: 10, // Wait 10 seconds
            pageViews: 2,  // Show after 2 page views
          }
        }
      ]
    }
  }
  window.OneSignal = window.OneSignal || [];
  window.OneSignal.push(function() {
    window.OneSignal.init(window._oneSignalInitOptions);
  });
}, 3000);
// Category-Based Prompt
setTimeout(function(){
  window._oneSignalInitOptions.promptOptions = {
    slidedown: {
      prompts: [
        {
          type: "category",
          autoPrompt: true,
          text: {
            actionMessage: "Choose what notifications you'd like to receive:",
            acceptButtonText: "Subscribe",
            cancelButtonText: "Not now",
            positiveUpdateButton: "Save Preferences",
            negativeUpdateButton: "Cancel",
            updateMessage: "Update your notification preferences.",
          },
          categories: [
            {
              tag: "news",
              label: "Breaking News",
            },
            {
              tag: "sports",
              label: "Sports Updates",
            },
            {
              tag: "tech",
              label: "Technology News",
            }
          ]
        }
      ]
    }
  }
  window.OneSignal = window.OneSignal || [];
  window.OneSignal.push(function() {
    window.OneSignal.init(window._oneSignalInitOptions);
  });
}, 3000);

Prompts Específicos de Página

Método PHP do Lado do Servidor
Use o filtro onesignal_initialize_sdk para controlar inicialização baseado em propriedades de página.
Método JavaScript do Lado do Cliente
Habilite “Disable OneSignal initialization” e adicione JavaScript condicional para inicializar OneSignal apenas em páginas específicas.

Prompts Multi-Idioma

Para sites de idioma único, simplesmente traduza o texto na configuração do prompt. Para sites multi-idioma, use o método de inicialização manual acima e detecte o idioma da página para exibir texto apropriado.

Segmentação e Direcionamento de Usuário

Marcando Usuários

Categorize usuários com Data Tags para enviar notificações direcionadas:
// Tag users based on their interests
OneSignal.push(function() {
  OneSignal.sendTag("interest", "technology");
  OneSignal.sendTag("location", "california");
});

Direcionando Segmentos

Crie Segments no seu dashboard OneSignal usando filtros User Tag, então direcione-os com o filtro onesignal_send_notification:
<?php
add_filter('onesignal_send_notification', 'target_tech_users', 10, 4);

function target_tech_users($fields, $new_status, $old_status, $post) {
  // Only send to users interested in technology
  $fields['included_segments'] = array('Technology Enthusiasts');
  return $fields;
}

Imagens Destacadas em Notificações

Habilite Suporte de Imagem Destacada

Garanta que seu tema suporte imagens destacadas. Verifique o functions.php do seu tema para:
add_theme_support('post-thumbnails');

Configure Configurações de Imagem

Em OneSignal Push → Sent Notification Settings, ative as opções de imagem destacada desejadas:

Configurações de imagem destacada mostrando opções de ícone e imagem grande

Integração de Plugin de Terceiros

Tipos de Post Padrão

Habilite Automatically send a push notification when I publish a post from 3rd party plugins para tipos de post padrão.

Configurações de integração de plugin de terceiros

Tipos de Post Personalizados

Adicione tipos de post personalizados (separados por vírgula) ao campo Additional Custom Post Types:

Campo de configuração de tipos de post personalizados

Encontrando Tipos de Post Personalizados: Olhe a URL do seu navegador ao criar o tipo de post personalizado: https://seusite.com/wp-admin/post-new.php?post_type=seu_tipo_personalizado O parâmetro post_type mostra o nome a adicionar.

Integração de App Móvel

Método 1: Abertura Simples de Navegador Web

Habilite Send notifications additionally to iOS & Android platforms nas configurações do seu plugin WordPress.

Toggle de integração de plataforma móvel

Método 2: Deep Linking

Para comportamento de app móvel personalizado, desabilite a configuração acima e use este código PHP:
<?php
add_filter('onesignal_send_notification', 'send_to_mobile_apps', 10, 4);

function send_to_mobile_apps($fields, $new_status, $old_status, $post) {
  $fields['isAndroid'] = true;
  $fields['isIos'] = true;
  $fields['isAnyWeb'] = true;
  $fields['data'] = array("customkey" => $fields['url']);
  $fields['web_url'] = $fields['url'];
  unset($fields['url']); // Prevents browser opening on mobile

  return $fields;
}

Hooks e Filtros do Plugin WordPress

Posicionamento de Código

Coloque código PHP personalizado em wp-content/mu-plugins/ para prevenir que seja sobrescrito por atualizações.
Crie wp-content/mu-plugins/onesignal-custom.php com seu código personalizado.

onesignal_send_notification

Modifique parâmetros de notificação antes de enviar:
<?php
add_filter('onesignal_send_notification', 'customize_notification', 10, 4);

function customize_notification($fields, $new_status, $old_status, $post) {
  // Customize title and message
  $fields['headings'] = array("en" => "Breaking News!");
  $fields['contents'] = array("en" => "Check out our latest post");

  // Schedule for later
  $fields['send_after'] = "2024-12-25 09:00:00 GMT-0800";

  // Add action buttons
  $fields['web_buttons'] = array(
    array(
      "id" => "read-more",
      "text" => "Read More",
      "url" => get_permalink($post->ID)
    )
  );

  return $fields;
}

onesignal_initialize_sdk

Controle quando OneSignal inicializa:
<?php
add_filter('onesignal_initialize_sdk', 'control_initialization', 10, 1);

function control_initialization($settings) {
  // Only initialize on blog posts
  if (is_single() && get_post_type() == 'post') {
    return true;
  }
  return false;
}

onesignal_include_post

Force notificações para tipos de post específicos:
<?php
add_filter('onesignal_include_post', 'include_pages', 10, 3);

function include_pages($new_status, $old_status, $post) {
  // Send notifications when pages are published
  if ($post->post_type == "page" && $new_status == "publish") {
    return true;
  }
  return false;
}

onesignal_meta_box_send_notification_checkbox_state

Controle o estado padrão do checkbox de notificação:
<?php
add_filter('onesignal_meta_box_send_notification_checkbox_state', 'auto_check_checkbox', 10, 2);

function auto_check_checkbox($post, $settings) {
  // Always check the box for news category posts
  if (has_category('news', $post)) {
    return true;
  }
  return false;
}

Sites Mistos WordPress/Não-WordPress

Para sites com páginas WordPress e não-WordPress:
  1. Use Configuração com Código Personalizado no dashboard OneSignal
  2. Adicione este código a páginas não-WordPress:
<script src="https://cdn.onesignal.com/sdks/OneSignalSDK.js" async=""></script>
<script>
var OneSignal = window.OneSignal || [];
var initConfig = {
  appId: "YOUR_APP_ID_FROM_WORDPRESS_PLUGIN",
  notifyButton: {
    enable: true
  },
};
OneSignal.push(function () {
  OneSignal.SERVICE_WORKER_PARAM = {
    scope: '/wp-content/plugins/onesignal-free-web-push-notifications/sdk_files/'
  };
  OneSignal.SERVICE_WORKER_PATH = 'wp-content/plugins/onesignal-free-web-push-notifications/sdk_files/OneSignalSDKWorker.js'
  OneSignal.SERVICE_WORKER_UPDATER_PATH = 'wp-content/plugins/onesignal-free-web-push-notifications/sdk_files/OneSignalSDKWorker.js'
  OneSignal.init(initConfig);
});
</script>

Solução de Problemas

Problemas Comuns

Erro “No Recipients”

  • Causa: Tentar enviar múltiplas notificações para o mesmo post muito rapidamente
  • Solução: Aguarde pelo menos um minuto entre notificações para o mesmo post

Prompts Não Aparecem

  • Causa: Plugins de cache, configurações de navegador ou problemas de inicialização
  • Soluções:
    • Limpe todos os plugins de cache
    • Verifique permissões de notificação do navegador
    • Verifique que HTTPS está habilitado
    • Confirme que a configuração do plugin está salva

Aviso “Couldn’t load wp.data”

  • WordPress 5+ com Gutenberg: Pode indicar problemas de configuração - contate o suporte
  • WordPress 4.x: Seguro ignorar - este aviso não afeta a funcionalidade

Tipos de Post Personalizados Não Funcionam

  • Causa: Faltando meta dados necessários
  • Solução: Use o filtro onesignal_include_post para incluir explicitamente seu tipo de post

Notificações Não Agendando

  • Causa: Cron do WordPress ou conflitos de tema
  • Soluções:
    1. Use OneSignal Dashboard ou API para agendamento
    2. Implemente agendamento personalizado com filtro onesignal_send_notification
    3. Use integração Zapier para automação

Entradas de Banco de Dados

OneSignal cria estas entradas na sua tabela wp_postmeta:
EntryDescription
onesignal_meta_box_presentConfirma que OneSignal estava ativo quando o post foi publicado
onesignal_send_notificationRastreia envio de notificação
statusStatus HTTP da notificação (200 = sucesso)
response_bodyResposta API com ID de notificação e contagem de destinatários
recipientsNúmero de usuários que receberam a notificação

Obtendo Ajuda


Próximos Passos

Após completar esta configuração:
  1. Monitore Desempenho: Verifique seu dashboard OneSignal regularmente para crescimento de inscritos e métricas de engajamento
  2. Otimize Prompts: Experimente com diferentes tempos e mensagens de prompt
  3. Segmente Usuários: Implemente marcação para enviar notificações mais direcionadas
  4. Teste Completamente: Envie notificações de teste para diferentes dispositivos e navegadores
  5. Planeje Estratégia de Conteúdo: Desenvolva uma estratégia de notificação que adicione valor sem sobrecarregar usuários
Para recursos avançados como teste A/B, segmentação avançada e analytics detalhados, considere fazer upgrade para um plano pago do OneSignal.