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”.
Selecione WordPress Plugin or Website Builder para continuar:

Passo 2: Configuração do Site

Configure as informações do seu site cuidadosamente pois estas configurações afetam todas as notificações:
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.
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:
Navegue para seu admin WordPress → OneSignal Push → aba Configure e cole as chaves:

Habilite Prompts de Push

Ative o Slide Prompt e Subscription Bell para solicitar permissão dos visitantes:
Salve sua configuração - isto é crítico para o plugin funcionar adequadamente.

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:

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

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).
Passo 2: Habilite Inicialização Manual
Role para Advanced Settings e ative “Disable OneSignal initialization”, então Salve.
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:

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.

Tipos de Post Personalizados

Adicione tipos de post personalizados (separados por vírgula) ao campo Additional Custom Post Types:
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.

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.