Overview

This release marks a significant upgrade by streamlining the setup & configuration process. With Version 3+, you can handle all your prompt settings in one place -- the OneSignal Dashboard. For the older version 2.x.x WordPress docs, see WordPress Legacy plugin.

New in WordPress Plugin version 3+:

• 🚀 Upgrades the OneSignal Web SDK from version 15 to 16.
• 💬 Setup more new prompts within the OneSignal dashboard, including the following. No custom code is required anymore to configure these.
  • Category Prompt
  • Email/Phone Slide Prompt
  • Custom Link Prompt.
• ⏩ When publishing a new post, check the "Send notification when post is published" box to send a push notification.
• 🧑‍🤝‍🧑 Choose which audience segment should receive notifications for each post.
• 📑 Web Topics are included by default.
• 📲 Send to mobile app subscribers, with an option to direct them to a different URL (Deep Link).

Requirements

• OneSignal account
• OneSignal App ID and REST API Key (Keys and IDs)

Setup

1. Navigate to your OneSignal dashboard WordPress config

Login to onesignal.com and open your OneSignal dashboard. Navigate to Settings > Push & In-App > Web Settings > Wordpress Plugin or Website Builder and select WordPress.

2. Configure your WordPress site setup

Add your site details:

• Site Name: This is used as the default title of your web push notifications if no title is provided.
• Site URL: This must be the exact origin (URL) of your site. For example, if your site is https://mydomain.com, don’t use https://www.mydomain.com. Follow the Same-origin policy for more details.
• Local Testing: Developers, refer to our Local Testing Guide if you are testing on localhost.
• Auto Resubscribe (Recommended): Allows users who clear their browser data/cache to be automatically resubscribed when they return to your site. They will not be prompted again unless they turn off push permissions.
• Default Icon URL (Recommended): This icon is used for web push notifications and prompts. It should be a square 256x256 px PNG or JPG file.

3. Permission prompt setup

Click Add Prompt to select either the Push Prompt or Email/Phone Prompt. You can set all of them up but only one at a time.

Push prompts

This is where you can add the Slide, Category, Bell, Custom Link and Native prompts. See Web permission prompts for more details on each.

Email/Phone prompt

You can ask for the user's email address and/or phone number if you want to send email and/or SMS using OneSignal. This must be setup and you can't send email or SMS using the WordPress plugin but using our dashboard. See Email setup and/or SMS setup for details.

4. Welcome notification (optional)

Send a push immediately after the user subscribes to the website the first time. This is a good opportunity to thank them for subscribing and gives the user an example of how web push notifications work.

Advanced Push Settings

This is for setting up the Web SDK setup directly. You can skip this for now and click Save.

Configure WordPress Plugin

Copy-paste the APP ID and API Key into the OneSignal WordPress plugin so they match.

Click Finish and Save Settings to complete setup.

Complete migration in WordPress

If you upgraded from a previous version of our WordPress plugin, then follow this guide, otherwise, skip to the next section.

As soon as you save your configuration in the OneSignal.com dashboard, navigate back to WordPress to select "Migration Completed" and complete your plugin upgrade.

❗️

Ensure you select "Migration Completed"

Quickly complete these steps to avoid users missing any notifications.

Publish a post to send a notification

While creating a Post in WordPress, you should see a metabox for OneSignal Push Notifications. Ensure Send notification when post is published, is checked. You can send it to all subscribers or choose a specific audience segment to target. You can create and manage your segments in the OneSignal Dashboard > Audience > Segments.

By default, a notification will automatically use the post's title and an excerpt of the content. It will also include an image if there is a featured image. However, you can customize the Title and Content of a notification by checking Customize notification content. You can also customize the Mobile URL, which is the link mobile users will receive.

When you publish the post, a notification will be sent.

👍

WordPress Setup Complete!

You have successfully setup the OneSignal WordPress plugin!

FAQ

How do I send push notifications to my mobile app subscribers?

If you also have a mobile app set up in OneSignal that's separate from your Website, you can select Send notification to Mobile app subscribers in the plugin settings screen to include subscribers to your mobile app in your audience.

In the OneSignal Push Notifications metabox, you can choose a different URL for your Mobile app subscribers (Deep Link). If you do not include a different URL, it will direct them to your Website instead of a specific page of your app.

Why do my prompts not appear to be working after the migration?

If you have caching rules set up on your WordPress site (e.g. .htaccess file), this may delay seeing the results of the migration when testing. Disable the browser cache to force updated files to be loaded.

To disable cache, right-click anywhere on your WordPress site to open "Inspect" > Network tab in your developer console.

"A bad HTTP response code (404) was received when fetching the script." / service worker failed

This occurs when you have saved your configurations in the dashboard but have not yet selected "Migration Completed" in the WordPress plugin. Make sure you've selected "Migration Completed" in the WordPress Plugin to complete your upgrade.