WordPress Legacy Setup

This comprehensive guide walks you through setting up and customizing web push notifications using OneSignal WordPress plugin versions 2.x.x. If you’re using version 3 or higher, see our WordPress v3+ guide.

​

Prerequisites

• WordPress website with admin access
• HTTPS enabled (required for web push notifications)
• OneSignal account (free at onesignal.com)

​

Step 1: Choose Integration

Create your OneSignal account at onesignal.com. If this isn’t your first app, select New App/Website, name your app, select Web, and click “Next”.

Select WordPress Plugin or Website Builder to continue:

​

Step 2: Site Setup

Configure your site information carefully as these settings affect all notifications:

​

Step 3: Advanced Push Settings (Optional)

OneSignal provides Safari Web Push certificates at no cost. Only upload custom certificates if you have specific requirements.

When to Use Custom Certificates:

• You have existing Safari certificates
• Your organization requires specific certificate management
• You need custom certificate branding

​

Step 4: Configure WordPress Plugin

​

Install the Plugin

Add the OneSignal WordPress Plugin from your WordPress admin or by searching “OneSignal” in the plugin directory.

​

Configure API Keys

Copy your App ID and API Key from the OneSignal dashboard:

Navigate to your WordPress admin → OneSignal Push → Configure tab and paste the keys:

​

Enable Push Prompts

Activate the Slide Prompt and Subscription Bell to request permission from visitors:

Save your configuration - this is critical for the plugin to function properly.

​

Step 5: Test Your Setup

​

Verify Installation

1. Visit your website (you may need to clear cache plugins)
2. Look for the OneSignal Slide Prompt and Subscription Bell
3. Subscribe to test the flow
4. Check OneSignal Dashboard → Audience → Users to confirm your subscription

​

Send Test Notification

Navigate to OneSignal Dashboard → Messages → New Push to send your first notification and verify everything works.

​

Step 6: Configure Notification Prompts

Set up how and when users see subscription prompts in the Configure section:

​

Subscription Bell

A persistent icon (usually in the corner) that users can click anytime to manage their subscription status.

​

Slide Prompt

A modal dialog that appears based on your timing settings to request permission.

Next Steps: Users typically want to customize prompt timing and appearance. See the Advanced Customizations section below.

​

Step 7: Automatic Post Notifications

​

Basic Setup

When creating posts, you’ll see a OneSignal section. Check Send notification on post publish to notify subscribers:

​

Auto-Enable Notifications

To automatically check this box for all new posts:

1. Go to OneSignal Push → Automatic Notification Settings
2. Enable Automatically send a push notification when I create a post
3. Save settings

​

Welcome Notifications

Configure optional welcome messages sent immediately after users subscribe. Edit or disable these in the Configure section of your plugin.

​

Advanced Customizations

The OneSignal WordPress plugin loads our Web Push SDK with your configured options. You can use any Web Push SDK JavaScript APIs to customize the experience further.

​

Customizing Subscription Prompts

​

Advanced Prompt Setup

For sophisticated prompt customization including delays, categories, and email collection:

Step 1: Disable Default Prompts

In OneSignal WordPress Plugin → Prompt Settings, turn OFF the Slide and Native Prompt (you can keep the Bell enabled).

Step 2: Enable Manual Initialization

Scroll to Advanced Settings and toggle ON “Disable OneSignal initialization”, then Save.

Step 3: Add Custom JavaScript

Add this code to your site (after the 3-second delay shown in examples):

// 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);

​

Page-Specific Prompts

Server-Side PHP Method

Use the onesignal_initialize_sdk filter to control initialization based on page properties.

Client-Side JavaScript Method

Enable “Disable OneSignal initialization” and add conditional JavaScript to initialize OneSignal only on specific pages.

​

Multi-Language Prompts

For single language sites, simply translate the text in the prompt configuration.

For multi-language sites, use the manual initialization method above and detect the page language to display appropriate text.

​

User Segmentation and Targeting

​

Tagging Users

Categorize users with Data Tags to send targeted notifications:

// Tag users based on their interests
OneSignal.push(function() {
  OneSignal.sendTag("interest", "technology");
  OneSignal.sendTag("location", "california");
});

​

Targeting Segments

Create Segments in your OneSignal dashboard using User Tag filters, then target them with the onesignal_send_notification filter:

<?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;
}

​

Featured Images in Notifications

​

Enable Featured Image Support

Ensure your theme supports featured images. Check your theme’s functions.php for:

add_theme_support('post-thumbnails');

​

Configure Image Settings

In OneSignal Push → Sent Notification Settings, toggle on the desired featured image options:

​

Third-Party Plugin Integration

​

Standard Post Types

Enable Automatically send a push notification when I publish a post from 3rd party plugins for standard post types.

​

Custom Post Types

Add custom post types (comma-separated) to the Additional Custom Post Types field:

Finding Custom Post Types: Look at your browser’s URL when creating the custom post type: https://yoursite.com/wp-admin/post-new.php?post_type=your_custom_type

The post_type parameter shows the name to add.

​

Mobile App Integration

​

Method 1: Simple Web Browser Opening

Enable Send notifications additionally to iOS & Android platforms in your WordPress plugin settings.

​

Method 2: Deep Linking

For custom mobile app behavior, disable the above setting and use this PHP code:

<?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;
}

​

WordPress Plugin Hooks and Filters

​

Code Placement

Create wp-content/mu-plugins/onesignal-custom.php with your custom code.

​

onesignal_send_notification

Modify notification parameters before sending:

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

Control when OneSignal initializes:

<?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 notifications for specific post types:

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

Control the default state of the notification checkbox:

<?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;
}

​

Mixed WordPress/Non-WordPress Sites

For sites with both WordPress and non-WordPress pages:

1. Use Custom Code Setup in OneSignal dashboard
2. Add this code to non-WordPress pages:

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

​

Troubleshooting

​

Common Issues

​

”No Recipients” Error

• Cause: Trying to send multiple notifications for the same post too quickly
• Solution: Wait at least one minute between notifications for the same post

​

Prompts Not Appearing

• Cause: Cache plugins, browser settings, or initialization issues
• Solutions:
  • Clear all cache plugins
  • Check browser notification permissions
  • Verify HTTPS is enabled
  • Confirm plugin configuration is saved

​

”Couldn’t load wp.data” Warning

• WordPress 5+ with Gutenberg: May indicate setup issues - contact support
• WordPress 4.x: Safe to ignore - this warning doesn’t affect functionality

​

Custom Post Types Not Working

• Cause: Missing required meta data
• Solution: Use the onesignal_include_post filter to explicitly include your post type

​

Notifications Not Scheduling

• Cause: WordPress cron or theme conflicts
• Solutions:
  1. Use OneSignal Dashboard or API for scheduling
  2. Implement custom scheduling with onesignal_send_notification filter
  3. Use Zapier integration for automation

​

Database Entries

OneSignal creates these entries in your wp_postmeta table:

​

Getting Help

• Plugin Issues: Check Troubleshooting WordPress Web Push
• General Support: Contact support@onesignal.com
• Plugin Source: Available on GitHub

​

Next Steps

After completing this setup:

1. Monitor Performance: Check your OneSignal dashboard regularly for subscriber growth and engagement metrics
2. Optimize Prompts: Experiment with different prompt timing and messaging
3. Segment Users: Implement tagging to send more targeted notifications
4. Test Thoroughly: Send test notifications to different devices and browsers
5. Plan Content Strategy: Develop a notification strategy that adds value without overwhelming users

For advanced features like A/B testing, advanced segmentation, and detailed analytics, consider upgrading to a paid OneSignal plan.